@wattsonclub/wattson-cli 0.1.0 → 0.1.1

package/skill/references/workout-building-blocks.md

@@ -1,507 +1,292 @@
-# Workout building blocks
+# Workout building blocks: exact authoring contract
 
-This doc describes the current **atomic workout grammar** in `packages/domain` and how agents should think about composing workouts from it.
-
-It is intentionally agent-oriented.
-
-Goal:
-- make the workout structure legible without reading raw Zod code
-- expose the atomic building blocks that agents can combine
-- make validation/revision loops more reliable
-- establish a stable conceptual vocabulary for future CLI/MCP/chat interfaces
-
-Canonical source of truth remains the domain schema.
-This doc is a human/agent guide, not a replacement for the schema.
-
-Source of truth:
-- `packages/domain/src/index.ts`
-
----
-
-## 1. Mental model
-
-A workout is:
-- metadata + rationale + constraints
-- a sequence of **blocks**
-- where blocks are either:
-  - simple timed blocks
-  - repeated interval sets
-  - notes/support markers
-
-The useful abstraction for agents is:
-
-1. choose an **objective**
-2. choose a **macro shape**
-3. fill that shape with typed blocks
-4. choose targets/execution modes/cadence/HR constraints
-5. validate
-6. revise until clean
-
-In other words:
-- agents should compose workouts from typed pieces
-- agents should not treat the workout as an opaque paragraph
-
----
-
-## 2. Top-level workout fields that matter most
-
-These fields drive authoring behavior most strongly:
-
-- `title`
-- `objective`
-- `athleteContext.ftpWatts`
-- `blocks[]`
-- `constraints`
-- `rationale`
-- optional `computed`
-- optional `validation`
-- optional `scheduledDate` (`YYYY-MM-DD`): the day the rider plans to ride it. Set with `schedule_saved_workout`; it orders the library and never starts a ride.
-
-Important practical point:
-- the **blocks** define the actual workout shape
-- the **constraints** define what is allowed/safe/preferred
-- the **validation/computed** fields define whether the workout is coherent/executable
-
----
-
-## 3. Atomic building blocks
-
-## 3.1 Simple timed blocks
-
-These are the main single-step building blocks.
-
-Supported simple block types:
-- `warmup`
-- `steady`
-- `recovery`
-- `cooldown`
-- `ramp`
-- `free_ride`
-- `cadence_drill`
-- `rest`
-
-Shape:
-- `id`
-- `type`
-- `durationSec`
-- optional `target`
-- optional `title`
-- optional `instructions[]`
-- optional `cadence`
-- optional `hr`
-
-### When to use them
-
-#### `warmup`
-Use for:
-- gradually preparing the rider
-- low-to-moderate progressive openers
-- cadence ramping without heavy load
-
-#### `steady`
-Use for:
-- endurance
-- tempo
-- threshold holds
-- any stable target period
-
-#### `recovery`
-Use for:
-- low-load valleys between work bouts
-- aerobic reset periods
-
-#### `cooldown`
-Use for:
-- winding the session down
-- reducing target and cadence pressure at the end
-
-#### `ramp`
-Use for:
-- explicit increasing/decreasing load phases
-- progressive openers or build segments
-
-#### `free_ride`
-Use for:
-- rider-controlled sections
-- open movement / transitions
-- less prescriptive sections where target control should be loose
-
-#### `cadence_drill`
-Use for:
-- skill emphasis
-- cadence-specific work where the pedaling cue matters as much as the power target
-
-#### `rest`
-Use for:
-- explicit rests distinct from active recovery
-- true low/no-load gaps
-
----
-
-## 3.2 Interval set block
-
-Composite block type:
-- `interval_set`
-
-Shape:
-- `id`
-- `type: "interval_set"`
-- `repeat`
-- `steps[]`
-- optional `title`
-- optional `instructions[]`
-- optional `cadence`
-- optional `hr`
-
-This is the main repeating composition primitive.
-
-Think of it as:
-- a small local workout pattern
-- repeated `n` times
-
-That makes it the core tool for:
-- VO2 reps
-- threshold reps
-- over/unders (using step structure)
-- cadence skill repeats
-- repeated recovery/work structures
-
-### Allowed interval-set step types
-Inside an `interval_set`, steps can be:
-- `work`
-- `recovery`
-- `steady`
-- `ramp`
-
-This is important:
-- the outer block says “repeat this structure”
-- the inner steps say what the repeated structure actually is
-
-### Good uses
-
-#### Classic 3x VO2
-- interval_set repeat 3
-  - work 2m @ 115% FTP
-  - recovery 2m @ 50% FTP
-
-#### Threshold ladder
-- interval_set repeat 2
-  - steady 6m @ 100% FTP
-  - recovery 2m @ 55% FTP
-
-#### Cadence focus set
-- interval_set repeat 4
-  - steady 1m @ 75% FTP cadence 105+
-  - recovery 1m @ 50% FTP
-
----
-
-## 3.3 Climb block
-
-Composite terrain block:
-- `climb`
-
-Shape:
-- `id`
-- `type: "climb"`
-- `course` (a `CourseProfile`: name, source, totals, and `segments[]` of `{ distanceM, gradePct }`)
-- optional `pacingPctFtp` (default `0.85`)
-- optional `title`, `instructions[]`, `cadence`, `hr`
-
-A climb is a simulated ascent: the trainer runs in gradient simulation mode and follows the course's grade
-at the rider's virtual position, which the app computes from live watts, rider and bike mass, and the
-profile. The block ends when the rider reaches the end of the course, not on a timer. Its compiled
-`durationSec` is a physics estimate at `pacingPctFtp × FTP` and drives previews, TSS and zone time only.
-
-Rules:
-- `constraints.allowedExecutionModes` must include `"grade"`.
-- Get `course` from the planner's climb catalog (`lookup_climb`), a Strava segment import
-  (`import_strava_segment`), one of the rider's own Strava rides (`import_strava_activity_course`, source
-  kind `strava_activity`, optionally cut to a segment effort or distance window), a Strava route
-  (`import_strava_route`, source kind `strava_route`), a GPX file or public GPX link (`import_gpx_course`,
-  source kind `gpx`), a myCols or climbfinder page (`import_climb_page`, source kind `climb_page`), the
-  road between two places (`build_road_course`, source kind `road`, OpenStreetMap
-  geometry plus raster elevation) or generated terrain
-  (`generate_terrain_course`, source kind `synthetic`: a distance, average grade and shape, deterministic
-  for the same inputs). Saved workouts keep a snapshot of the course, so disconnecting Strava does not
-  remove the climb.
-- `athleteContext.weightKg` improves the estimate (75 kg when absent). Bike mass is fixed internally at 7.5 kg; legacy profile/workout bike weights are ignored. W/kg uses rider weight only.
-- Trainers without simulation mode ride the climb in ERG at the pacing watts.
-
-Validation warns when a course is under 300 m, averages under 1 %, or has grades outside −20..25 % (they
-are clamped for the trainer).
-
-Every ride also gets a virtual distance (`actualMetrics.distanceM`, `ascentM`): climbs from the course
-odometer, ERG steps as a flat road at the recorded power, written into the FIT file so Strava counts the
-mileage. After the ride, `summarize_session` reports each climb the rider started (`summary.climbs`): distance and
-ascent actually ridden from the app's virtual odometer, time, average power, VAM and whether the summit was
-reached. The app's ride history shows the same figures with the profile.
-
-## 3.4 Note block
-
-Support-only block type:
-- `note`
-
-Shape:
-- `id`
-- `type: "note"`
-- `text`
-
-Use for:
-- non-executable guidance
-- rider coaching context
-- explicit reminders that should survive revision/rendering
-
-Agents should use `note` sparingly.
-If the content changes the actual executable session shape, it should probably be a real workout block, not just a note.
-
----
-
-## 4. Target grammar
-
-Targets are also typed.
-This matters because agents should choose targets intentionally rather than describing them vaguely.
-
-Supported target modes:
-- `open`
-- `watts`
-- `pct_ftp`
-- `zone`
-- `ramp_watts`
-- `ramp_pct_ftp`
-- `resistance_level`
-- `grade_percent`
-
-## 4.1 Practical meaning
-
-### `open`
-No strict load target.
-Good for:
-- free ride
-- easy reset
-- technique-focused movement
-
-### `watts`
-Absolute target.
-Good when:
-- athlete FTP/context is already resolved
-- exact prescription matters
-
-### `pct_ftp`
-Relative target.
-Good default for authoring because:
-- portable across riders
-- easier for agents to reason about conceptually
-
-Important:
-- `%FTP` values are fractional in structured payloads
-- use `0.55` for `55% FTP`
-- use `1.15` for `115% FTP`
-- never pass whole percentages like `55` or `115`
-
-### `zone`
-Zone-based target.
-Good for:
-- simple endurance/recovery prescriptions
-- more human-facing authoring when exact percentage is unnecessary
-
-### `ramp_watts` / `ramp_pct_ftp`
-Progressive target from start -> end.
-Good for:
-- warmups
-- build phases
-- progressive efforts
-
-### `resistance_level`
-Trainer resistance mode target.
-Use when explicitly designing for resistance execution.
-
-### `grade_percent`
-Grade-mode target.
-Use when explicitly designing for grade/simulation execution.
-
----
-
-## 5. Additional per-block constraints/cues
-
-Blocks and interval steps can also carry:
-
-### cadence
-Shape:
-- `min`
-- `max`
-- `cue`
-
-Use for:
-- skill emphasis
-- spin-up drills
-- low-cadence strength cues
-
-### hr
-Shape:
-- `capBpm`
-- `softCapBpm`
-
-Use for:
-- safety bounds
-- recovery gating
-- keeping endurance/recovery blocks honest
-
-### instructions[]
-Use for:
-- rider-facing execution guidance
-- short coaching prompts
-- reminders that belong to the block itself
-
-Good examples:
-- `Relax shoulders`
-- `Stay seated`
-- `Smooth pedal stroke`
-- `Do not sprint the start`
-
----
-
-## 6. Workout-level constraints
-
-Workout-level constraints currently include:
-- `maxDurationSec`
-- `maxPctFtp`
-- `maxContinuousWorkSec`
-- `maxHrBpm`
-- `allowedExecutionModes`
-- `disallowStanding`
-- `avoidSprintStarts`
-- `indoorOnly`
-
-These are important because they tell the agent what *not* to build.
-
-Important:
-- `maxPctFtp` is also fractional
-- use `1.2` for `120% FTP`, not `120`
-
-Practical rule:
-- if the user request conflicts with workout constraints, the agent should prefer a legal workout + explanation over inventing an invalid one and hoping validation fixes it later
-
----
-
-## 7. Composition patterns agents should use
-
-These are not hardcoded templates.
-They are strong composition patterns.
-
-## 7.1 Endurance ride with gentle structure
-- warmup
-- steady endurance block
-- optional cadence drill inserts
-- cooldown
-
-## 7.2 VO2 session
-- warmup
-- interval_set(work/recovery x n)
-- cooldown
-
-## 7.3 Threshold / sweet spot session
-- warmup
-- longer steady work block(s)
-- recovery between blocks if needed
-- cooldown
-
-## 7.4 Skills session
-- warmup
-- cadence_drill or free_ride sections with explicit cadence cues
-- light steady aerobic work
-- cooldown
+Structured JSON is canonical. The renderer is implemented; no workout-text parser exists. See [workout-text-format.md](workout-text-format.md). Audited against `packages/domain/src/index.ts`, `packages/domain/src/course.ts`, `packages/contracts/src/tools.ts`, and `services/planner-api/src/service.ts`.
 
