runningman is a local, running-only training tracker written in Zig. It shows
the planned workout for a date, records what actually happened, preserves every
schedule revision, and produces a weekly check-in suitable for sharing with
ChatGPT.
The training log is append-only JSONL. Corrections and schedule changes add new records instead of silently changing history.
The general half-marathon planner uses standalone runner-profile, evidence-ledger, and policy documents. Validate them:
./zig-out/bin/runningman profile validate examples/runner-profile.json
./zig-out/bin/runningman evidence validate evidence/half-marathon.json
./zig-out/bin/runningman policy validate policies/half-marathon.jsonAssess the example runner's baseline and target:
./zig-out/bin/runningman plan assess examples/runner-profile.jsonThese commands do not read or create the personal training log. Assessment reports:
- the primary recent performance used;
- a current half-marathon equivalent;
- estimate uncertainty;
- a bounded training-improvement assumption;
- a supported race-date outcome range;
- a rounded target recommendation;
- target classification and explanation;
- effort and pace anchors; and
- the effective policy rules.
Target classifications are:
completion: there is not enough performance evidence for a numeric target;recommended: no target was supplied, so the planner proposes one;supported: the requested target is no faster than the supported fast boundary;aspirational: the target is outside the range but may remain motivational; andinfeasible: the target is beyond the strongest outcome supported by the profile, plan window, and policy.
An aspirational or infeasible target is never used as the training-pace anchor. Assessment does not write or apply a plan.
Generate a deterministic proposal against an initialized append-only data file:
./zig-out/bin/runningman plan generate examples/runner-profile.json \
--output proposed-plan.json
./zig-out/bin/runningman plan preview proposed-plan.json
./zig-out/bin/runningman plan apply proposed-plan.json
./zig-out/bin/runningman plan markdown --output training-plan.mdGeneration allocates the macrocycle, weekly volume, long-run progression, explicit quality-work progression, and structured daily workouts before running an independent policy validator. Quality sessions record their stage, phase position, work distance, repetition format, recovery, and whether the week establishes, progresses, reduces, tapers, or sharpens the load. In the foundation phase, progression adds whole 1 km repetitions while retaining the same 1 km repetition length and two-minute recovery; it no longer alternates between unrelated 1 km and 500 m formats. The proposal is never applied automatically. With no supported pace anchor, the plan retains effort guidance without inventing pace or duration precision.
The same planner can generate a course-aware trail plan. Start from the trail profile example and record the race ascent and technicality. Race descent and recent ascent history remain optional rather than being invented when unknown:
./zig-out/bin/runningman profile validate examples/runner-profile-trail.json
./zig-out/bin/runningman plan assess examples/runner-profile-trail.json
./zig-out/bin/runningman plan generate examples/runner-profile-trail.json \
--output trail-plan.json
./zig-out/bin/runningman plan preview trail-plan.json
./zig-out/bin/runningman plan markdown trail-plan.json \
--output trail-training-plan.mdTrail plans retain the road planner's distance, recovery, spacing, and taper
guardrails, then add periodized weekly ascent, long-run ascent, uphill quality
work, trail-specific sessions, controlled descending, and race-course vertical
targets. All trail workouts use effort guidance rather than converting a flat
performance into a trail pace or finish-time prediction. The generated JSON
records terrain and ascent/descent for every core workout and the Markdown plan
shows weekly vertical targets. See
docs/half-marathon-policy.md for the evidence
boundaries and explicit product assumptions.
The profile chooses baseline.training_load_basis independently of running-day
availability. distance uses measured weekly kilometres; duration progresses
time-based regular, quality, and long-run prescriptions. The duration example
uses two available days, but the same load path also supports additional easy
days without changing its macrocycle, workout roles, or validator. Trail terrain
and vertical targets are applied after load and session allocation. If ascent
history is absent, either load basis uses conservative course-relative vertical
targets while leaving the profile's history missing. Other exercise is neither
scheduled nor credited as running load.
Generated proposals also embed deterministic provenance: the complete runner profile and policy snapshots, SHA-256 identities for the profile, policy, and evidence ledger, the assessment used for pacing, and structured decisions for every week and workout. Applying a proposal preserves the same provenance in the append-only schedule revision. No generation timestamp is included, so identical source files still produce byte-identical proposals.
With an applied planner-generated schedule, runningman plan markdown writes
the friendly plan directly to standard output. Add --output training-plan.md
to save it instead. To inspect an unapplied proposal, pass its path explicitly:
runningman plan markdown proposed-plan.json. The document starts with a
compact whole-plan table, then presents each week with its purpose, planned
volume, daily run instructions, and the time-and-effort-matched bicycle option.
Rest days remain visible, while internal schedule IDs, policy rule IDs, and
planner provenance stay in the structured data rather than cluttering the
shared document.
Explain an active schedule, one active workout, a proposal, or one proposed workout without selecting a mode flag:
./zig-out/bin/runningman plan explain
./zig-out/bin/runningman plan explain today
./zig-out/bin/runningman plan explain tomorrow
./zig-out/bin/runningman plan explain 26
./zig-out/bin/runningman plan explain 2026-07-22
./zig-out/bin/runningman plan explain proposed-plan.json
./zig-out/bin/runningman plan explain proposed-plan.json today
./zig-out/bin/runningman plan explain proposed-plan.json tomorrow
./zig-out/bin/runningman plan explain proposed-plan.json 2026-07-22The command recognizes today, tomorrow, or a strict YYYY-MM-DD argument as
a date and otherwise treats it as a proposal path. It recomputes the target
assessment and explains phase purpose, weekly progression, workout allocation,
pace derivation, rule summaries, evidence IDs, and explicit product assumptions.
Explanation is read-only and never revises the schedule.
The canonical JSON Schemas include:
schemas/runner-profile.schema.jsonschemas/evidence-ledger.schema.jsonschemas/training-policy.schema.jsonschemas/proposed-plan.schema.json
Runner inputs are represented as a value plus one of these sources:
measureduser_enteredderiveddefaulted
This prevents a later plan explanation from presenting a default or estimate as
measured fact. A target time is optional. If it is omitted, the later baseline
assessment will recommend a supported target or outcome range. The
recent_performances.value list may be empty, but it must still be present so
that missing performance evidence is explicit.
The current profile format supports half-marathon plans spanning 55–168 days and 2–6 core running days. The distance policy requires at least three days; the duration policy supports two or more. Profile validation also checks date ordering, day availability, numeric baselines, recent performances, and known unavailable dates. The evidence ledger requires traceable citations, populations, comparisons, outcomes, limitations, confidence, planning implications, and stable policy-rule links. Policy validation checks numerical boundaries, workout recipes, unique identifiers, and reciprocal links between every rule and evidence entry.
The policy and assessment design is explained in
docs/half-marathon-policy.md.
Zig 0.16 is required:
./check.shThe script formats the Zig source, builds the executable, and runs unit and CLI
tests. The executable is written to zig-out/bin/runningman.
Choose the Monday on which week 1 starts:
./zig-out/bin/runningman init 2026-07-20The generated plan has 13 complete weeks and ends with the half marathon on Sunday of week 13. For a start date of 2026-07-20, race day is 2026-10-18.
The four core runs are Monday, Tuesday, Thursday, and Saturday. Wednesday is an optional recovery run, and Friday and Sunday are rest days (except race day). Training progresses through these phases:
| Weeks | Phase | Main progression |
|---|---|---|
| 1–3 | Foundation | Establish consistent easy volume and controlled quality |
| 4 | Recovery | Reduce volume and intensity |
| 5–7 | Build | Increase long runs, intervals, and sustained work |
| 8 | Recovery | Absorb the build before race-specific work |
| 9–11 | Race-specific | Longer half-marathon-effort segments and peak long runs |
| 12 | Taper | Reduce volume while retaining short controlled intensity |
| 13 | Race | Short easy running, rest, and the half marathon |
By default, data is stored in runningman-data.jsonl in the current directory.
Root-level JSONL data files and generated weekly check-ins are gitignored, so
personal training data is not included in repository commits.
Use a different file by placing --data PATH before the command:
./zig-out/bin/runningman --data ~/training/running.jsonl todayEncrypt the default data file for the configured runningman GPG recipient:
./scripts/encrypt-dataThis atomically creates or replaces runningman-data.jsonl.gpg. The plaintext
JSONL file remains gitignored; only the encrypted snapshot should be committed.
The script is configured for the dedicated runningman key with fingerprint
F66219D7C10E26FF1000B9932E2818269A17B4DB and refuses to modify an existing
encrypted snapshot if that recipient is unavailable or encryption fails.
Encrypt a non-default data path or choose another output path:
./scripts/encrypt-data --data ~/training/running.jsonl
./scripts/encrypt-data --output ~/training/runningman-data.jsonl.gpgAfter pulling on another computer, decrypt the snapshot:
./scripts/decrypt-dataIf no local plaintext file exists, the script installs the decrypted file. If one exists, it is replaced only when it is an exact prefix of the decrypted append-only log and the added records include an activity. Identical or older snapshots leave the local file unchanged. Divergent logs fail without replacing either copy, so activity records from one computer cannot be silently lost.
Use non-default encrypted and plaintext paths with --input and --data:
./scripts/decrypt-data --input ~/training/running.jsonl.gpg \
--data ~/training/running.jsonlEncrypted snapshots cannot be merged. Pull and decrypt the latest snapshot before recording on another computer, then encrypt, commit, and push before switching computers again.
Every CLI date argument accepts an explicit YYYY-MM-DD, a day number in the
current month such as 26, today, or tomorrow. Relative dates use the
computer's local calendar date; a day number never rolls into another month.
With no command, runningman shows today:
./zig-out/bin/runningman
./zig-out/bin/runningman today
./zig-out/bin/runningman tomorrow
./zig-out/bin/runningman 26
./zig-out/bin/runningman 2026-07-25The output includes the phase, workout instructions, intensity, distance, segment pace ranges, time implied by each distance/pace pair, expected total time, a time-and-effort-matched bicycle replacement, schedule revision ID, workout ID, and any recorded result.
See a detailed upcoming schedule, starting today by default:
./zig-out/bin/runningman schedule --weeks 4
./zig-out/bin/runningman schedule --weeks 4 --from 2026-07-20Every non-rest running workout includes a bicycle option derived from the planned segment durations. A pace-derived duration range is replaced by one practical target near its midpoint: repetitions are rounded to 15 seconds, standalone segments under 15 minutes to 30 seconds, segments under an hour to one minute, and longer segments to five minutes. Exact planned durations and recovery periods remain exact. Repetitions, recovery-week reductions, taper reductions, and the distinction between easy and demanding work are retained. Bicycle distance is deliberately not prescribed because terrain, wind, equipment, and cycling economy make a kilometre conversion misleading.
The replacement uses a practical duration near the planned running time and a cycling-specific RPE target as a conservative field approximation. It is not presented as a proven 1:1 physiological equivalence. Running and cycling can produce different heart-rate and oxygen-uptake responses at apparently matched effort, and running-specific mechanical preparation is not replaced. The 2026 systematic review and meta-analysis found no clear short- to medium-term difference in the limited studies, but explicitly concluded that the evidence does not establish interchangeability. The mode-dependent RPE/heart-rate response is supported by Hassmén (1990), and an acute matched-HIIT comparison found different cardiorespiratory responses between running and cycling (Scanlan et al.).
Use bike-specific power or heart-rate zones when they have been established from cycling. Otherwise follow the displayed RPE and breathing cues. Stop if cycling produces knee pain. The half-marathon race itself has no equivalent bicycle replacement.
Record the Oura scores shown each morning:
./zig-out/bin/runningman check-in
./zig-out/bin/runningman check-in 2026-07-21 \
--sleep 82 \
--readiness 76 \
--notes "Slept well"Running check-in without score flags prompts for them interactively. A second
check-in for the same date creates an append-only correction.
Download an Oura Trends CSV with Sleep Score and Readiness Score, then put
it in oura_trends/. Import the newest CSV in that directory with:
./scripts/import-ouraThe importer validates the complete CSV first, displays every dated score, and
marks dates that already have a morning check-in. After explicit approval, it
records only missing dates through the normal append-only check-in command.
It never creates corrections for dates already present.
Pass a particular export, inspect without recording, or use another data file:
./scripts/import-oura oura_trends/oura_2026-08-11_2026-08-18_trends.csv
./scripts/import-oura --dry-run
./scripts/import-oura --data ~/training/running.jsonl OURA_TRENDS.csvRun log without activity flags for guided input:
./zig-out/bin/runningman log
./zig-out/bin/runningman log 2026-07-20Or provide everything directly:
./zig-out/bin/runningman log 2026-07-20 \
--distance 7.1 \
--duration 44:30 \
--avg-hr 141 \
--ascent-m 120 \
--descent-m 115 \
--rpe 3 \
--pain 0 \
--notes "Easy and relaxed"To fill missing scheduled runs during an illness, preview an inclusive date range:
./zig-out/bin/runningman log --sick --from 2026-08-24 --through 2026-09-06 --dry-runRemove --dry-run to review the affected workouts and confirm recording them.
Both dates are required and accept YYYY-MM-DD, a day in the current month,
or today; sickness dates cannot be in the future. For example,
--from 21 --through 26 --dry-run previews the 21st through the 26th of the
current month (once the 26th has arrived). Use full dates to cross months.
Each missing run is recorded as skipped with reason sickness. Existing
outcomes (including cycling substitutions), unconfirmed return-stage forecasts,
scheduled rest days, and optional
recovery runs where rest is equally valid are left
alone; repeating the command adds no duplicates. Every date must have a
scheduled workout or rest entry. The command does not change the schedule or
invent effort, pain, or recovery scores. Run runningman review afterwards;
missing recovery data can still result in INSUFFICIENT_DATA.
Outcomes are:
completedmodifiedskippedrested
A modified workout requires a reason:
./zig-out/bin/runningman log 2026-07-21 \
--modified \
--distance 6 \
--duration 39:00 \
--rpe 8 \
--pain 2 \
--pain-location "right knee" \
--reason "Stopped intervals early"RPE uses 1–10 and pain uses 0–10. Distance, duration, heart rate, ascent, descent, RPE, pain, and notes are optional. For repetition-based workouts such as intervals or hills, you can record completion, RPE, pain, and a short note without inventing a distance or duration. Logging the same date again creates an explicit correction linked to the prior activity. The next morning’s Oura scores provide the recovery signal in weekly reports.
Duration accepts whole minutes (44), minutes and seconds (44:30), or hours,
minutes, and seconds (1:03:10).
Record a bicycle replacement by sport and duration. Bicycle kilometres remain separate from running volume in reports:
./zig-out/bin/runningman log 2026-07-28 \
--sport cycling \
--duration 43:00 \
--avg-hr 138 \
--rpe 7 \
--pain 0 \
--notes "Completed the prescribed bicycle intervals"On macOS, a Polar Beat summary screenshot can be recognized locally with Apple's Vision framework:
./scripts/import-polar \
"polar_beat_screenshots/Screenshot 2026-07-20 at 19.01.46.png"The importer reads the date from the filename and extracts visible values such as duration, average and maximum heart rate, calories, fat-burn percentage, training benefit, and heart-rate-zone durations. OCR uses recognized labels and their relative positions, so small crop and scale differences do not require fixed screenshot coordinates.
The script displays its inference and asks whether to use those values as the
starting point. If accepted, it opens a complete runningman log command in
$EDITOR, falling back to vi. Add missing values, correct OCR results, or
change the outcome in that file. Saving and exiting successfully runs the
edited command immediately. Exit the editor with a non-zero status—for example,
Vim's :cq—to cancel without recording anything.
Missing fields appear as commented options inside the editable command. Distance uses the active workout's planned distance as its suggested value when the plan has one. RPE and pain remain placeholders because they must describe what actually happened.
For a GUI editor, configure it to wait until the file is closed:
EDITOR="code --wait" ./scripts/import-polar SCREENSHOT.pngPreview the generated editor file without recording:
./scripts/import-polar --dry-run SCREENSHOT.pngOverride a missing or incorrect filename date, or select another data file:
./scripts/import-polar --date 2026-07-20 SCREENSHOT.png
./scripts/import-polar --data ~/training/running.jsonl SCREENSHOT.pngDuration and average HR populate their dedicated activity fields. Other Polar values and a SHA-256 source-image identifier are preserved in notes. Distance, RPE, and pain remain explicitly missing for manual entry. If the date already has an activity, the editor file warns that running it will create an append-only correction. Reimporting the exact same image also produces a warning.
Export the original activity from Garmin Connect, or copy its .fit file from
the Edge device, into garmin_activity_exports/. With no file argument, the
importer selects the most recently modified .fit or .zip file:
./scripts/import-garminYou can also pass either the FIT file or Garmin's ZIP explicitly:
./scripts/import-garmin garmin_activity_exports/23767860323.zipThe importer validates the FIT checksums and reads running and cycling session summaries locally. It normally selects the sport stored in the FIT file. Date, timer duration, distance, average heart rate, ascent, and descent populate dedicated activity fields. Available measurements such as maximum heart rate and speed, calories, cadence, power, training effect, temperature, laps, and heart-rate-zone durations are preserved in notes. GPS coordinates and device identifiers are not copied into the training log.
As with the Polar importer, the measured values are shown first. Accepting them
opens an editable runningman log command; saving and exiting records it.
RPE and pain remain explicit placeholders for manual entry. If the ride replaced
a planned run, change the generated outcome to modified and add a reason.
An Edge records the active device sport profile in the original FIT file. Changing the activity type later in Garmin Connect does not necessarily rewrite an "Export Original" download. Override a run recorded under a cycling profile explicitly:
./scripts/import-garmin \
--sport running \
garmin_activity_exports/23791249774.zipWhen the override differs from the FIT sport, both values are retained in the activity notes for auditability.
Preview without recording, override the local FIT date, or select another data file:
./scripts/import-garmin --dry-run ACTIVITY.fit
./scripts/import-garmin --date 2026-07-28 ACTIVITY.fit
./scripts/import-garmin --sport running ACTIVITY.fit
./scripts/import-garmin --data ~/training/running.jsonl ACTIVITY.zipThe source FIT SHA-256 is recorded in notes. Reimporting the same activity, or importing on a date that already has an activity, adds a warning to the editable command before any append-only correction can be created.
Ask whether the current schedule still looks appropriate:
./zig-out/bin/runningman reviewThe review covers progress from the start of the plan through the latest closed training day. Its recommendation uses at most the latest 28 closed days. If today's core workout has not been logged yet, today is not treated as missing: the activity window closes yesterday while today's Oura scores remain available as yesterday's next-morning recovery signal. Use an explicit date for a reproducible historical review:
./zig-out/bin/runningman review --as-of 2026-07-27The concise output shows whole-plan outcomes by workout category, planned and
actual running distance, runner-specific HR/RPE calibration, the current Oura
Sleep/Readiness pattern, coverage gaps, and a HOLD, PROGRESS, REDUCE, REPLAN, or
INSUFFICIENT_DATA recommendation.
When information is insufficient, missing workout dates and types appear
directly below the recommendation. Missing Oura dates are listed separately
with the number of additional check-ins required to meet each coverage rule.
For a sickness-related REPLAN on a generated road-distance plan, the review
also prints the next plan adjust command. It preserves the selected executable
and data path, and suggests a start after any logged training on or after the
review date. The readiness flag is your confirmation, not inferred from Oura;
the adjustment asks whether the target date can move and only creates a proposal.
Preview and explicit application remain separate steps.
Once a return plan is applied, review leads with the current return block and
dated checkpoint instead of suggesting a fresh adjustment for the old sickness skips.
For example, an aerobic-return week starting September 7 has a September 13
checkpoint before a possible September 14 repeat week. The report explains
what to assess and prints one command: runningman plan checkpoint. It asks
whether to continue the progression or spend another period running easy,
previews the change, and applies it only after you confirm. Your movable/fixed
target preference is remembered; no filenames or stage flags are required.
Missing data or current reduction signals block the checkpoint. The checkpoint also
appears after generation/application and in daily workout views. It is a
scheduling reminder, not an automatic assessment of recovery.
If the repeated week is interrupted, review explains why Continue is
unavailable and offers Easy through the same checkpoint command. Easy can
start today (after any already logged dates), without waiting for Monday. It
reuses the original completed-training baseline and easy-return construction,
not another percentage reduction. Preview and confirmation are still required.
An explicitly applied new easy-return period acknowledges the setbacks before
its restart; ordinary stage advances retain that accounting boundary. The next
checkpoint uses runs from the new return period, not earlier return attempts.
Unconfirmed forecast workouts are excluded from required outcomes, disruption counts, planned-distance totals, and next-morning Oura requirements. Existing records on those days are preserved as context, including illness and actual running distance; recorded pain and unusual effort remain visible to the review.
Check your last recorded run and any missing workout outcomes since then:
./zig-out/bin/runningman status
./zig-out/bin/runningman status --as-of 2026-09-26This read-only report uses activity dates and the latest correction for each day. It lists required workouts after the last run and before the selected date, with today shown separately, not overdue. With no recorded runs, it checks from plan start. Rest days, optional runs, and unconfirmed return-stage workouts are not missing logs. Cycling, skipped, rested, and modified outcomes resolve that day's log; only completed running or modified running with recorded distance or duration counts as the last run. It does not assess recovery or change the plan.
Show daily plan versus reality:
./zig-out/bin/runningman history
./zig-out/bin/runningman history 2026-07-20 2026-08-16Summarize recent weeks and compare mileage with the preceding equal-length period:
./zig-out/bin/runningman compare --weeks 4
./zig-out/bin/runningman compare --weeks 1 --ending 2026-07-26The comparison includes outcomes, planned distance ranges, actual mileage and duration, easy/quality/long-run distribution, average RPE, heart rate, Oura Sleep and Readiness Scores, pain reports, and missing records. Missing data is never treated as rest.
Generate a Markdown report:
./zig-out/bin/runningman review report \
--weeks 1 \
--ending 2026-07-26 > weekly-check-in.mdIt contains:
- Training goal, baseline, availability, and intensity guidance
- Planner, profile, policy, evidence, source hashes, assessment, and race context when generated provenance is available
- A deterministic
HOLD,PROGRESS,REDUCE,REPLAN, orINSUFFICIENT_DATArecommendation with every coverage and direction rule - Schedule revision history
- Planned-versus-actual summary
- Comparison signals
- Daily workout expectations
- Actual results, RPE, heart rate, pain, reasons, and notes
- Next-morning Oura Sleep and Readiness Scores
- The latest known schedule revision
- Every remaining planned day through race day, including structured segments, pace ranges, and expected duration
- The JSON contract for proposing a complete replacement program
The local classifier uses review policy runningman-review version 7. Oura is
responsible for combining its physiological signals; Runningman consumes only
the resulting Sleep and Readiness Scores and does not reinterpret raw HRV or
other sensor data. Each score remains independent. A morning is shown as
BALANCED, SLEEP_LIMITED, READINESS_LIMITED, or BOTH_LIMITED, so adequate
Sleep with poor Readiness remains visible rather than being averaged away.
The classifier requires an explicit outcome for every closed core run,
next-morning Sleep/Readiness coverage for at least half of eligible core runs,
and complete scores on at least two of the latest three mornings. REPLAN is
selected for at least two modified, skipped, or rested core runs, requesting
that the next proposal reconnect the remaining progression to completed
training. Sickness-related skips are shown with their count and first/last
workout dates; these are not inferred illness onset or recovery dates.
Replanning does not itself prescribe less load, shift workouts, or decide the
race date. Those decisions belong to the next proposal.
REDUCE is selected for a non-race RPE of 9–10, confirmed current pain affecting
the plan, or Sleep or Readiness below Oura's Good boundary of 70 on at
least two of those three mornings. A cycling substitution remains visible but
does not reduce the plan by itself. Reduction signals take precedence over
replanning and progression signals. Missing required coverage takes precedence
over all directions, while known disruption remains visible in the report.
Pain scores of 0–3 are informational. If any score in the decision window is
above 3, the concise review asks whether pain currently affects the user's
ability to follow the plan. Only an explicit yes selects REDUCE; historical
pain never decides on the user's behalf. The answer is used for that read-only
review and is not written to the training log.
PROGRESS requires at least two completed sessions that provide consistent
evidence that the prescription was conservative: quality sessions below their
RPE 6–8 target, or sessions completed faster than the full structured pace
range while remaining inside the prescribed RPE. These persistence thresholds
are conservative product assumptions. One unusual workout or wearable score
does not select a direction, missing activity is never treated as rest, and
data after the review horizon is excluded. Bidirectional adjustment follows the
general increase/maintain/decrease model evaluated in recreational runners by
Nuuttila et al.; Runningman's exact
signals and persistence thresholds remain product policy rather than a claim
that the study validated this implementation.
The review also derives observed session-average heart-rate bands for easy, quality, and long runs whose recorded RPE matched the prescribed range. At least two matching runs are required. With four or more it reports the central half of observations to reduce outlier influence. Quality-session HR includes warm-up and recovery and is explicitly not presented as the heart rate of the hard repetitions; segment-specific guidance requires structured lap HR data. Both HR and RPE remain visible because field running research found comparable training outcomes from HR- and RPE-guided prescriptions while noting different measurement precision (Johnson et al.).
The recommendation is read-only: it does not automatically reduce, hold, progress, or replace the schedule. This keeps the program from making a medical or training-load decision from an unsupported threshold. Any replacement still uses the independently validated preview/apply workflow below.
The raw audit log can also be exported:
./zig-out/bin/runningman export --format jsonl > training-export.jsonlGive the Markdown file to ChatGPT or Codex for a weekly review. A review does not have to change the program. If a change is recommended, ask it to create a revision JSON file that follows the contract in the report and replaces every remaining day through race day.
Applied schedules are immutable snapshots. When a replacement is applied,
existing activities retain their original schedule_id and workout_id, and
review resolves those activities against that older workout. Only the
remaining program changes; the historical schedule is not rewritten.
For a sickness interruption, create a Friel-inspired return proposal:
./zig-out/bin/runningman plan adjust --from 2026-09-07 \
--ready-to-resume --output return-plan.jsonThe first adjustment asks whether your target date is movable or fixed.
Later adjustments inherit that preference from the applied plan. For an explicit
override or unattended first adjustment, specify --race-date flexible|keep|YYYY-MM-DD.
The default aerobic-return stage contains only easy, effort-based runs and rest. It uses familiar completed running, then projects a repeat of your last completed loading week followed by its original progression. With a movable target, no weeks from that progression are discarded. With a fixed date, any omissions are listed explicitly and the remaining structure is validated.
After reviewing and applying the initial proposal, follow that program. At the checkpoint shown by the program, run:
./zig-out/bin/runningman plan checkpointChoose continue if running and recovery feel normal, or easy if you are ready
for easy running but not the next loading block. Inspect the preview and confirm
with y to update the same program. cancel, a blank answer, or EOF makes no
change. The command handles dates and remembers the target preference. A fixed
target is never moved silently if an extension cannot fit.
After the repeated loading week, the same checkpoint confirms its response
before the remaining progression. No calendar date automatically advances it.
Advanced scripts can still use plan adjust --stage repeat|continuation and
separate proposal files. --base-weeks 1-4 changes the provisional calendar
estimate, not a mandatory recovery duration.
Base returns can start midweek. If today's run is already logged, choose a
later --from date to preserve it. Repeat/continuation stages start on Mondays.
The initial adjustment needs a complete REPLAN review and
--ready-to-resume; this is your statement, not medical clearance from Oura.
Original history, baseline evidence and the race prescription are preserved.
Old percentage-cap proposals (v1/v2) must be regenerated into a new file.
See interruption adjustment policy for the coaching source, explicit implementation assumptions, stage workflow and limits.
A revision targets the current schedule ID, so an older AI response cannot silently overwrite a newer program. Previewing is read-only:
./zig-out/bin/runningman plan preview revised-program.jsonAfter inspecting the full preview, apply it:
./zig-out/bin/runningman plan apply revised-program.jsonRevision files use only the
proposed-plan schema. The complete
document must preserve its planner provenance, assessment, macrocycle weeks,
and the structured decision attached to every week and workout. Unsupported
proposal schema versions are rejected.
The easiest starting point for a revised program is a newly generated complete
proposal. It must contain one workout or rest entry for every consecutive date
from the embedded runner profile's plan start through race day. effective_from
marks the first workout changed by the revision. Earlier workouts are retained
as validation context and must exactly match the current schedule. A segment
can prescribe distance_km with a fast/slow pace range, or duration_seconds;
repetitions and recovery are represented with repetitions and
recovery_seconds.
Preview and apply both recompute the embedded assessment and run the complete plan through the independent validator. Editing a prescription without its decision record, changing historical context, or violating progression, spacing, volume, phase, or taper rules causes the proposal to be rejected.
Applying creates a new immutable schedule snapshot. Dates before
effective_from are copied from the parent schedule, while later dates come
from the revision file. Previous schedules remain present, and recorded
activities remain linked to the exact schedule and workout that were in effect
when they were logged.
Every JSON line has schema_version: 2 and one of these event types:
schedule: immutable context, revision metadata, provenance, and weekly decisions when availableworkout: one dated workout in a complete schedule snapshot, with structured segments and pace rangesactivity: an actual result linked to the exact schedule and workoutmorning_check_in: Oura Sleep and Readiness Scores for a dated morning
This preserves both what was planned and what was known when an activity was recorded.