@trainheroic-unofficial/cli 3.4.0 → 3.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/cli.mjs CHANGED
@@ -272,6 +272,15 @@ const athleteWorkoutNoteArgsSchema = z.object({
272
272
  notes: z.string().optional(),
273
273
  rpe: z.number().int().min(1).max(10).optional()
274
274
  }).refine((v) => v.notes !== void 0 || v.rpe !== void 0, { message: "Provide notes and/or rpe" });
275
+ /**
276
+ * Args for the athlete per-exercise note write (the "Add exercise note" box on the exercise
277
+ * screen — band color, etc.). `savedWorkoutSetExerciseId` is the slot id from athlete_log_targets.
278
+ * Empty `notes` clears the note. Distinct from {@link athleteWorkoutNoteArgsSchema} (session note).
279
+ */
280
+ const athleteExerciseNoteArgsSchema = z.object({
281
+ savedWorkoutSetExerciseId: idArgSchema,
282
+ notes: z.string()
283
+ });
275
284
  const presentedNullNumber = z.number().nullable();
276
285
  const presentedNullString = z.string().nullable();
277
286
  /** Flattened exercise within a presented workout: prescriptions, logged results, units. */
@@ -279,6 +288,7 @@ const athleteWorkoutExerciseSchema = z.object({
279
288
  exerciseId: presentedNullNumber,
280
289
  title: z.string(),
281
290
  instruction: presentedNullString,
291
+ notes: presentedNullString,
282
292
  units: z.array(presentedNullString),
283
293
  prescribed: z.array(z.string()),
284
294
  performed: z.array(z.string())
@@ -387,6 +397,7 @@ z.array(rosterActivityRowSchema);
387
397
  const presentedExerciseSessionSchema = z.object({
388
398
  date: z.string(),
389
399
  abr: presentedNullString,
400
+ notes: presentedNullString,
390
401
  estimated1RM: presentedNullNumber,
391
402
  sets: z.array(z.object({
392
403
  setNumber: z.number(),
@@ -526,6 +537,7 @@ const logSetTargetOutputSchema = z.object({
526
537
  savedWorkoutSetExerciseId: z.number(),
527
538
  title: z.string(),
528
539
  units: z.array(nullableString),
540
+ notes: nullableString,
529
541
  prescribed: z.array(z.string()),
530
542
  performed: z.array(z.string())
531
543
  }))
@@ -600,6 +612,10 @@ z.object({
600
612
  notes: z.string(),
601
613
  rpe: nullableNumber
602
614
  });
615
+ z.object({
616
+ savedWorkoutSetExerciseId: z.number(),
617
+ notes: z.string()
618
+ });
603
619
  const workoutReadExerciseOutputSchema = z.object({
604
620
  order: z.number(),
605
621
  title: z.string(),
@@ -702,6 +718,12 @@ const exerciseSpecSchema = z.object({
702
718
  instr: z.string().optional(),
703
719
  param_1_type: z.number().optional(),
704
720
  param_2_type: z.number().optional()
721
+ }).superRefine((exercise, ctx) => {
722
+ if (Array.isArray(exercise.reps) && Array.isArray(exercise.weight) && exercise.reps.length !== exercise.weight.length) ctx.addIssue({
723
+ code: "custom",
724
+ message: `Per-set reps and weight arrays must have the same length; received ${exercise.reps.length} reps and ${exercise.weight.length} weights.`,
725
+ path: ["weight"]
726
+ });
705
727
  });
706
728
  /** A block's Red-Zone leaderboard: a unit string/number, or an object with options. */
707
729
  const leaderboardSpecSchema = z.union([
@@ -1407,6 +1429,16 @@ function performedSlotsByExerciseId(sets) {
1407
1429
  }
1408
1430
  return map;
1409
1431
  }
1432
+ /** Per-exercise athlete notes keyed by the prescription template id (`workout_set_exercise_id`). */
1433
+ function notesByTemplateId(sets) {
1434
+ const map = /* @__PURE__ */ new Map();
1435
+ for (const { exercises } of sets) for (const ex of exercises) {
1436
+ const id = coerceInt(ex.workout_set_exercise_id);
1437
+ const notes = str$1(ex.notes);
1438
+ if (id !== null && notes !== null) map.set(id, notes);
1439
+ }
1440
+ return map;
1441
+ }
1410
1442
  /** Align an exercise's prescribed slots with the slots the athlete logged, per set index. */
1411
1443
  function mergeExercise(prescribed, performed, meta) {
1412
1444
  const indices = [.../* @__PURE__ */ new Set([...prescribed.keys(), ...performed.keys()])].sort((a, b) => a - b);
@@ -1420,7 +1452,7 @@ function mergeExercise(prescribed, performed, meta) {
1420
1452
  };
1421
1453
  }
1422
1454
  /** A prescription block, each exercise aligned with the slots the athlete logged against it. */
1423
- function mergePrescriptionBlock(set, performedById) {
1455
+ function mergePrescriptionBlock(set, performedById, notesById) {
1424
1456
  const exercises = Array.isArray(set.workoutSetExercises) ? set.workoutSetExercises : [];
1425
1457
  return {
1426
1458
  order: coerceInt(set.order) ?? 0,
@@ -1434,6 +1466,7 @@ function mergePrescriptionBlock(set, performedById) {
1434
1466
  exerciseId: coerceInt(ex.exercise_id),
1435
1467
  title: typeof ex.title === "string" ? ex.title : "",
1436
1468
  instruction: str$1(ex.instruction),
1469
+ notes: id !== null ? notesById.get(id) ?? null : null,
1437
1470
  units: exerciseUnits(ex.param_1_type, ex.param_2_type)
1438
1471
  });
1439
1472
  })
@@ -1450,6 +1483,7 @@ function mergeSavedBlock(set, exercises) {
1450
1483
  exerciseId: coerceInt(ex.exercise_id),
1451
1484
  title: typeof ex.exercise_title === "string" ? ex.exercise_title : "",
1452
1485
  instruction: str$1(ex.instruction),
1486
+ notes: str$1(ex.notes),
1453
1487
  units: exerciseUnits(ex.param_1_type, ex.param_2_type)
1454
1488
  }))
1455
1489
  };
@@ -1468,7 +1502,8 @@ function mergeAthleteWorkout(raw) {
1468
1502
  const prescriptionSets = (Array.isArray(workout.workoutSets) ? workout.workoutSets : []).filter(isRecord);
1469
1503
  const logged = savedSets(saved);
1470
1504
  const performedById = performedSlotsByExerciseId(logged);
1471
- const blocks = prescriptionSets.map((s) => mergePrescriptionBlock(s, performedById)).sort((a, b) => a.order - b.order);
1505
+ const notesById = notesByTemplateId(logged);
1506
+ const blocks = prescriptionSets.map((s) => mergePrescriptionBlock(s, performedById, notesById)).sort((a, b) => a.order - b.order);
1472
1507
  const prescribedIds = /* @__PURE__ */ new Set();
1473
1508
  for (const s of prescriptionSets) {
1474
1509
  const exs = Array.isArray(s.workoutSetExercises) ? s.workoutSetExercises : [];
@@ -1514,6 +1549,7 @@ function toStringExercise(ex) {
1514
1549
  exerciseId: ex.exerciseId,
1515
1550
  title: ex.title,
1516
1551
  instruction: ex.instruction,
1552
+ notes: ex.notes,
1517
1553
  units: ex.units,
1518
1554
  prescribed: sideStrings(ex.sets, (s) => s.prescribed),
1519
1555
  performed: sideStrings(ex.sets, (s) => s.performed)
@@ -1673,6 +1709,7 @@ function presentLogTargets(list) {
1673
1709
  savedWorkoutSetExerciseId: id,
1674
1710
  title: exerciseTitle(ex),
1675
1711
  units: exerciseUnits(ex.param_1_type, ex.param_2_type),
1712
+ notes: str$1(ex.notes),
1676
1713
  prescribed: prescribedStrings(ex),
1677
1714
  performed: performedStrings(ex)
1678
1715
  };
@@ -1788,6 +1825,7 @@ function presentExerciseHistory(detail) {
1788
1825
  sessions: (detail.history ?? []).map((h) => ({
1789
1826
  date: h.dateCompleted,
1790
1827
  abr: h.abr ?? null,
1828
+ notes: str$1(h.notes),
1791
1829
  estimated1RM: h.bestEstimated1RM ?? null,
1792
1830
  sets: (h.sets ?? []).map((s) => ({
1793
1831
  setNumber: s.setNumber,
@@ -2551,6 +2589,28 @@ async function setAthleteWorkoutNote(client, args) {
2551
2589
  };
2552
2590
  }
2553
2591
  //#endregion
2592
+ //#region ../js/src/athlete-exercise-note.ts
2593
+ /**
2594
+ * PUT /1.0/athlete/savedworkoutsetexercise/{id} — set the athlete's per-exercise note (the
2595
+ * "Add exercise note" box on the exercise screen). A notes-only body leaves logged reps/weight
2596
+ * untouched. Empty `notes` clears the note. GET on that path 405s; the range read and exercise
2597
+ * history both echo the stored string. Coach-visible.
2598
+ */
2599
+ async function setAthleteExerciseNote(client, args) {
2600
+ const savedWorkoutSetExerciseId = coerceInt(args.savedWorkoutSetExerciseId);
2601
+ if (savedWorkoutSetExerciseId === null) throw new Error(`Invalid savedWorkoutSetExerciseId ${String(args.savedWorkoutSetExerciseId)}.`);
2602
+ const res = await client.request("PUT", `/1.0/athlete/savedworkoutsetexercise/${savedWorkoutSetExerciseId}`, { body: {
2603
+ id: savedWorkoutSetExerciseId,
2604
+ notes: args.notes
2605
+ } });
2606
+ if (!res.ok) throw new Error(`Set exercise note failed (HTTP ${res.status}).`);
2607
+ const data = isRecord(res.data) ? res.data : {};
2608
+ return {
2609
+ savedWorkoutSetExerciseId,
2610
+ notes: typeof data.notes === "string" ? data.notes : args.notes
2611
+ };
2612
+ }
2613
+ //#endregion
2554
2614
  //#region ../js/src/workout-export.ts
2555
2615
  const DEFAULT_FILENAME_BASE = "trainheroic-workout-history";
2556
2616
  /** Pretty-printed JSON of the structured workouts, exactly as `presentAthleteWorkoutsExport` yields. */
@@ -2768,9 +2828,75 @@ function repsList(ex) {
2768
2828
  const reps = ex.reps;
2769
2829
  if (Array.isArray(reps)) return reps.map((r) => String(r));
2770
2830
  if (reps === void 0 || reps === null) return [];
2771
- const sets = Math.max(1, Math.trunc(Number(ex.sets ?? 1)) || 1);
2831
+ const sets = Array.isArray(ex.weight) ? ex.weight.length : Math.max(1, Math.trunc(Number(ex.sets ?? 1)) || 1);
2772
2832
  return Array.from({ length: sets }, () => String(reps));
2773
2833
  }
2834
+ /** Number of sets that the encoder will write for an exercise. */
2835
+ function exerciseSetCount(ex) {
2836
+ if (Array.isArray(ex.reps) && ex.reps.length > 0) return ex.reps.length;
2837
+ if (Array.isArray(ex.weight)) return ex.weight.length;
2838
+ if (!Array.isArray(ex.reps) && ex.reps !== void 0 && ex.reps !== null || ex.weight !== void 0 && ex.weight !== null) return Math.max(1, Math.trunc(Number(ex.sets ?? 1)) || 1);
2839
+ return 0;
2840
+ }
2841
+ function findSetSplits(blocks) {
2842
+ return blocks.flatMap((block) => block.exercises.flatMap((exercise) => {
2843
+ const setCount = exerciseSetCount(exercise);
2844
+ if (setCount <= 10) return [];
2845
+ return [{
2846
+ blockTitle: block.title,
2847
+ exerciseTitle: exercise.title ?? String(exercise.id),
2848
+ setCount,
2849
+ blockCount: Math.ceil(setCount / 10)
2850
+ }];
2851
+ }));
2852
+ }
2853
+ function setSplitSummary(blocks) {
2854
+ const splits = findSetSplits(blocks);
2855
+ if (splits.length === 0) return null;
2856
+ return `TrainHeroic supports at most 10 sets per exercise block. The following will be split into consecutive same-titled blocks: ${splits.map(({ blockTitle, exerciseTitle, setCount, blockCount }) => `${blockTitle} / ${exerciseTitle}: ${setCount} sets into ${blockCount} blocks`).join("; ")}.`;
2857
+ }
2858
+ function sliceExercise(exercise, setCount, start) {
2859
+ if (start > 0 && setCount <= start) return null;
2860
+ const chunkCount = setCount === 0 ? 0 : Math.min(10, Math.max(0, setCount - start));
2861
+ const chunk = { ...exercise };
2862
+ const hasPerSetReps = Array.isArray(exercise.reps) && exercise.reps.length > 0;
2863
+ const hasScalarReps = !Array.isArray(exercise.reps) && exercise.reps !== void 0 && exercise.reps !== null;
2864
+ if (Array.isArray(exercise.reps) && exercise.reps.length > 0) {
2865
+ chunk.reps = exercise.reps.slice(start, start + 10);
2866
+ delete chunk.sets;
2867
+ } else if (hasScalarReps) chunk.sets = chunkCount;
2868
+ if (Array.isArray(exercise.weight)) {
2869
+ chunk.weight = exercise.weight.slice(start, start + 10);
2870
+ if (!hasPerSetReps && !hasScalarReps) delete chunk.sets;
2871
+ } else if (!hasPerSetReps && exercise.weight !== void 0 && exercise.weight !== null) chunk.sets = chunkCount;
2872
+ return chunk;
2873
+ }
2874
+ /**
2875
+ * Split blocks so no encoded exercise exceeds TrainHeroic's ten parameter slots.
2876
+ * Exercises in a superset stay aligned by set range; shorter exercises appear only in
2877
+ * chunks where they still have sets.
2878
+ */
2879
+ function splitOversizedBlocks(blocks) {
2880
+ return blocks.flatMap((block) => {
2881
+ const setCounts = block.exercises.map(exerciseSetCount);
2882
+ const largestSetCount = Math.max(0, ...setCounts);
2883
+ const chunkCount = Math.max(1, Math.ceil(largestSetCount / 10));
2884
+ if (chunkCount === 1) return [block];
2885
+ return Array.from({ length: chunkCount }, (_, index) => {
2886
+ const start = index * 10;
2887
+ const exercises = block.exercises.map((exercise, exerciseIndex) => sliceExercise(exercise, setCounts[exerciseIndex] ?? 0, start)).filter((exercise) => exercise !== null);
2888
+ if (index === 0) return {
2889
+ ...block,
2890
+ exercises
2891
+ };
2892
+ return {
2893
+ title: block.title,
2894
+ ...block.type === void 0 ? {} : { type: block.type },
2895
+ exercises
2896
+ };
2897
+ });
2898
+ });
2899
+ }
2774
2900
  /** Build one saveWorkoutSetExercises payload entry with all ten param slots filled. */
2775
2901
  function makeExercise(ex, workoutSetId, order, key) {
2776
2902
  const reps = repsList(ex);
@@ -2778,8 +2904,7 @@ function makeExercise(ex, workoutSetId, order, key) {
2778
2904
  if (instruction === "" && ex.rpe !== void 0 && ex.rpe !== null) instruction = `RPE ${ex.rpe}`;
2779
2905
  const hasWeight = ex.weight !== void 0 && ex.weight !== null;
2780
2906
  const weightArr = Array.isArray(ex.weight) ? ex.weight : null;
2781
- let count = reps.length;
2782
- if (count === 0 && hasWeight) count = weightArr ? weightArr.length : Math.max(1, Math.trunc(Number(ex.sets ?? 1)) || 1);
2907
+ const count = exerciseSetCount(ex);
2783
2908
  let param2Type;
2784
2909
  let param2Values;
2785
2910
  if (hasWeight) {
@@ -2810,8 +2935,8 @@ function makeExercise(ex, workoutSetId, order, key) {
2810
2935
  eType: "e",
2811
2936
  use_count: 0
2812
2937
  };
2813
- const p1 = slots(reps);
2814
- const p2 = slots(param2Values);
2938
+ const p1 = slots(reps, 10);
2939
+ const p2 = slots(param2Values, 10);
2815
2940
  for (let i = 0; i < 10; i += 1) {
2816
2941
  entry[`param_1_data_${i + 1}`] = p1[i] ?? "";
2817
2942
  entry[`param_2_data_${i + 1}`] = p2[i] ?? "";
@@ -2929,7 +3054,10 @@ function createPath(opts) {
2929
3054
  return `/2.0/coach/calendar/workout/createWorkoutForDay/${opts.programId}/${y}/${m}/${d}/0`;
2930
3055
  }
2931
3056
  async function buildSession(client, opts) {
2932
- const blocks = z.array(blockSpecSchema).parse(opts.blocks);
3057
+ const validatedBlocks = z.array(blockSpecSchema).parse(opts.blocks);
3058
+ const splitSummary = setSplitSummary(validatedBlocks);
3059
+ if (splitSummary !== null && opts.confirmSetSplit !== true) throw new Error(`${splitSummary} Set confirmSetSplit:true to allow this change.`);
3060
+ const blocks = splitSummary === null ? validatedBlocks : splitOversizedBlocks(validatedBlocks);
2933
3061
  const sess = await req(client, "POST", createPath(opts), {});
2934
3062
  checkResponse(sessionCreateResponseSchema, sess, "session create");
2935
3063
  const workoutId = Number(sess.workout_id);
@@ -4124,7 +4252,8 @@ Coach — manage a roster (needs a coach account):
4124
4252
  coach exercise stats
4125
4253
 
4126
4254
  workouts (spec: {"blocks":[{"title","exercises":[{"id","sets"?,"reps"?,"weight"?,"rpe"?}]}],"instruction"?};
4127
- reps/weight may be a scalar or per-set array; omit --publish to leave a draft):
4255
+ reps/weight may be a scalar or per-set array; >10 sets split into consecutive blocks
4256
+ and require --yes; omit --publish to leave a draft):
4128
4257
  coach workout build (--program <id> | --athlete <id>) (--date Y-M-D | --timeline-day <n>) [--publish --yes] <spec.json>|--file f
4129
4258
  coach workout read --program <id> --date Y-M-D --pw <id>
4130
4259
  coach workout publish --pw <id> --yes
@@ -4156,6 +4285,7 @@ Athlete — the logged-in user's own training (a coach account works too):
4156
4285
  athlete session-remove --id <programWorkoutId> --date Y-M-D --yes (delete a stray PERSONAL session; the id is the session 'id' from 'athlete workouts')
4157
4286
  athlete swap-exercise --set-exercise <savedWorkoutSetExerciseId> --exercise <exerciseId> --yes (substitute one prescribed exercise in a COACH-SCHEDULED slot for a different one — your copy only; slot id from 'athlete log-targets', exerciseId from 'athlete exercises')
4158
4287
  athlete workout-note --date Y-M-D --id <programWorkoutId> [--notes "..."] [--rpe 1-10] --yes (the free-text note / session RPE on a workout, coach-visible; id is the session 'id' from 'athlete workouts'; empty --notes clears; notes-only leaves rpe untouched and vice versa)
4288
+ athlete exercise-note --set-exercise <savedWorkoutSetExerciseId> --notes "..." --yes (the per-exercise note on the exercise screen — band color, etc.; slot id from 'athlete log-targets'; empty --notes clears; distinct from workout-note)
4159
4289
  JSON is the exercises array: [{"exerciseId":N,"sets":[{"param1":reps,"param2":weight}, ...]}, ...]
4160
4290
  `;
4161
4291
  function out(value) {
@@ -4318,12 +4448,15 @@ async function cmdWorkoutBuild(client, a) {
4318
4448
  const parsed = await jsonInput(positionals[0], values.file);
4319
4449
  const spec = validate(workoutSpecSchema, Array.isArray(parsed) ? { blocks: parsed } : parsed, "workout spec", "run 'trainheroic skill' for the workout spec format and copy-paste examples.");
4320
4450
  const publish = values.publish === true;
4451
+ const splitSummary = setSplitSummary(spec.blocks);
4452
+ if (splitSummary !== null && values.yes !== true) fail(`${splitSummary} Add --yes to confirm.`);
4321
4453
  if (publish && values.yes !== true) fail("publishing is athlete-facing; add --yes to build and publish.");
4322
4454
  const opts = {
4323
4455
  programId,
4324
4456
  blocks: spec.blocks,
4325
4457
  publish
4326
4458
  };
4459
+ if (splitSummary !== null) opts.confirmSetSplit = true;
4327
4460
  if (values.date !== void 0) opts.date = parseWorkoutDate(values.date);
4328
4461
  if (values["timeline-day"] !== void 0) opts.timelineDay = toInt(values["timeline-day"], "--timeline-day");
4329
4462
  if (spec.instruction !== void 0) opts.instruction = spec.instruction;
@@ -4657,6 +4790,22 @@ async function cmdAthleteWorkoutNote(client, a) {
4657
4790
  if (values.yes !== true) fail(`setting the session note on workout ${args.programWorkoutId} is coach-visible; add --yes.`);
4658
4791
  return out(await setAthleteWorkoutNote(client, args));
4659
4792
  }
4793
+ const ATHLETE_EXERCISE_NOTE_USAGE = "athlete exercise-note --set-exercise <savedWorkoutSetExerciseId> --notes \"...\" --yes";
4794
+ async function cmdAthleteExerciseNote(client, a) {
4795
+ const { values } = parse(a, {
4796
+ "set-exercise": { type: "string" },
4797
+ notes: { type: "string" },
4798
+ yes: { type: "boolean" }
4799
+ });
4800
+ const notes = values.notes;
4801
+ if (notes === void 0) fail(`usage: trainheroic ${ATHLETE_EXERCISE_NOTE_USAGE}`);
4802
+ const args = validate(athleteExerciseNoteArgsSchema, {
4803
+ savedWorkoutSetExerciseId: need(values["set-exercise"], ATHLETE_EXERCISE_NOTE_USAGE),
4804
+ notes
4805
+ }, "exercise-note args");
4806
+ if (values.yes !== true) fail(`setting the exercise note on slot ${args.savedWorkoutSetExerciseId} is coach-visible; add --yes.`);
4807
+ return out(await setAthleteExerciseNote(client, args));
4808
+ }
4660
4809
  async function cmdAthleteWorkouts(client, a) {
4661
4810
  const { values } = parse(a, {
4662
4811
  start: { type: "string" },
@@ -4752,7 +4901,8 @@ async function cmdAthlete(client, rest) {
4752
4901
  case "session-remove": return cmdAthleteSessionRemove(client, a);
4753
4902
  case "swap-exercise": return cmdAthleteSwapExercise(client, a);
4754
4903
  case "workout-note": return cmdAthleteWorkoutNote(client, a);
4755
- default: return fail("usage: trainheroic athlete <whoami|profile|prefs|workouts|log-targets|exercises|recent-exercises|circuits|programs|history|prs|stats|working-maxes|leaderboard|export|log-set|prescribe-set|log-session|session-remove|swap-exercise|workout-note>");
4904
+ case "exercise-note": return cmdAthleteExerciseNote(client, a);
4905
+ default: return fail("usage: trainheroic athlete <whoami|profile|prefs|workouts|log-targets|exercises|recent-exercises|circuits|programs|history|prs|stats|working-maxes|leaderboard|export|log-set|prescribe-set|log-session|session-remove|swap-exercise|workout-note|exercise-note>");
4756
4906
  }
4757
4907
  }
4758
4908
  async function cmdSkill(rest) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trainheroic-unofficial/cli",
3
- "version": "3.4.0",
3
+ "version": "3.5.1",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -21,8 +21,8 @@
21
21
  ],
22
22
  "dependencies": {
23
23
  "zod": "^4.4.3",
24
- "@trainheroic-unofficial/dto": "3.4.0",
25
- "@trainheroic-unofficial/js": "3.4.0"
24
+ "@trainheroic-unofficial/dto": "3.5.1",
25
+ "@trainheroic-unofficial/js": "3.5.1"
26
26
  },
27
27
  "devDependencies": {
28
28
  "@types/node": "^26.3.0",
@@ -69,6 +69,7 @@ on a 401/403. Start with `$TH athlete whoami` to confirm auth and get your `id`.
69
69
  | Log an off-plan session (gated) | `$TH athlete log-session --date Y-M-D '[{"exerciseId":N,"sets":[...]}]' --yes` |
70
70
  | Swap a prescribed exercise (gated) | `$TH athlete swap-exercise --set-exercise <sweId> --exercise <exerciseId> --yes` |
71
71
  | Add a session note / RPE (gated) | `$TH athlete workout-note --date Y-M-D --id <programWorkoutId> --notes "..." --yes` |
72
+ | Add a per-exercise note (gated) | `$TH athlete exercise-note --set-exercise <sweId> --notes "..." --yes` |
72
73
  | Remove a stray personal session | `$TH athlete session-remove --id <programWorkoutId> --date Y-M-D --yes` |
73
74
 
74
75
  ## Reading training
@@ -193,16 +194,28 @@ $TH athlete workouts --start 2026-06-01 --end 2026-06-01 --summary
193
194
  $TH athlete workout-note --date 2026-06-01 --id 149542413 --notes "Hips felt tight." --rpe 8 --yes
194
195
  ```
195
196
 
197
+ ## Per-exercise note
198
+
199
+ `$TH athlete exercise-note` writes the "Add exercise note" field on one exercise — the place
200
+ an athlete records band color, setup cues, or anything the weight field cannot hold. It is
201
+ coach-visible and distinct from the session note. The slot id is `savedWorkoutSetExerciseId`
202
+ from `$TH athlete log-targets`. Empty `--notes` clears the note.
203
+
204
+ ```bash
205
+ $TH athlete log-targets --start 2026-06-01 --end 2026-06-01
206
+ $TH athlete exercise-note --set-exercise 2712369448 --notes "green band" --yes
207
+ ```
208
+
196
209
  ## Gotchas
197
210
 
198
211
  - `profile` must send `use_metric` and `stats` must send `date`, or the API returns 400.
199
212
  The CLI fills `use_metric` (toggle with `--metric`); pass `--date` to `stats`.
200
213
  - Units are **fixed per exercise** and surfaced positionally as `[param 1, param 2]` (e.g.
201
214
  `["reps", "lb"]`). They are not labelled by role: some exercises reverse the slots.
202
- - `log-set` and `workout-note` write to your coach-visible log. Gate them behind explicit user
203
- confirmation, never run them autonomously, and verify the result. `log-set`'s request shape
204
- was reverse-engineered from the mobile app (a two-step write: log the exercise data, then
205
- mark the set completed).
215
+ - `log-set`, `workout-note`, and `exercise-note` write to your coach-visible log. Gate them
216
+ behind explicit user confirmation, never run them autonomously, and verify the result.
217
+ `log-set`'s request shape was reverse-engineered from the mobile app (a two-step write:
218
+ log the exercise data, then mark the set completed).
206
219
  - This API is undocumented and can change. `references/athlete-api.md` lists the endpoints
207
220
  and shapes.
208
221
 
@@ -41,9 +41,9 @@ completed workouts in an inclusive window. Each item:
41
41
 
42
42
  The SDK's `presentAthleteWorkout` merges the two copies into `{ id, date, title, program, team,
43
43
  instruction, notes, rpe, logged, blocks: [{ order, title, instruction, isTest, exercises: [{ exerciseId,
44
- title, instruction, units, prescribed, performed }] }] }`. `instruction` is the coach's session
44
+ title, instruction, notes, units, prescribed, performed }] }] }`. `instruction` is the coach's session
45
45
  note; `notes` / `rpe` are the athlete's own session note and RPE on `saved_workout` (null when
46
- unset). `performed` holds the per-set values
46
+ unset). Each exercise's `notes` is the per-exercise athlete note (null when unset). `performed` holds the per-set values
47
47
  the athlete logged (made-gated; empty when nothing was recorded), `logged` is true when any
48
48
  exercise has `performed` values, and athlete-added/personal work with no prescription is
49
49
  appended as its own blocks. No `--raw` is needed to read logged results.
@@ -84,6 +84,13 @@ param_1_data_N, param_2_data_N (10 slots) }`. This is the only path that actuall
84
84
  calendar summary's duration is separate). The SDK's `setAthleteWorkoutNote` looks the saved id
85
85
  up from `date` + `programWorkoutId` (the range item's top-level `id`).
86
86
 
87
+ 4. **Per-exercise note** — `PUT /1.0/athlete/savedworkoutsetexercise/{savedWorkoutSetExerciseId}`
88
+ with `{ id, notes }`. A notes-only body leaves logged reps/weight untouched; empty `notes`
89
+ clears. GET on that path 405s. The range read's saved copy and
90
+ `GET /v5/exercises/{id}/history[].notes` both echo the stored string. Distinct from the
91
+ session note (step 3) and from coach `instruction`. The SDK's `setAthleteExerciseNote` takes
92
+ the slot id from `athlete_log_targets`.
93
+
87
94
  There is no GET for a single saved workout set; read it from the workout range's
88
95
  `saved_workout.workoutSets[]` (`id` = savedWorkoutSetId, `workoutSetExercises[].id` =
89
96
  savedWorkoutSetExerciseId, `workoutSetExercises[].workout_set_exercise_id` = the template id).
@@ -97,8 +104,9 @@ account) expose:
97
104
  `athlete_exercises`, `athlete_exercise_history`, `athlete_personal_records`,
98
105
  `athlete_exercise_stats`, `athlete_working_maxes`, `athlete_leaderboard`.
99
106
  - Gated writes include `athlete_log_set` for performed results, `athlete_prescribe_set` for
100
- planned reps/weight that must not mark a set completed, and `athlete_workout_note` for the
101
- session note / RPE (elicitation or `confirm:true`).
107
+ planned reps/weight that must not mark a set completed, `athlete_workout_note` for the
108
+ session note / RPE, and `athlete_exercise_note` for the per-exercise note (elicitation or
109
+ `confirm:true`).
102
110
 
103
111
  ## Warehouse tools (hosted worker only, D1-backed)
104
112
 
@@ -120,4 +128,6 @@ Living status table: `.agents/skills/reverse-engineer-api/coverage.md`.
120
128
  In-scope athlete reads are wrapped (`athlete_circuits`, `athlete_programming_programs`,
121
129
  `athlete_recent_exercises`). Closed without a wrap: working-max write (read exists; set/update
122
130
  never found). `PUT /1.0/athlete/savedworkout/{id}` is wrapped as the session-note / RPE write
123
- (`athlete_workout_note`); it is not a set-logging path.
131
+ (`athlete_workout_note`); it is not a set-logging path. `PUT /1.0/athlete/savedworkoutsetexercise/{id}`
132
+ with `{id, notes}` is the per-exercise note write (`athlete_exercise_note`); a notes-only body
133
+ does not wipe logged reps/weight.