-## 7.5 Recovery session
-- warmup or very gentle open start
-- low-load steady / open blocks
-- cadence comfort cues
-- cooldown optional if already very easy
+## Drafting versus composing
 
----
+`draft_workout` generates a deterministic starter, not an arbitrary-block authoring language. Input is:
 
-## 8. What agents should usually do first
+```json
+{
+  "objective": "vo2max",
+  "durationMin": 20,
+  "constraints": { "maxPctFtp": 1.2, "allowedExecutionModes": ["erg"] },
+  "context": { "styleHints": ["three controlled efforts"] }
+}
+```
 
-When authoring from natural language, agents should generally choose in this order:
+Both MCP surfaces register the name `draft_workout`. The internal explicit-athlete surface uses `DraftWorkoutInputSchema` and also requires `athleteId`; the authenticated surface uses `DraftMyWorkoutInputSchema`, omits `athleteId`, and resolves the signed-in athlete. `draftMyWorkout` is a client/service method, not a separate MCP tool name. `durationMin` is a positive integer (no schema maximum; resulting workouts must be at most 24 hours). Only `maxPctFtp` and `allowedExecutionModes` are accepted draft constraints. `context.readinessSnapshotId` is an optional nonempty ID; it is not consulted by this deterministic builder. `styleHints` defaults to `[]` and is copied into rationale, **not interpreted to change blocks**. Mode preference is ERG, then resistance, then grade. Allowing grade does not generate a distance-based climb.
 
