Joules

Use this to build a cycling-week proposal from ride days, durations, and an athlete-facing narrative. This supersedes prior pending proposals for the same week, which can no longer be presented or committed. Target differences are reported but never block the proposal.

buildWeek

Use this after the athlete accepts a presented week. Publish that exact proposal to the athlete's Joules calendar, replacing incomplete workouts from the prior weekly publication and incomplete workouts without a publication in the proposed week, while preserving completed workouts. This also replaces the week's narrative. Invalid or stale pending proposals may be marked expired without publishing rides. Retrying the same committed proposal returns its saved result without duplicating rides.

commitWeek

Read the athlete profile, planning status, next planning week, and applicable activity target.

getPlanningContext

Use this to present a built week proposal for athlete review.

presentWeek

Use this to save planning facts the athlete stated or directly confirmed. Supplied fields replace their saved values; omitted fields are preserved.

setAthleteProfile

Use this only when missingRequired is empty. Before calling, show the complete proposed or replacement plan and receive explicit athlete approval of that exact plan. Fit every weekly target within saved availableDays and weeklyHours. This destructively replaces the plan from startDate forward. startDate must be the Monday of the athlete's current local week or a future Monday. Completed workouts and earlier incomplete workouts are preserved; incomplete workouts from the athlete's local today forward may be removed. Weekly target dimensions are optional constraints. After saving, use the first returned week to call buildWeek, then presentWeek.

setPlan