Repository navigation
Releases
trainctl 0.9.0: corpus-checked running engine, one view layout, session plan by default
trainctl 0.9.0 brings a running engine checked against a coaching corpus, one row layout for every view, workout-level review from laps, and the session plan as the default data model. It collects four stages of work since 0.6.0.
Highlights
A running engine measured, not guessed
- Season shape checked against a coaching corpus. A matrix of 576 synthetic profiles (base volume × days × goal × horizon × time budget) generates plans without shape violations: the long run stays the longest session, no single session carries the week, easy running stays at or above 75%.
- A long-run track that grows by at most 2 km per loading week, and accents that progress through the season (J-8), with a 1000/400/200 m ladder in the peak phase.
- Weekly time budget caps the peak of the macrocycle instead of trimming week by week, so deloads and the taper stay lighter than the weeks around them.
- Return after a break.
trainctl log --to … --reason illness|injury|travel|otherrecords a break, andadaptproposes a return block to approve (R-5 after illness, R-11 after a layoff, no volume proposal after an injury). trainctl checkreports season-shape issues;trainctl rulesexplains every rule the engine cites, with its source.
Views on one row layout
trainctl season: the whole season, one week per row, with accents and the long run.week,today,PLAN.mdand the printable sheet share the same session rows;--fullbrings back the full cards.reviewagainst the targets: laps from FIT, TCX or intervals.icu are matched to the planned repetitions, with paces and the share within range. Auto laps are reported as such; heart rate is never judged.- View options: miles (
units: imperial), Polish club notation (notation: club) and a heart-rate ceiling for easy and long runs fromhrMaxandsex. Pace stays the target.
One data model
trainctl initwrites the session-plan profile (schema 2). A running profile with therunningblock uses the full running engine; cycling and swimming live in the same file.- Running-plan parity. In a running workspace on schema 2,
why,status,review,adapt,deskand break logging behave exactly as in the running plan, and proposals are applied with--apply. - Structured running steps. Warm-up, repetitions with a pace range and recovery, strides, hills and progression thirds reach the FIT file and the intervals.icu workout as real steps, each with the RPE range of its segment.
Upgrade notes
- The first
trainctl planafter updating rewrites future days of an existing plan. Past, logged, pinned and approved days stay as they are. Runtrainctl difffirst to preview the change. - New workspaces use schema 2. Existing running-plan profiles keep working unchanged. To move one, run
trainctl migrate --prepare, review the proposal, thentrainctl migrate --apply <id>; every profile field is carried over and the originals are kept inplan/migrations/<id>/. - The Claude Code plugin starts
trainctl-mcp@0.9.0throughnpx; update the plugin to pick up this version.
Install
npx trainctl@0.9.0 init # no install
npm install -g trainctl@0.9.0 # or install the CLI
claude mcp add trainctl --env TRAINCTL_DIR="/path/to/my-training" -- npx -y trainctl-mcp@0.9.0Codex users can download trainctl-codex-0.9.0.zip below. It bundles the CLI, the MCP server and their dependencies; follow INSTALL.txt. Node.js 22.18 or newer is required.
All six npm packages are published at 0.9.0 with the latest tag: trainctl, trainctl-mcp, trainctl-core, trainctl-export, trainctl-sync-intervalsicu, trainctl-sync-files.
Verification
- 1672 tests, typecheck and build on the release commit; CI green on Linux and Windows with Node 22.18 and 24, including installation from tarballs.
- Tarballs installed in an isolated directory and the CLI and MCP scenarios run from them: 128 FIT files decoded with the Garmin FIT SDK, 8 calendars, 11 MCP calls.
- The same scenarios run again from the public npm registry without authentication (
npm-validation.json). SHA256SUMS.txtlists the checksums of the attached files.
Assets
| File | Contents |
|---|---|
trainctl-codex-0.9.0.zip |
Codex plugin with the bundled CLI and MCP server |
validation.json |
Local validation of the release commit and the plugin bundle |
npm-validation.json |
Validation of the published npm packages |
SHA256SUMS.txt |
SHA-256 checksums of the files above |
Full changelog: CHANGELOG.md · Compare v0.6.0...v0.9.0
v0.6.0 · Structured workouts and clearer CLI
Version 0.6.0 adds detailed workout instructions and makes the terminal descriptions easier to follow. Version 0.6.0 is available on npm and GitHub. All six npm packages use the latest tag. The Codex plugin ZIP includes the CLI, MCP server and dependencies.
Fixed
- Fractional pace now rounds correctly across minute boundaries in CLI and
Intervals.icu work/recovery steps. - Hard running and timed swimming repetitions explain their actual intent;
standalone sessions do not imply a known training phase. - Multisport rule links now refer to MULTISPORT rather than running foundations.
Added
- Phase-specific cycling and swimming recipes with objectives, rationale,
success criteria, warm-up, main work, recovery and cool-down. - Named swimming drills, RPE guidance without current calibration, and
bounded progression for bike/run bricks. - Coaching instructions in CLI/MCP, JSON/YAML, Markdown, HTML, ICS and
Intervals.icu; FIT step notes and explicit recovery power/pace. - MS-6 documents recipe parameters, evidence boundaries and device limits.
Changed
- CLI workout cards separate objectives, structure, rationale and adjustments
with coloured headings. Planned peak RPE has a labelled ten-step colour scale;
recovery targets have separate rows, and durations use minutes and seconds. - Replacement and shortening previews compare structured cards; confirmation
shows a concise summary. Plain/MCP output keeps headings and numeric RPE. - FTP/CSS without a current dated source now uses subjective effort guidance.
- Shortening preserves complete repetitions and the minimum quality stimulus.
- A time budget too small for a quality set explicitly produces an easy session.
Distribution and limits
- Six npm packages at version 0.6.0 (
latest), plus a self-contained Codex plugin
and terminal examples on GitHub. - Training recipe parameters remain documented engineering choices; independent
coaching review and tests on physical Garmin/Suunto watches are still pending. - FIT step notes may be truncated to 254 UTF-8 bytes; full instructions remain
available through CLI/MCP and text exports.
Verification
- Public npm installation (fresh directory and cache, no authentication): PASS. All six
latesttags resolve to 0.6.0; 56 CLI commands, 11 MCP calls, 128 FIT files and 8 ICS calendars / 231 events. Coaching metadata and coloured RPE output verified. - Local suite: 1076/1076 tests passed, types, build and generated skills checked.
- Coaching simulation: 17 real CLI calls, 72 sessions and 22 workout recipes.
- Isolated package installation: 56 CLI commands, 11 MCP calls, 128 FIT files and 8 ICS calendars / 231 events.
- Relocated plugin: 40 CLI calls, 58 MCP calls, all 22 tools, 50 resources and 2 prompts.
- All six CI jobs passed, Linux/Windows and Node 22.18/24.
Install from npm
npm install -g trainctl@0.6.0
# Or run without a global installation:
npx --yes trainctl@0.6.0 --versionMCP: npx --yes trainctl-mcp@0.6.0. Requires Node >=22.18.0.
Downloads
trainctl-codex-0.6.0.zip: extract to a permanent directory and followINSTALL.txt. Requires Node >=22.18.0. The bundled CLI runs throughnode plugin/scripts/trainctl.mjs.trainctl-x-examples-0.6.0.zip: 10 terminal images at 1600×900, draft Polish posts, alt text and an offline gallery. Captured during 0.6.0 development using synthetic data.validation.json,npm-validation.jsonandSHA256SUMS.txt: verification details and asset integrity.
Full changes: v0.5.0...v0.6.0
v0.5.0 — multisport, Codex plugin and responsive CLI
Version 0.5.0 is distributed through GitHub only: source code and the bundled Codex plugin are available below. No 0.5.0 npm packages are published as part of this release. The ZIP plugin includes its dependencies and works without downloading them from npm.
Added
- Cycling, swimming and mixed-sport plans with separate profiles, time volumes,
equipment constraints, session IDs and multisport race groups. - Reviewed substitutions in all six directions between running, cycling and
swimming, with time budgets, trade-offs and restoration of the original session. - Schema v1 to v2 migration with preview/apply, protected history, journal entries
for the sport actually performed, and recovery after interrupted writes. - Multisport FIT, ICS and HTML exports, calendar withdrawal/reactivation, and
activity matching across Intervals.icu and imported FIT/TCX/GPX files. - A self-contained Codex plugin bundle with 21 training tools, six skills and
trainctl_workspacefor selecting the training directory explicitly. --color auto|always|neverand--plain; responsive tables, consistent sport
colours, readable help and separate session metadata in the CLI.
Fixed
week --sessionnow selects the requested session, including other weeks,
and rejects unknown IDs or conflicting sport filters.init --from-intervalsrespects agent setup and commit options; a conflicting
--sportsoption is rejected before contacting the provider or writing files.- CLI logs of a spontaneous sport change now use the same default
modified
status as MCP unless an explicit status is supplied. - Codex no longer treats the plugin cache as the training workspace. A server
session binds to one selected directory and keeps its credential context separate. - Interactive selectors and the week browser now emit valid terminal control
sequences. Narrow layouts preserve labels, full IDs and Unicode graphemes.
Dependencies and validation
- Updated the MCP SDK, Zod, Vitest/Vite and transitive dependencies; adapted the
test runner to Vitest 4. The dependency audit returned no known advisories. - CI checks source, installed npm tarballs and relocated plugin bundles on Linux
and Windows. Export checks use Garmin FIT SDK and ICAL.js independently.
Known limits
- Cycling/swimming templates and substitution limits remain explicit engineering
choices; a substitution is not a claim of physiological equivalence. - Physical-watch acceptance is separate from file/parser validation. Suunto
account pairing and live Google Calendar import were not completed in this audit. - Multisport groups export linked sessions; swimming FIT send-off is unsupported,
and pace is descriptive when stroke is the executable target.
Release verification
- Local full suite: 1044/1044 passed, types/build and npm dry-run passed.
- CI: all six jobs passed, Linux/Windows and Node 22.18/24.
- Installed tarballs: 56 CLI commands, 11 MCP calls, 128 FIT files and 8 ICS calendars verified.
- Bundled plugin: all 22 tools, 40 CLI calls, 57 MCP calls, 49 resources and 2 prompts.
- Attachments: plugin ZIP, SHA-256 sums, validation metadata and CLI output renders using synthetic data.
To install the Codex plugin, extract the ZIP to a permanent directory and follow INSTALL.txt. Node >=22.18.0 is required.
v0.4.0 — plugin for Claude Code and Codex, activity files, and a plan that keeps your decisions
Install: npx trainctl@0.4.0, MCP: npx -y trainctl-mcp@0.4.0, plugin for Claude Code and Codex from this repository (see docs/integrations/agents.md). New package: trainctl-sync-files. Full history in CHANGELOG.md.
Fixed — found by running every command on a fresh directory
reviewon a Sunday no longer reports the whole week's volume next to the
number of remaining sessions ("52 km across 1 sessions"); it shows what is
left of the week's target.- A directory without
trainctl.yamlnow points totrainctl initinstead of
trainctl plan, which would only have pointed back toinit. whyno longer prints "About 0 minutes" for a rest day, no longer states the
session's purpose twice, and lists each rule once with its text and
provenance instead of in two separate sections.loganswers with what the plan had for that day next to what was recorded,
says when an entry falls on a rest day, and returns structureddatafor MCP.- Messages print
plan/plan.yamlon every system (Windows printedplan\plan.yaml). - A plan generated by another minor version of the engine is reported in
today,week,why,reviewandcheck(informational; never fails
--strict). A plan file with a newer schema is refused with advice to
upgrade trainctl. - Rule sources link to
docs/science/FOUNDATIONS.mdon GitHub, pinned to the
release tag — the file is not part of the npm package, so the relative path
inwhy,deskandAGENTS.mdled nowhere after installation.
Changed — trainctl plan keeps what you decided (ADR-033)
- On an existing plan,
planregenerates only the future. Past and logged
days, pinned days, hand edits, approved shortenings and days whose new session
would exceed a saved time budget stay as they are. An approved volume baseline
fromadapt --applyis kept until you changeathlete.recentWeeklyKm.
Previously every regeneration silently discarded all of that — including on
the documented path "add a race result →trainctl plan". - The same training cycle keeps its phase boundaries; a different goal distance,
or a new goal after the race, starts a new cycle and keeps the earlier weeks
as history ("week 2/12" counts the current cycle). On race day the race
counts as done only when most of its distance is logged or synced (a day
logged as skipped never counts), so a morning shakeout before a postponed
race keeps the same cycle. - Right after
adapt --apply,planreproduces the approved days, including
strength sessions, time-budget caps and the day of the decision. Later,
strength follows the current phases andstrength.days. - A
plan/plan.yamlthat cannot be read (a merge conflict, a missing goal) is
never overwritten silently:planrefuses until it is fixed or--freshis
given, andstatusno longer suggests aplanthat would fail. trainctl diffshows exactly the regenerationplanwould perform.
plan --fresh(MCPfresh) starts over and lists what it discards.- Fixed: a race result recorded inside the plan's horizon did not reset the
calibration rhythm (W-12), so a regeneration could schedule a time trial a
week after a fresh 10 km result.
Added — a CLI you can script
--jsonon every command prints{ code, data, output }— the same data the
MCP tools return (ADR-035).-C <dir>/TRAINCTL_DIRfor the CLI, as the MCP server already had.TRAINCTL_TODAY=YYYY-MM-DDsimulates the date; every CLI and MCP output
announces it, and past-day protection and proposal expiry follow it (ADR-034).- Relative dates in the CLI:
today,tomorrow,yesterday,+N/-N,
weekday names in English and Polish. MCP tools stay ISO-only. trainctl logwithout flags in a terminal asks: pick a session from the last
week, then status, distance, time, RPE and a note.trainctl status/trainctl_status: profile validity, engine version,
calibration, key source (never its value),.envprotection, last pull,
journal, saved proposals with their validity today, uncommitted files.--commit [message]oninit,plan,log,shift,reschedule --apply,
adapt --applyandshorten --apply(MCPcommit) commits exactly the files
the command changed — never secrets,sync.jsonor other staged changes
(ADR-040).init --commitincludes.gitignorewhen it created it or when it
had no uncommitted changes before the secret patterns were added.todayshows the estimated duration and the next session.trainctl completion bash|zsh|fish|pwsh, examples undertrainctl help <command>.- Usage errors (unknown command or flag, a date that is not a date) exit with 2.
Added — trainctl in Claude Code and Codex (ADR-036)
- A plugin in
plugin/, with this repository as its marketplace for both agents:
/plugin marketplace add dithiothreitol/trainctl+/plugin install trainctl@trainctl
in Claude Code,codex plugin marketplace add dithiothreitol/trainctlin Codex.
It bundles the MCP server, the coach persona and four task skills
(review,debrief,shorten,what-if), and in Claude Code two hooks: the
coach instructions at session start in a training directory, and
trainctl checkafter an edit ofplan/plan.yaml. - Skills are generated from the same text as
AGENTS.md
(node tools/plugin/render-skills.ts);plugin.test.tsfails on drift. trainctl init --agent claude|codex|all(MCPagent) writes
.claude/settings.jsonor.codex/config.toml; existing files are never
overwritten.- MCP:
trainctl_ruleexplains a rule by ID with its source class and a link to
FOUNDATIONS for this version; resourcestrainctl://plan,trainctl://config,
trainctl://agents,trainctl://rules/{id}; promptsweekly-reviewand
debrief. CLI:trainctl rules [id]. trainctl checkreturns its findings asdata(--json, MCP, the hook).tools/release/bump-version.mjsmoves every pinned version together: packages,
plugin manifests, MCP configs, the hook and the CI examples.
Added — execution without a hub, a fuller calendar, context from the watch (ADR-037)
- New package
trainctl-sync-files: reads exported FIT, TCX and GPX files
(also.gz, as in Strava and Garmin bulk exports) as a pull-only source, with
no dependencies.trainctl pull --from <folder>(MCPfrom) and
sync.filesintrainctl.yamlforreviewwithout an API key. Skipped files
are named. The same run exported in two formats (start within 60 s, similar
distance) counts once, keeping the richest file: FIT, then TCX, then GPX.
initaddsactivities/to.gitignore. - The sync port is split into
ActivitySource(pull) andSyncProvider
(pull + push). pushsends races as race events (RACE_A/B/C) and strength sessions as
separateWeightTrainingentries, in their own requests: if intervals.icu
refuses either form, a race falls back to an ordinary entry, a warning says
so, and the running sessions are pushed regardless. Cleanup of stale entries
now covers everytrainctl-entry, not only workouts. Not yet verified on a
live intervals.icu account.reviewquotes resting heart rate, sleep and weight from the synced wellness
data, and RPE recorded in the hub where the journal has none — verbatim, with
the source, never averaged or turned into a verdict. HRV and CTL/ATL are
deliberately left out (H-1, P-4).
Added — the engine: time, life after the race, a plan without a race
- Time budget (
time.weeklyMinutes,weekdayMinutes,weekendMinutes,
E-2): weeks over the weekly budget get a lower volume target, days over their
limit are shortened with the same rules asshortenand carry the trade-off;
the plan says when the budget lowers the peak below the level recommended
for the distance, and what the peak would be without it (P-7/P-8). Races and
time trials are never cut.
A week keeps its macrocycle target; the volume the budget leaves is stored
next to it (timeCappedKm), andweek,adapt,diffandexportshow it.
A zone recalibration fromadaptchanges paces: day limits shorten
sessions that no longer fit from the current week, the weekly budget lowers
volume from the next week on, and volume goes up again throughplan. - Transition block after the goal race (R-8): after a half marathon or
longer, two weeks — about half the pre-race volume, easy only, first run on
the third day after a marathon (R-1), then back to normal with one accent;
one week at ~70% after a shorter goal (R-10). Strength returns in the second
week (R-9). Measured first:tools/corpus/post_race_profile.py(three long
races in the corpus — a weak basis, stated as such).todayandwhysay
"after the race" instead of "outside the plan", and a new goal set during the
block starts its cycle after it. - A plan without a race (
goal.kind: base,until, P-11): base weeks only,
deload every fourth week, growth to your documented peak and a plateau; no
taper, no prediction, no race pack. - Strength variants and journal: two weeks of getting into it (F-18), then
heavy sessions, one maintenance session a week in the peak (F-12, F-14);
trainctl log --strength done|skipped [--minutes](MCPstrength) records a
session without touching the run entry of the same day;reviewandtoday
show it. - Trail results no longer calibrate road zones while a road result exists
(Z-10); a trail-only calibration is used with a warning. - Rules E-2, F-18, P-11, R-8, R-9, R-10 and Z-10 in FOUNDATIONS §10, marked as
engineering choices where no source exists. The corpus backtest is unchanged
(volume 1.04, Δ accents 0, Δ sessions 0, tune-ups 6/6).
Docs
- README command tables list
shortenan...
v0.3.0 — three coaching workflows: shorten, why, review
Install: npx trainctl@0.3.0, MCP: npx -y trainctl-mcp@0.3.0. Full history in CHANGELOG.md.
Added — everyday coaching workflows
shorten --minutes 40/trainctl_shortensaves a single-session proposal,
accounting for preparation, recovery and strength. Reduced quality variants
preserve pace and bookends; easy replacements explicitly give up the original
purpose. Approved exceptions survive adaptation and carry their rationale
when moved. All use the existing proposal ID and expiry protections.whyexplains the stored session's goal, phase, dose, neighboring demanding
sessions, execution and time constraints; it identifies manual edits.review --prepare/trainctl_review(prepare=true)combines execution facts
with a saved diff for approval, or explains why no change can be prepared.
Seven-day reports cover exactly seven dates; refresh includes the 21-day
adaptation window. No test result means a request for data, not a timestamp-only
recalibration patch. CLI, MCP and agent onboarding support both languages.
Fixed — training workflow audit
- Generated weeks reconcile actual session distances with their budget. Small
budgets no longer force minimum-size quality sessions; lint reports mileage
and easy-share deviations instead of suppressing low-volume warnings. - Zone-only recalibration preserves approved workout structure and volume.
Volume changes are anchored in upcoming weeks; accepted baselines are saved
in the plan instead of replaying progression from its original date. - Proposals expire at the next local calendar day. Historical date selection
cannot bypass protection of past sessions. Manual swaps also respect recorded
sessions, race dates, pins and time budgets. - Race distance is separate from training volume. Training compliance excludes
both planned and actual races. Unknown race duration is no longer 15 minutes. - Hill returns count toward distance and duration. FIT and intervals.icu preserve
alternating/progression remainders; estimates count the final exported recovery. - Conflicting tune-ups are rejected explicitly. Generation respects the preferred
long-run day; taper carries frequency forward and reports infeasible schedules.
Full-day blocks also remove strength, with a visible trade-off. log --test-time MM:SS(MCP:testTime) stores the measured segment separately.
Whole-session time is never suggested as the test result. Synced completed
tests also trigger a request for their missing result.- Input validation rejects non-finite numbers, negative distances, malformed
times and impossible calendar dates.
Validation: 641 passing tests, including 21 audit regression cases and 35
coaching-workflow regression cases. Type checks, builds and installation of all
five packages verified, including CLI workflows, FIT/mobile export and MCP.
v0.2.0 — reviewed adaptation and time-aware scheduling
Install: npx trainctl@0.2.0, MCP: npx -y trainctl-mcp@0.2.0. Full history in CHANGELOG.md.
Reviewed adaptation and time-aware scheduling
- Execution data now distinguishes unknown from explicitly skipped sessions.
Pull, review and adaptation share running-only classification and the latest
journal correction. Shorter sync refreshes retain older history. adapt --preparesaves an inspectable, content-addressed plan proposal;
adapt --apply <id>applies exactly that proposal and rejects changed inputs
or edited proposal files. Past, logged, pinned and manually edited days stay
intact. Applicable patches cover volume and calibration; recovery remains an
individual coaching decision.reschedule --time YYYY-MM-DD=minutes --pin YYYY-MM-DD --preparation minutes
honors time budgets including preparation, recoveries and strength. Preview
exposes alternatives (--strategy long|quality) and dropped sessions.- Plans retain calibration inputs and generated-day checksums.
whyexplains
result selection and rule provenance;excluded/exclusionReasonlet runners
retain unsuitable race results without using them for zones or predictions. - MCP tools return structured domain data with output schemas and annotations.
export --what mobile --date YYYY-MM-DD: standalone responsive workout HTML,
including light/dark mode, session steps, purpose and expandable reasoning.- Fixed new-result detection comparing a result collection against itself,
cycling counting toward a planned run, and the sync test's dependence on the
current calendar date.pull --datemakes historical sync ranges explicit.
See the workflow guide for examples and boundaries.
Added
trainctl log --rpe <1–10>(CLI and thetrainctl_logMCP tool): session
effort on the CR-10 scale, stored in the journal and shown bytoday. The
engine only stores and quotes it — it never converts feelings into zones,
paces or volume (ADR-027; collection is grounded in P-6, the refusal in Z-4).- The weekly review has a new section, How it felt: journal entries with an
RPE or a note from the reviewed window, quoted verbatim (the last entry per
day wins). No aggregation, no thresholds — the trail is material for a
conversation with the coach-agent, not input to arithmetic. AGENTS.mdgrew a debrief ritual (after a logged session, ask how it went
and record it; when the feeling clashes with the session's role, ask one
question about context), rule 8 — feelings are for conversation, not
arithmetic — and an opt-in offer of a scheduled Monday debrief.docs/examples/proactive-review.md: the coach speaks first — a weekly
check-in from the agent's scheduler or cron, with the consent and
propose-don't-apply rules spelled out.
v0.1.1 — the packages actually run once installed
If you installed 0.1.0, it did not work. This release is the fix.
npx trainctl died on startup with ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING: 0.1.0 published its TypeScript sources with exports and bin pointing at .ts files, and Node deliberately refuses to strip types for anything under node_modules. That works in the repository and nowhere else. Every test ran from the source tree, so nothing caught it until the first npx after publishing.
Fixed
- Packages ship compiled JavaScript (
dist/) with type declarations and source maps, built bypnpm build; the TypeScript sources travel alongside, so a stack trace still lands on readable code. Development is unchanged — the repository still runs straight from TypeScript. - Export filenames dropped the Polish
ł:interwałybecameinterwa-y.fit, and a race called Bieg Wrocławski producedbieg-wroc-awski.ics. Letters Unicode does not decompose (ł ø đ ß æ œ) are transliterated now. - The MCP server reported a hard-coded
0.1.0in its handshake regardless of the package version. Both binaries read their own manifest.
Added
trainctl --version— the bug-report template asked for it before it existed.- Two guards so this class of bug cannot ship again:
packaging.test.tsasserts the published entry points are built files (and that versions match and descriptions are English), and CI packs all five tarballs, installs them into a clean directory, and runs the CLI and the MCP server fromnode_modules.
Changed
- Package descriptions on npm are English; they were Polish in 0.1.0.
0.1.0 is deprecated on npm. Full detail: CHANGELOG.md, and the reasoning is recorded as ADR-026 in SPEC.md.
v0.1.0 — first public release
A running coach that lives in your terminal: a plan-generating engine with a CLI and an MCP server. Your training plan is a YAML file in a git repository, every session cites the research behind it, and your agent gets the coach as a tool.
mkdir my-training && cd my-training && git init
npx trainctl init && npx trainctl plan && npx trainctl todayEngine. Macrocycle from base to taper with pyramidal-to-polarised progression; session shapes drawn from a corpus of 50 real coaching plans; zones calibrated from race results, never from a watch's threshold estimate; finish prediction as a range, never a single number; a week re-solver that names the session it sacrifices and why.
Interfaces. 16 CLI commands and 16 MCP tools over the same handlers, so the agent and the terminal cannot disagree. check lints the plan against the engine's invariants and fails a CI pipeline; diff --plan compares two full plans, so "what if I move the race three weeks" is a branch, not a rewrite. English and Polish, both first-class.
Where it refuses. No injury-risk score, no readiness from HRV, no silent edits to your own plan — each refusal documented against the literature in docs/science/FOUNDATIONS.md (~60 sources, rule IDs quoted by trainctl why).
Requires Node ≥ 22.18; there is no build step, so the published package is the source you can read. Architecture and decisions: SPEC.md. Full changelog: CHANGELOG.md.
Known limits are listed in the changelog rather than hidden: activities reaching intervals.icu through Strava carry no data through its API, long runs are always generated easy (71% of the corpus coach's), and the backtest calibrates VDOT to an engineering value rather than the athlete's own results.
Tag note: v0.1.0 was moved once, hours after it was first cut, to include a fix for export filenames dropping the Polish ł (interwa-y.fit → interwaly.fit). Nothing had been published under the tag at that point — the npm packages are not out yet — so the tag now matches exactly what will be published.