-1. infer the workout objective
-2. infer intended duration
-3. choose whether the workout is mostly:
-   - steady/simple blocks
-   - repeated intervals
-   - skills/free ride
-4. choose target style:
-   - `pct_ftp` is usually the safest authoring default
-   - `zone` is okay for simpler low-intensity prescriptions
-   - `watts` is better when exact absolute load matters
-5. add cadence / HR cues only when they actually help
-6. validate before saving
+For custom composition, take the returned `.workout`, edit its `blocks`, constraints, title and rationale, then pass `{ "workout": ... }` to validate and save. Draft, revise and validate are candidates/read-only with respect to the saved library; **save publishes**. Unknown object properties are generally stripped by Zod, not implemented: putting `blocks`, a custom title, or extra constraints in draft input does not author them.
 
----
+## Complete workout envelope
 
-## 9. How validation should fit into authoring
+Required fields (unless a default is stated):
 
-Current validation structure already includes:
-- `status: pass | warn | fail`
-- `issues[]`
-- each issue has:
-  - `code`
-  - `message`
-  - `path[]`
-  - `severity: warning | error`
+| Field | Contract |
+| --- | --- |
+| `id`, `athleteId` | Nonempty strings. Preserve server-returned identity when editing a candidate. |
+| `version` | Positive integer. Fresh draft is 1; revision candidate is base version + 1. |
+| `createdAt`, `updatedAt` | ISO datetime strings. |
+| `createdBy`, `updatedBy` | Actor objects below. |
+| `kind`, `sport` | Exactly `workout_definition`, `cycling_indoor`. |
+| `title` | Nonempty string (workout schema has no maximum). |
+| `objective` | `recovery`, `endurance`, `tempo`, `sweet_spot`, `threshold`, `vo2max`, `anaerobic`, `sprint`, `skills`, `test`, `custom`. |
+| `status` | `draft`, `validated`, `scheduled`, `retired`. Save recalculates status; do not claim validation by changing this field. |
+| `athleteContext` | Required `ftpWatts` > 0; optional `weightKg` > 0 and positive integer `maxHrBpm`; `constraints` string array defaults to `[]`. This context is a snapshot, not a live profile reference. |
+| `blocks` | Nonempty array of blocks below. At least one executable block is needed. |
+| `constraints` | Defaults to the constraint defaults below. |
+| `rationale` | Required `summary` string (can be empty); `whyToday` string array defaults `[]`; optional `adaptationGoal` string, `confidence` in [0,1]. |
+| `tags` | String array, default `[]`. |
 
-That is already a strong base for agent loops.
+Optional: `scheduledDate` (`YYYY-MM-DD` regex; use scheduling tools to manage the library day, never to start a ride), `sourceWorkoutId` (nonempty string), `computed`, `validation`, `sharing`, `workoutFingerprint`.
 
-The practical loop should be:
-1. draft from blocks
-2. validate
-3. inspect issue `severity`
-4. use issue `path` to identify which block or step is the problem
-5. revise only the relevant part
-6. validate again
+Actors are exactly one of:
 
-That is much better than “draft once and hope.”
+```json
+{"type":"user","userId":"user-id"}
+{"type":"agent","agentId":"agent-id","runId":"optional-run-id","promptRef":"optional-prompt-id"}
+{"type":"system","system":"validator"}
+```
 
----
+System choices: `scheduler`, `runtime`, `validator`, `importer`. IDs are nonempty. Retain draft attribution rather than fabricate actors. `sharing` is server-owned lineage: `originalWorkoutId`, `originalWorkoutVersion`, `originalShareId`, `originalFingerprint`, `sourceWorkoutId`, `sourceWorkoutVersion`, `shareId`. Versions are positive integers, share IDs UUIDs, fingerprints match `^v1:[a-f0-9]{64}$`. After input schema parsing, `saveWorkout` overwrites `sharing` with the latest saved record’s lineage, or clears it for a new ID, then computes `workoutFingerprint`; do not synthesize either. This ownership rule concerns `sharing`, not the separate top-level `sourceWorkoutId`. Malformed supplied lineage can still fail input parsing before it is discarded.
 
-## 10. What usually validates/revises well
+`computed` has positive integer `durationSec`, nonnegative `intensityFactor`, `tss`, optional nonnegative `estimatedKj`, and `zoneDistributionSec` with nonnegative z1–z5 and optional z6–z7. `validation` has `status: pass|warn|fail`, `issues` default `[]`; each issue has string `code`, `message`, string-array `path` default `[]`, and `severity: warning|error`. Remove stale computed/validation after edits; validation/save recompute them.
 
-Agents will usually do better when they:
-- use a clear warmup / work / cooldown shape
-- use `pct_ftp` rather than over-specific absolute watts too early
-- keep repeated sets explicit with `interval_set`
-- keep rider coaching in `instructions[]` rather than in long prose
-- use workout constraints honestly
-- treat `validate` as part of authoring, not as a final optional extra
+## All block primitives
 
----
+Executable blocks share `id` (nonempty), optional `title` string, `instructions` string array default `[]`, optional `cadence` and `hr`.
 
-## 11. Common mistakes agents should avoid
+| Type | Required additional fields | Meaning |
+| --- | --- | --- |
+| `warmup`, `steady`, `recovery`, `cooldown`, `ramp`, `free_ride`, `cadence_drill`, `rest` | `durationSec`: positive integer; optional `target` | One timed step. Type alone does **not** set power, ramp, or trainer mode. `rest` is not automatically zero watts; `free_ride` with a power target is ERG. |
+| `interval_set` | `repeat`: positive integer; `steps`: nonempty array | Repeat the complete step sequence. No outer duration or target. |
+| `climb` | `course`: full course object; optional `pacingPctFtp` | Distance-ended simulation; no authored `durationSec` or `target`. |
+| `note` | `id`, `type`, `text`: nonempty string | No duration, target, instructions, cadence, HR or title. Not executable. |
 
-### 1. Treating notes as executable structure
-If it affects the ride shape, make it a block.
+Interval steps use the shared fields plus positive integer `durationSec` and optional `target`, but **only** `work`, `recovery`, `steady`, `ramp` types. No nested sets, climbs, notes, warmups, cooldowns, cadence-drill or rest step types. `work` is not a top-level simple type. Use a `steady` interval step with cadence cues for repeated skills work. There is no schema maximum repeat/step count; keep expansions reasonable and total duration <= 86,400 seconds.
 
-### 2. Overusing vague prose instead of typed blocks
-The more vague the workout description, the harder it is to revise and validate.
+Interval compilation expands every repetition. Runtime IDs are `<set-id>:r1:s1` etc., not the step's authored ID. Parent and step instructions merge with duplicate strings removed. Cadence minimum/cue use child value when present, otherwise parent; cadence maximum and both HR caps use the **lower** parent/child value. Parent set title does not become each step title. Notes disappear from execution.
 
-### 3. Using live adaptation to solve pre-execution authoring problems
-If the workout is not yet running, revise the saved workout.
-Do not force everything through `session adapt`.
+## Combining primitives into a session
 
-### 4. Inventing unsupported runtime changes
-Current live ops are bounded.
-Structural edits like “add another interval right now” are not first-class runtime ops today.
+`blocks` execute in array order; there is no parallel execution or conditional branching. Each `interval_set` expands its whole sequence for every repetition before the next top-level block begins. Recovery at the end of a set repeats too, including after the final effort.
 
-### 5. Ignoring constraints and expecting validate to rescue everything
-Validation is a loop, not a magic trash compactor.
+| Recipe | Composition and timing |
+| --- | --- |
+| VO2 repetitions | Warmup → set of work + recovery → cooldown. 300 + 3 × (120 + 120) + 180 = 1,200 seconds. See the complete example below. |
+| Over/unders | Warmup → set with two `work` steps at different FTP fractions → recovery → cooldown. Both efforts count as continuous work when each is >= .88 FTP; an “under” is not automatically recovery. |
+| Ladder | Differently timed work/recovery steps in a set with `repeat: 1`, or multiple sets in `blocks`. Do not nest sets. |
+| Two sets with a long break | First set → top-level recovery → second set. Put the long recovery outside the sets so it is not repeated. |
+| ERG + terrain | Power warmup → climb with a returned full `course` → power cooldown. Allow both `erg` and `grade`; total duration includes a climb estimate, not a fixed finish time. |
+| Repeated cadence skills | Set of `steady` steps with cadence and instructions, not `cadence_drill` children. Child cadence/HR inheritance follows the rules above. |
 
----
+Choose targets separately from block labels: a `ramp` needs a ramp target to ramp power; a `recovery` label does not supply recovery watts. Include all non-open modes used in `allowedExecutionModes`. Calculate duration limits for the whole composition, not one repetition. Prefer distinct block IDs and retain the workout envelope; combine authored blocks, not saved workout envelopes or runtime plans.
 
-## 12. Recommended next implementation follow-on
+## All target JSON variants
 
-The next code/doc layers that fit this grammar well are:
-- a canonical text notation for workouts
-- a structured/chat-friendly workout renderer
-- validation feedback that references block/step locations more explicitly in human terms
+Bounds are inclusive unless marked `>`. Numerical values need not be integers unless specified.
 
-Those should sit on top of this block grammar, not replace it.
+| Exact object example | Schema limits | Runtime |
+| --- | --- | --- |
+| `{"mode":"open"}` | No value | Open |
+| `{"mode":"watts","value":200}` | value > 0, no schema upper bound | ERG watts |
+| `{"mode":"pct_ftp","value":0.88}` | 0 < value <= 3 | ERG, rounded fraction × FTP |
+| `{"mode":"zone","value":"z2"}` | z1, z2, z3, z4, z5, z6, z7 | ERG using fixed fractions below |
+| `{"mode":"ramp_watts","start":100,"end":180}` | Both > 0 | ERG start/end watts |
+| `{"mode":"ramp_pct_ftp","start":0.55,"end":0.7}` | Each > 0 and <= 3 | ERG start/end, each rounded fraction × FTP |
+| `{"mode":"resistance_level","value":35}` | 0..100 | Resistance |
+| `{"mode":"grade_percent","value":4}` | −20..25 | Timed constant grade; not a distance-ended climb |
+
+Missing target executes open. No implicit default intensity is assigned. Fractions are **0.55 for 55%**, never 55. Zero watts / zero FTP fraction is rejected; use open or a supported resistance target, not an invented zero-watt target. Ramps may ascend, descend or stay equal, and any simple block/interval step may carry any target variant.
+
+Zone targets do not use the athlete's configured zone ranges: fixed fractions are z1=.50, z2=.68, z3=.83, z4=.98, z5=1.13, z6=1.35, z7=1.65. Ramps use their endpoint **average** for intensity validation and metrics, not endpoint peak. Check endpoints yourself when enforcing a strict peak ceiling.
+
+## Cadence, HR and workout constraints
+
+`cadence` is `{ "min": 85, "max": 100, "cue": "Smooth pedalling" }`; all fields optional, min/max positive integers. No min<=max check exists. `hr` is `{ "capBpm": 165, "softCapBpm": 155 }`; both optional positive integers. Empty cadence/HR objects are schema-valid. These are not conditional branching/recovery-gate instructions.
+
+Compiler emits cadence **maximum** and the lower hard/soft HR cap as step safety bounds; cadence minimum/cue are not runtime target fields. Put essential rider cues in `instructions` too. Workout max HR / max FTP produce default safety bounds.
+
+| Constraint | Range / default |
+| --- | --- |
+| `maxDurationSec` | Optional positive integer; global 24-hour ceiling also applies. |
+| `maxPctFtp` | Optional fraction > 0 and <= 3. |
+| `maxContinuousWorkSec` | Optional positive integer. |
+| `maxHrBpm` | Optional positive integer. Athlete context max HR alone does not set this constraint. |
+| `allowedExecutionModes` | Array of `erg`, `resistance`, `grade`; default `["erg"]`. Empty allowed by schema. Open execution is always permitted; `open` is not an allowed-array enum value. |
+| `disallowStanding` | Boolean default false. |
+| `avoidSprintStarts` | Boolean default false. |
+| `indoorOnly` | Boolean default true; sport is still indoor cycling when false. |
+
+## Climb course authoring and attribution
+
+Prefer a full `course` returned by catalog lookup/import/generation over manually inventing geography. Supported source kinds: `catalog`, `strava_segment`, `strava_route`, `strava_activity`, `gpx`, `road`, `climb_page`, `synthetic`, `manual`. Preserve source provenance and attribution. Workouts store a snapshot, not a dependency on a connected source account.
+
+A `course` requires:
+
+- `id`, `name`: nonempty strings.
+- `source`: required `kind` enum above; optional string `externalId`, valid URL `url`, string `attribution`, ISO datetime `importedAt`.
+- `totalDistanceM` > 0; `totalAscentM` >= 0; `totalDescentM` >= 0 defaults 0.
+- `averageGradePct`, `maxGradePct`: numbers.
+- `segments`: nonempty array of `{ "distanceM": positiveNumber, "gradePct": numberFromMinus30To35 }`.
+- Optional `region` string, numeric `startElevationM`, `summitElevationM`, `climbCategory`: `hc|1|2|3|4|uncategorized`.
+- Optional `track`: 2..300 points with `distanceM` >= 0, latitude −90..90, longitude −180..180. Keep distances ordered and totals consistent; schema does not cross-check aggregate totals against segments. `buildCourseProfile` computes totals/category and downsamples tracks locally.
+
+`pacingPctFtp` is > 0 and <= 3, resolved default **0.85** (not inserted as a schema default). Compiled pacing watts = rounded FTP × fraction. Estimate uses rider mass from `athleteContext.weightKg` or 75 kg, fixed bike mass 7.5 kg, and elevation when available. Legacy bike weights are ignored.
+
+Include `grade` in allowed modes (and `erg` for power-target warmup/cooldown). Compiler emits grade mode, clamped mean-grade initial target, segment grades clamped to −20..25%, and a course runtime payload carrying attribution/pacing/physics. The runtime tracks live virtual distance and finishes at the course end, **not** the estimated duration. Unsupported simulation hardware can fall back to pacing-watts ERG in the app; the compiler still requires grade authorization. Changing pacing changes estimated duration/TSS, not the terrain or a guaranteed completion time. Duration constraints on climbs are therefore preview estimates, not time guarantees.
+
+Warnings: total distance < 300 m (`climb.course.too_short`), mean grade < 1% (`climb.course.flat`), any segment outside trainer −20..25% (`climb.course.grade_clamped`). Source segment schema still rejects outside −30..35%.
+
+## Validation is necessary, not a complete coaching/safety proof
+
+Call `validate_workout` with `{ "workout": candidate }`. It returns `validation`, `computed`, and (unless validation fails) `runtimePlanPreview`. Schema errors happen before semantic validation. A fail blocks artifact runtime compilation; calling the low-level compiler alone is not validation.
+
+Implemented semantic checks:
+
+- No executable steps; global 24-hour / authored max duration exceedance.
+- Intensity above max FTP, based on constant/zone/ramp-mean/climb-pacing intensity.
+- Non-open execution mode absent from allowed modes.
+- Lower of step hard/soft HR caps greater than workout max HR.
+- Standing text detected with `disallowStanding`: regex `\bstand(?:ing)?\b` in executable title/cadence cue/instructions. Even “do not stand” matches; use “stay seated”. Note text is not checked.
+- Missing target warnings only for `steady`, `ramp`, `work`. Explicit `open` does not warn.
+- Continuous work adds consecutive known-intensity steps >= .88 FTP except `recovery`, `cooldown`, `rest`; other steps reset it. This is not simply the duration of an interval set.
+- With `avoidSprintStarts`, known intensity >= 1.2 starting before elapsed 120 seconds is an error except warmup/recovery/cooldown. First known intensity >= 1.2 also warns, even when preceded by open steps.
+- Climb warnings above. No mandatory warmup/cooldown/cadence-drill cue or objective-specific physiology checks.
+
+Issue paths use zero-based string indices, e.g. `["blocks","1","steps","0","repeat","2"]`. `describeWorkoutPath` renders “block 2 > step 1 > repeat 3”; do not interpret indices as text line numbers.
+
+Metrics: duration sums flattened steps; ramps count wholly in their average-intensity zone, not split over zones. Unknown effort (open/resistance/constant grade) contributes zero modeled power/IF/TSS and z1 time, not evidence of zero actual effort. Climbs use pacing. IF is root-mean-square duration-weighted FTP ratio (rounded 3 decimals), TSS = hours × IF² × 100 (1 decimal); estimated kJ uses duration-weighted mean power. Zone boundaries are <.56, <.76, <.91, <1.06, <1.21, <1.51, then z7.
+
+Save recalculates artifacts; `expectedValidationStatus` (`pass|warn|fail`) is an equality guard, not an override. Failing workouts can be saved as `draft` (except >24 hours, rejected); passing/warning workouts save as `validated`, unless retired. Thus require the validated status you reviewed, rather than assuming save rejects all errors. Notes-only candidates also have zero computed duration, which conflicts with the positive-duration output schema: keep an executable step.
+
+## Edit → revalidate → save loop
+
+1. Keep the complete candidate as `{ "workout": ... }` in `candidate.json`. Edit this definition, not the compiled runtime preview. Unsaved drafts can be edited directly; a saved workout needs a new version (see revisions below).
+2. Remove stale `computed` and `validation` fields after edits. Keep athlete context and constraints intentional: FTP, targets, repetition counts, courses and pacing can all affect validation and load estimates.
+3. Run `wattson --json workout validate --input-file candidate.json > validation.json` (MCP: `validate_workout` with the same object). A successful request/exit code is not a validation pass.
+4. Inspect `validation.status` and every issue's `code`, `path`, `severity` and `message`. Fix schema errors first; locate semantic failures in the authored block/step using the issue path. Repair the actual mismatch, not its status label. Do not loosen a rider's safety constraint simply to obtain a pass.
+5. Repeat validation after **every** edit: the previous result no longer describes the edited candidate. Check `computed.durationSec`, load estimates and `runtimePlanPreview` for the intended order, repetitions, modes and targets. Review warnings; repair failures before treating the workout as rideable.
+6. Construct save input from the exact candidate just reviewed, with `expectedValidationStatus` equal to the reviewed status (`pass` by default). Validation returns artifacts, not a replacement workout. The guard compares status only; it does not bind a previous validation response to the candidate. Save recomputes validation.
+7. For saved-workout edits include `expectedLatestVersion` for the saved base. On conflict, fetch the latest workout, reapply intended edits and validate again; do not blindly change the guard and retry. Fetch the returned saved ID/version and runtime plan to verify persistence.
+
+The [command reference](commands.md#revise-a-saved-version) has a guarded revision sequence; the composition example below supplies a complete new-workout sequence. Neither validation nor revision updates an in-progress ride.
+
+## Revisions: supported patch and actual limitations
+
+`revise_workout` takes `{ "patch": ... }`, not a full workout. Both MCP surfaces register this same name and use `ReviseWorkoutInputSchema`; neither takes `athleteId`. The authenticated surface calls the client/service method `reviseMyWorkout` and checks ownership of the saved base before revision. It loads a **saved** base; use direct JSON edits for an unsaved draft.
+
+```json
+{
+  "patch": {
+    "workoutId": "saved-id",
+    "baseVersion": 1,
+    "preserve": ["objective", "interval_structure"],
+    "changes": { "newTitle": "Controlled VO2", "intensityMultiplier": 0.95 },
+    "naturalLanguage": "Make the efforts a little easier",
+    "reason": "Reduce today's load"
+  }
+}
+```
+
+Required: nonempty `workoutId`, positive integer `baseVersion`, string `reason`. `naturalLanguage` is optional descriptive text, **not parsed into operations**. `preserve` defaults `[]`; `changes` defaults `{}`. All change fields are optional:
+
+| Change | Contract and actual implementation |
+| --- | --- |
+| `newTitle` | Trimmed nonempty string, max 100 chars. |
+| `newObjective` | Objective enum; label only, does not rebuild structure. |
+| `durationDeltaSec` | Integer; implementation clamps to −600..600, modifies from tail. Negative edits leave changed steps >=30s. Positive edits add to last simple block or last step of last set; repeats multiply the real total change. The helper does not skip notes/climbs: a trailing one has no `durationSec`, so positive edits assign `NaN`; negative edits also poison the remaining subtraction with `NaN`, preventing earlier timed blocks from being shortened. Hand-edit those compositions instead. |
+| `intensityMultiplier` | Schema .7..1.2, implementation clamps to **.8..1.1**. Scales watts/fractions/resistance and ramp endpoints. Zone/open/constant-grade targets unchanged. Climbs scale pacing (clamped .2..3), changing estimated duration too. Other scaled values can exceed target schema limits and make the revision output fail schema parsing (e.g. resistance 100 × 1.1). |
+| `addCadenceFocus` | Boolean; adds min85/max105/cue to non-note top-level blocks without any cadence object, including sets/climbs. Does not replace existing cadence or directly edit child steps. |
+| `removeLastInterval` | Boolean; despite name, current code removes the **last non-interval-set top-level block**, often cooldown/note/climb. It does not remove a repetition. Hand-edit blocks for a real interval deletion. |
+| `switchToRecovery` | Boolean; only rewrites top-level `recovery` targets. Absent target becomes .55 FTP; numeric `value` becomes .55 **in its existing mode** (including watts/resistance/grade). Ramps/zones/open and interval children unchanged; objective unchanged. Not a general recovery transformation. |
+
+Preserve semantics:
+
+- `objective` suppresses `newObjective` only.
+- `duration` suppresses `durationDeltaSec` only; removal/climb-pacing edits can still change total time.
+- `interval_structure` suppresses `removeLastInterval` and `addCadenceFocus`, not intensity/duration edits.
+- `tss` is accepted and echoed but **not enforced**. Do not promise TSS preservation.
+
+Operation order: removal, duration, intensity, cadence, recovery shift, title/objective. A duration change moves `maxDurationSec` only if old cap equalled old computed duration; independent caps remain. Returned diff includes requested intent (not necessarily applied operation), actual final duration and preserve flags. Review candidate blocks and validation, not only diff intent. Revision increments version and timestamp but does not save; save the returned workout with `expectedLatestVersion` set to the base/latest saved version. Direct manual revisions similarly preserve ID, increment version and use the concurrency guard. Retain creation metadata and provide truthful updated attribution.
+
+Implementation evidence: MCP names/schemas are in `services/planner-mcp/src/tools.ts` (`registerWriteTools`, `registerPublicWriteTools`). Revision behavior is in `services/planner-api/src/service.ts` (`withRecoveryShift`, `scaleTargetValue`, `withRemovedLastInterval`, `withDurationDelta`, `reviseWorkout`); lineage overwrite is in `saveWorkout`. These are current implementation quirks, not desired coaching semantics.
+
+## Full composition example: draft → edit → validate → save
+
+This builds an exact 20-minute session: 5-minute warmup, three 2-minute efforts each followed by 2-minute recovery, 3-minute cooldown. Drafting supplies the real athlete/metadata envelope; the script replaces every structural field it needs, without inventing server IDs or computed values. CLI examples assume an authenticated `wattson`; see [commands.md](commands.md) for installation/authentication.
+
+```sh
+wattson workout draft --objective vo2max --duration-min 20 --json > draft.json
+```
+
+Save this as `compose-workout.mjs` and run `node compose-workout.mjs`:
+
+```js
+import { readFileSync, writeFileSync } from 'node:fs';
+const { workout } = JSON.parse(readFileSync('draft.json', 'utf8'));
+if (!workout) throw new Error('Expected draft response with workout');
+workout.title = 'Controlled VO2 20';
+workout.objective = 'vo2max';
+workout.blocks = [
+  { id: 'warmup', type: 'warmup', durationSec: 300,
+    target: { mode: 'ramp_pct_ftp', start: 0.55, end: 0.7 },
+    instructions: ['Build smoothly'] },
+  { id: 'efforts', type: 'interval_set', repeat: 3,
+    cadence: { min: 85, max: 105 }, instructions: ['Stay seated'],
+    steps: [
+      { id: 'work', type: 'work', durationSec: 120,
+        target: { mode: 'pct_ftp', value: 1.15 },
+        instructions: ['Do not sprint the start'] },
+      { id: 'recover', type: 'recovery', durationSec: 120,
+        target: { mode: 'pct_ftp', value: 0.5 }, instructions: [] }
+    ] },
+  { id: 'cooldown', type: 'cooldown', durationSec: 180,
+    target: { mode: 'ramp_pct_ftp', start: 0.55, end: 0.45 },
+    instructions: ['Ease down gradually'] }
+];
+workout.constraints = {
+  ...workout.constraints,
+  maxDurationSec: 1200, maxPctFtp: 1.2, maxContinuousWorkSec: 120,
+  allowedExecutionModes: ['erg'], disallowStanding: true,
+  avoidSprintStarts: true, indoorOnly: true
+};
+workout.rationale = {
+  summary: 'Three controlled two-minute VO2 efforts with equal recovery.',
+  whyToday: ['Explicit 20-minute composition; confirm suitability for the rider.'],
+  adaptationGoal: 'Sustained high-aerobic efforts with controlled starts'
+};
+workout.tags = ['vo2max', '20min', 'mode:erg'];
+delete workout.computed;
+delete workout.validation;
+writeFileSync('candidate.json', JSON.stringify({ workout }, null, 2));
+```
+
+```sh
+wattson workout validate --input-file candidate.json --json > validation.json
+```
+
+Inspect all issues and runtime preview, then prepare a guarded save only for a pass:
+
+```js
+// Run as a separate .mjs file after validation.
+import { readFileSync, writeFileSync } from 'node:fs';
+const candidate = JSON.parse(readFileSync('candidate.json', 'utf8'));
+const result = JSON.parse(readFileSync('validation.json', 'utf8'));
+if (result.validation.status !== 'pass') {
+  throw new Error(JSON.stringify(result.validation));
+}
+if (result.computed.durationSec !== 1200 || result.runtimePlanPreview.steps.length !== 8) {
+  throw new Error('Unexpected compilation');
+}
+writeFileSync('save.json', JSON.stringify({
+  workout: candidate.workout, expectedValidationStatus: 'pass'
+}, null, 2));
+```
+
+```sh
+wattson workout save --input-file save.json --json
+```
+
+This final command persists to the selected account; validation does not. For a revision, add `expectedLatestVersion` to save input. Never save merely to test documentation. The example was checked locally against the schema/compiler and an isolated in-memory planner service, without production writes.