@trainheroic-unofficial/athlete-mcp 3.3.3 → 3.5.0

package/dist/server.mjs

@@ -257,6 +257,29 @@ const athleteSessionRemoveArgsSchema = z.object({
 	programWorkoutId: idArgSchema,
 	date: dateString
 });
+/**
+* Args for the athlete session-note write. `programWorkoutId` is the range item's top-level `id`
+* (athlete_workouts); `date` locates that day so the SDK can resolve the saved-workout id the PUT
+* targets. `notes` is the free-text box on the workout screen (empty string clears it). `rpe` is
+* the session RPE (1–10). At least one of `notes` / `rpe` is required — a notes-only PUT leaves
+* rpe untouched and vice versa.
+*/
+const athleteWorkoutNoteObject = z.object({
+	date: dateString,
+	programWorkoutId: idArgSchema,
+	notes: z.string().optional(),
+	rpe: z.number().int().min(1).max(10).optional()
+});
+const athleteWorkoutNoteArgsSchema = athleteWorkoutNoteObject.refine((v) => v.notes !== void 0 || v.rpe !== void 0, { message: "Provide notes and/or rpe" });
+/**
+* Args for the athlete per-exercise note write (the "Add exercise note" box on the exercise
+* screen — band color, etc.). `savedWorkoutSetExerciseId` is the slot id from athlete_log_targets.
+* Empty `notes` clears the note. Distinct from {@link athleteWorkoutNoteArgsSchema} (session note).
+*/
+const athleteExerciseNoteArgsSchema = z.object({
+	savedWorkoutSetExerciseId: idArgSchema,
+	notes: z.string()
+});
 const presentedNullNumber = z.number().nullable();
 const presentedNullString = z.string().nullable();
 /** Flattened exercise within a presented workout: prescriptions, logged results, units. */
@@ -264,6 +287,7 @@ const athleteWorkoutExerciseSchema = z.object({
 	exerciseId: presentedNullNumber,
 	title: z.string(),
 	instruction: presentedNullString,
+	notes: presentedNullString,
 	units: z.array(presentedNullString),
 	prescribed: z.array(z.string()),
 	performed: z.array(z.string())
@@ -282,6 +306,8 @@ const athleteWorkoutViewSchema = z.object({
 	program: presentedNullString,
 	team: presentedNullString,
 	instruction: presentedNullString,
+	notes: presentedNullString,
+	rpe: presentedNullNumber,
 	logged: z.boolean(),
 	personal: z.boolean(),
 	blocks: z.array(athleteWorkoutBlockSchema)
@@ -371,6 +397,7 @@ z.array(rosterActivityRowSchema);
 const presentedExerciseSessionSchema = z.object({
 	date: z.string(),
 	abr: presentedNullString,
+	notes: presentedNullString,
 	estimated1RM: presentedNullNumber,
 	sets: z.array(z.object({
 		setNumber: z.number(),
@@ -507,6 +534,7 @@ const logSetTargetOutputSchema = z.object({
 		savedWorkoutSetExerciseId: z.number(),
 		title: z.string(),
 		units: z.array(nullableString),
+		notes: nullableString,
 		prescribed: z.array(z.string()),
 		performed: z.array(z.string())
 	}))
@@ -574,6 +602,17 @@ const personalWorkoutCreatedOutputSchema = z.object({
 	groupId: z.number(),
 	date: z.string()
 });
+const athleteWorkoutNoteOutputSchema = z.object({
+	programWorkoutId: z.number(),
+	savedWorkoutId: z.number(),
+	date: z.string(),
+	notes: z.string(),
+	rpe: nullableNumber
+});
+const athleteExerciseNoteOutputSchema = z.object({
+	savedWorkoutSetExerciseId: z.number(),
+	notes: z.string()
+});
 const workoutReadExerciseOutputSchema = z.object({
 	order: z.number(),
 	title: z.string(),
@@ -1202,6 +1241,15 @@ function isPersonalSession(pw) {
 	return isRecord(pw) && pw.personal_cal === true;
 }
 /**
+* The `saved_workout` blob on a program-workout range item, or null if the athlete has no saved
+* copy yet. Session notes, RPE, and set writes all resolve through this.
+*/
+function savedWorkoutOf(pw) {
+	if (!isRecord(pw)) return null;
+	const ssw = isRecord(pw.summarizedSavedWorkout) ? pw.summarizedSavedWorkout : {};
+	return isRecord(ssw.saved_workout) ? ssw.saved_workout : null;
+}
+/**
 * Rank candidate rows for a free-text query (FTS5 replacement). Higher is better:
 * exact title, then prefix, then count of matched tokens, with shorter titles and
 * standard (non-custom) exercises preferred on ties.
@@ -1278,6 +1326,15 @@ function fetchExerciseStats(client, exerciseId, userId, date) {
 function fetchAthleteWorkouts(client, startDate, endDate) {
 	return getArray(client, `/3.0/athlete/programworkout/range?startDate=${startDate}&endDate=${endDate}`, "athlete workouts");
 }
+/**
+* The program-workout row with this id on this date. Throws if that id is not on the day's range;
+* callers should take the id from `athlete_workouts`.
+*/
+async function programWorkoutOnDate(client, date, programWorkoutId) {
+	const target = (await fetchAthleteWorkouts(client, date, date)).find((pw) => coerceInt(pw.id) === programWorkoutId);
+	if (target === void 0) throw new Error(`No workout with id ${programWorkoutId} on ${date}. Get the id and date from athlete_workouts.`);
+	return target;
+}
 function fetchLeaderboard(client, workoutId, opts = {}) {
 	const qs = new URLSearchParams();
 	if (opts.page !== void 0) qs.set("page", String(opts.page));
@@ -1356,6 +1413,16 @@ function performedSlotsByExerciseId(sets) {
 	}
 	return map;
 }
+/** Per-exercise athlete notes keyed by the prescription template id (`workout_set_exercise_id`). */
+function notesByTemplateId(sets) {
+	const map = /* @__PURE__ */ new Map();
+	for (const { exercises } of sets) for (const ex of exercises) {
+		const id = coerceInt(ex.workout_set_exercise_id);
+		const notes = str(ex.notes);
+		if (id !== null && notes !== null) map.set(id, notes);
+	}
+	return map;
+}
 /** Align an exercise's prescribed slots with the slots the athlete logged, per set index. */
 function mergeExercise(prescribed, performed, meta) {
 	const indices = [.../* @__PURE__ */ new Set([...prescribed.keys(), ...performed.keys()])].sort((a, b) => a - b);
@@ -1369,7 +1436,7 @@ function mergeExercise(prescribed, performed, meta) {
 	};
 }
 /** A prescription block, each exercise aligned with the slots the athlete logged against it. */
-function mergePrescriptionBlock(set, performedById) {
+function mergePrescriptionBlock(set, performedById, notesById) {
 	const exercises = Array.isArray(set.workoutSetExercises) ? set.workoutSetExercises : [];
 	return {
 		order: coerceInt(set.order) ?? 0,
@@ -1383,6 +1450,7 @@ function mergePrescriptionBlock(set, performedById) {
 				exerciseId: coerceInt(ex.exercise_id),
 				title: typeof ex.title === "string" ? ex.title : "",
 				instruction: str(ex.instruction),
+				notes: id !== null ? notesById.get(id) ?? null : null,
 				units: exerciseUnits(ex.param_1_type, ex.param_2_type)
 			});
 		})
@@ -1399,6 +1467,7 @@ function mergeSavedBlock(set, exercises) {
 			exerciseId: coerceInt(ex.exercise_id),
 			title: typeof ex.exercise_title === "string" ? ex.exercise_title : "",
 			instruction: str(ex.instruction),
+			notes: str(ex.notes),
 			units: exerciseUnits(ex.param_1_type, ex.param_2_type)
 		}))
 	};
@@ -1413,11 +1482,12 @@ function mergeAthleteWorkout(raw) {
 	const rec = raw;
 	const ssw = isRecord(rec.summarizedSavedWorkout) ? rec.summarizedSavedWorkout : {};
 	const workout = isRecord(ssw.workout) ? ssw.workout : {};
-	const saved = isRecord(ssw.saved_workout) ? ssw.saved_workout : {};
+	const saved = savedWorkoutOf(rec) ?? {};
 	const prescriptionSets = (Array.isArray(workout.workoutSets) ? workout.workoutSets : []).filter(isRecord);
 	const logged = savedSets(saved);
 	const performedById = performedSlotsByExerciseId(logged);
-	const blocks = prescriptionSets.map((s) => mergePrescriptionBlock(s, performedById)).sort((a, b) => a.order - b.order);
+	const notesById = notesByTemplateId(logged);
+	const blocks = prescriptionSets.map((s) => mergePrescriptionBlock(s, performedById, notesById)).sort((a, b) => a.order - b.order);
 	const prescribedIds = /* @__PURE__ */ new Set();
 	for (const s of prescriptionSets) {
 		const exs = Array.isArray(s.workoutSetExercises) ? s.workoutSetExercises : [];
@@ -1442,6 +1512,8 @@ function mergeAthleteWorkout(raw) {
 		program: str(rec.program_title),
 		team: str(rec.team_title),
 		instruction: str(workout.instruction),
+		notes: str(saved.notes),
+		rpe: coerceInt(saved.rpe),
 		logged: blocks.some((b) => b.exercises.some((e) => e.sets.some((s) => s.performed !== null))),
 		personal: isPersonalSession(rec),
 		blocks
@@ -1461,6 +1533,7 @@ function toStringExercise(ex) {
 		exerciseId: ex.exerciseId,
 		title: ex.title,
 		instruction: ex.instruction,
+		notes: ex.notes,
 		units: ex.units,
 		prescribed: sideStrings(ex.sets, (s) => s.prescribed),
 		performed: sideStrings(ex.sets, (s) => s.performed)
@@ -1489,6 +1562,8 @@ function presentAthleteWorkout(raw) {
 		program: w.program,
 		team: w.team,
 		instruction: w.instruction,
+		notes: w.notes,
+		rpe: w.rpe,
 		logged: w.logged,
 		personal: w.personal,
 		blocks: w.blocks.map(toStringBlock)
@@ -1553,6 +1628,7 @@ function presentLogTargets(list) {
 					savedWorkoutSetExerciseId: id,
 					title: exerciseTitle(ex),
 					units: exerciseUnits(ex.param_1_type, ex.param_2_type),
+					notes: str(ex.notes),
 					prescribed: prescribedStrings(ex),
 					performed: performedStrings(ex)
 				};
@@ -1620,6 +1696,7 @@ function presentExerciseHistory(detail) {
 		sessions: (detail.history ?? []).map((h) => ({
 			date: h.dateCompleted,
 			abr: h.abr ?? null,
+			notes: str(h.notes),
 			estimated1RM: h.bestEstimated1RM ?? null,
 			sets: (h.sets ?? []).map((s) => ({
 				setNumber: s.setNumber,
@@ -1751,9 +1828,7 @@ function assertUniqueExerciseResults(results) {
 function findSavedWorkoutSet(workouts, savedWorkoutSetId) {
 	const available = [];
 	for (const pw of workouts) {
-		const rec = pw;
-		const ssw = isRecord(rec.summarizedSavedWorkout) ? rec.summarizedSavedWorkout : {};
-		const sw = isRecord(ssw.saved_workout) ? ssw.saved_workout : null;
+		const sw = savedWorkoutOf(pw);
 		if (!sw) continue;
 		const sets = Array.isArray(sw.workoutSets) ? sw.workoutSets : [];
 		for (const s of sets) {
@@ -2002,9 +2077,7 @@ async function addExercisesToWorkout(client, workoutId, exercises) {
 * Throws on a non-ok response.
 */
 async function removePersonalWorkout(client, args) {
-	const target = (await fetchAthleteWorkouts(client, args.date, args.date)).find((pw) => coerceInt(pw.id) === args.programWorkoutId);
-	if (target === void 0) throw new Error(`No workout with id ${args.programWorkoutId} on ${args.date}. Get the id and date from athlete_workouts.`);
-	if (!isPersonalSession(target)) throw new Error(`Workout ${args.programWorkoutId} on ${args.date} is a coach-scheduled workout, not a personal session, so it can't be removed. To change logged results on a scheduled workout, use athlete_log_set.`);
+	if (!isPersonalSession(await programWorkoutOnDate(client, args.date, args.programWorkoutId))) throw new Error(`Workout ${args.programWorkoutId} on ${args.date} is a coach-scheduled workout, not a personal session, so it can't be removed. To change logged results on a scheduled workout, use athlete_log_set.`);
 	const res = await client.request("DELETE", `/v5/programWorkouts/${args.programWorkoutId}`);
 	if (!res.ok) throw new Error(`Remove personal workout failed (HTTP ${res.status}).`);
 }
@@ -2057,8 +2130,7 @@ function eachPrescribedExercise(workouts) {
 	const rows = [];
 	for (const pw of workouts) {
 		const rec = pw;
-		const ssw = isRecord(rec.summarizedSavedWorkout) ? rec.summarizedSavedWorkout : {};
-		const sw = isRecord(ssw.saved_workout) ? ssw.saved_workout : null;
+		const sw = savedWorkoutOf(rec);
 		if (!sw) continue;
 		const sets = [...Array.isArray(sw.workoutSets) ? sw.workoutSets : [], ...Array.isArray(sw.addedWorkoutSets) ? sw.addedWorkoutSets : []];
 		for (const s of sets) {
@@ -2182,6 +2254,59 @@ function definedProps(obj) {
 	return result;
 }
 //#endregion
+//#region ../js/src/athlete-workout-note.ts
+/**
+* PUT /1.0/athlete/savedworkout/{id} — set the athlete's session note (the free-text box on the
+* workout screen) and/or session RPE. The date + programWorkoutId (`athlete_workouts` `id`) locate
+* the saved workout; GET on that path 405s, so the range read is the lookup. A notes-only body
+* leaves rpe untouched and vice versa. Empty `notes` clears the note. Coach-visible.
+*/
+async function setAthleteWorkoutNote(client, args) {
+	if (args.notes === void 0 && args.rpe === void 0) throw new Error("Provide notes and/or rpe.");
+	const programWorkoutId = coerceInt(args.programWorkoutId);
+	if (programWorkoutId === null) throw new Error(`Invalid programWorkoutId ${String(args.programWorkoutId)}.`);
+	const saved = savedWorkoutOf(await programWorkoutOnDate(client, args.date, programWorkoutId));
+	const savedWorkoutId = saved !== null ? coerceInt(saved.id) : null;
+	if (savedWorkoutId === null) throw new Error(`Workout ${programWorkoutId} on ${args.date} has no saved workout to attach a note to.`);
+	const body = definedProps({
+		id: savedWorkoutId,
+		notes: args.notes,
+		rpe: args.rpe
+	});
+	const res = await client.request("PUT", `/1.0/athlete/savedworkout/${savedWorkoutId}`, { body });
+	if (!res.ok) throw new Error(`Set workout note failed (HTTP ${res.status}).`);
+	const data = isRecord(res.data) ? res.data : {};
+	return {
+		programWorkoutId,
+		savedWorkoutId,
+		date: args.date,
+		notes: typeof data.notes === "string" ? data.notes : args.notes ?? "",
+		rpe: coerceInt(data.rpe) ?? (args.rpe !== void 0 ? args.rpe : null)
+	};
+}
+//#endregion
+//#region ../js/src/athlete-exercise-note.ts
+/**
+* PUT /1.0/athlete/savedworkoutsetexercise/{id} — set the athlete's per-exercise note (the
+* "Add exercise note" box on the exercise screen). A notes-only body leaves logged reps/weight
+* untouched. Empty `notes` clears the note. GET on that path 405s; the range read and exercise
+* history both echo the stored string. Coach-visible.
+*/
+async function setAthleteExerciseNote(client, args) {
+	const savedWorkoutSetExerciseId = coerceInt(args.savedWorkoutSetExerciseId);
+	if (savedWorkoutSetExerciseId === null) throw new Error(`Invalid savedWorkoutSetExerciseId ${String(args.savedWorkoutSetExerciseId)}.`);
+	const res = await client.request("PUT", `/1.0/athlete/savedworkoutsetexercise/${savedWorkoutSetExerciseId}`, { body: {
+		id: savedWorkoutSetExerciseId,
+		notes: args.notes
+	} });
+	if (!res.ok) throw new Error(`Set exercise note failed (HTTP ${res.status}).`);
+	const data = isRecord(res.data) ? res.data : {};
+	return {
+		savedWorkoutSetExerciseId,
+		notes: typeof data.notes === "string" ? data.notes : args.notes
+	};
+}
+//#endregion
 //#region ../core/src/history.ts
 /**
 * Trim a presented exercise history's session time-series to an inclusive YYYY-MM-DD window.
@@ -2261,9 +2386,9 @@ function registerProfileTools(server, ctx, whoami, userId) {
 		return jsonResult(await fetchLeaderboard(ctx.client, toId(workoutId), opts));
 	}));
 }
-const ATHLETE_WORKOUTS_DESC = "Workouts on the AUTHENTICATED user's own athlete calendar in an inclusive YYYY-MM-DD window, flattened to blocks/exercises. When a coach account calls this, it returns the coach's own training schedule — not a roster athlete's. To inspect a roster athlete use athlete_saved_workouts (or athlete_training for a month overview); to verify a coach-published team session from the calendar side use workout_read. Each exercise carries both its `prescribed` sets (what the program called for) and `performed` sets (what the athlete actually logged); each workout has a top-level `logged` flag. Use `performed`/`logged` to tell what was recorded or done. That is the reliable signal: a session can hold logged sets while the API's own completion flags stay 0, and an empty `performed` means nothing was logged for that exercise. For 'did I record anything / what did I do', set loggedOnly:true to return only sessions with logged sets (it keeps whole sessions that have any logged set, so individual exercises inside can still show empty `performed`; it also shrinks a large result); limit returns the most recent N workouts (newest first). For a high-level overview ('what's on my schedule this week', 'what have I been training lately') set summary:true to get one compact row per session (date, program, title, logged flag, and exerciseCount/performedCount — read performedCount against exerciseCount, e.g. 1 of 12 logged) instead of every set — a multi-program week of full detail is large, so prefer summary first, then re-query a single day without it to drill into that day's sets. For 'what's my next workout', query a forward window from today; if it comes back empty, the most recent session is likely yesterday's still-unlogged one, so widen the window backward a day or two. Both filters apply to the presented view, not raw. raw:true returns the untouched API objects. This is a date-windowed fetch, NOT an aggregate: for lifetime totals (all-time session count, total volume, first/last logged date) call athlete_profile instead of summing windows — a multi-year range here can time out. Narrow the window if the result is truncated.";
-const ATHLETE_LOG_TARGETS_DESC = "The savedWorkoutSetId + savedWorkoutSetExerciseId that athlete_log_set needs, read straight off your scheduled/logged workouts in an inclusive YYYY-MM-DD window — no raw needed. This is the self-service path for logging into a COACH-SCHEDULED workout: read the ids here, then pass them to athlete_log_set. The default view is COMPACT: one row per saved set, each carrying its program/programId, the savedWorkoutSetId, and every exercise's savedWorkoutSetExerciseId with prescribed/performed values. When several workouts fall on the same day (you're on more than one program), narrow to one with program (a case-insensitive title substring, e.g. 'bodybuilding' — no id lookup needed), or programId/teamId if you have the id. raw:true returns the untouched API objects, but that blob is large and can be truncated when several workouts share a date — prefer the program filter + the default view. For reading what you actually did (not the log ids), use athlete_workouts.";
-const ATHLETE_EXERCISE_HISTORY_DESC = "Per-exercise PRs and the dated session time-series (sets performed, estimated 1RM). The returned `sessions` run all-time, newest first; pass since/until (YYYY-MM-DD, inclusive) to keep only sessions in that window — use it for 'last 3 months' / 'this year' questions so the result stays small. estimated1RM is a formula off the session's best set and reads high when a session mixes a heavy single with high-rep backdown work, so treat it as approximate, not a logged single. `liftPRs` are always all-time and ignore since/until, but each carries the date it was set, so filter those dates yourself to answer 'PRs set this year'. Set raw:true for the untouched API object. Get the exercise id from athlete_exercises.";
+const ATHLETE_WORKOUTS_DESC = "Workouts on the AUTHENTICATED user's own athlete calendar in an inclusive YYYY-MM-DD window, flattened to blocks/exercises. When a coach account calls this, it returns the coach's own training schedule — not a roster athlete's. To inspect a roster athlete use athlete_saved_workouts (or athlete_training for a month overview); to verify a coach-published team session from the calendar side use workout_read. Each exercise carries both its `prescribed` sets (what the program called for) and `performed` sets (what the athlete actually logged); each workout has a top-level `logged` flag. Session `notes` and `rpe` are the athlete's own note/RPE on that workout (null when unset), distinct from coach `instruction`. Each exercise may also carry `notes` (the per-exercise box on the exercise screen; null when unset). Use `performed`/`logged` to tell what was recorded or done. That is the reliable signal: a session can hold logged sets while the API's own completion flags stay 0, and an empty `performed` means nothing was logged for that exercise. For 'did I record anything / what did I do', set loggedOnly:true to return only sessions with logged sets (it keeps whole sessions that have any logged set, so individual exercises inside can still show empty `performed`; it also shrinks a large result); limit returns the most recent N workouts (newest first). For a high-level overview ('what's on my schedule this week', 'what have I been training lately') set summary:true to get one compact row per session (date, program, title, logged flag, and exerciseCount/performedCount — read performedCount against exerciseCount, e.g. 1 of 12 logged) instead of every set — a multi-program week of full detail is large, so prefer summary first, then re-query a single day without it to drill into that day's sets. For 'what's my next workout', query a forward window from today; if it comes back empty, the most recent session is likely yesterday's still-unlogged one, so widen the window backward a day or two. Both filters apply to the presented view, not raw. raw:true returns the untouched API objects. This is a date-windowed fetch, NOT an aggregate: for lifetime totals (all-time session count, total volume, first/last logged date) call athlete_profile instead of summing windows — a multi-year range here can time out. Narrow the window if the result is truncated.";
+const ATHLETE_LOG_TARGETS_DESC = "The savedWorkoutSetId + savedWorkoutSetExerciseId that athlete_log_set needs, read straight off your scheduled/logged workouts in an inclusive YYYY-MM-DD window — no raw needed. This is the self-service path for logging into a COACH-SCHEDULED workout: read the ids here, then pass them to athlete_log_set. The default view is COMPACT: one row per saved set, each carrying its program/programId, the savedWorkoutSetId, and every exercise's savedWorkoutSetExerciseId with prescribed/performed values and any per-exercise `notes`. When several workouts fall on the same day (you're on more than one program), narrow to one with program (a case-insensitive title substring, e.g. 'bodybuilding' — no id lookup needed), or programId/teamId if you have the id. raw:true returns the untouched API objects, but that blob is large and can be truncated when several workouts share a date — prefer the program filter + the default view. For reading what you actually did (not the log ids), use athlete_workouts.";
+const ATHLETE_EXERCISE_HISTORY_DESC = "Per-exercise PRs and the dated session time-series (sets performed, estimated 1RM). The returned `sessions` run all-time, newest first; pass since/until (YYYY-MM-DD, inclusive) to keep only sessions in that window — use it for 'last 3 months' / 'this year' questions so the result stays small. estimated1RM is a formula off the session's best set and reads high when a session mixes a heavy single with high-rep backdown work, so treat it as approximate, not a logged single. Each session may carry `notes` (the per-exercise athlete note). `liftPRs` are always all-time and ignore since/until, but each carries the date it was set, so filter those dates yourself to answer 'PRs set this year'. Set raw:true for the untouched API object. Get the exercise id from athlete_exercises.";
 const ATHLETE_EXERCISES_DESC = "The exercises the athlete has logged (id + title + positional units). Call with no arguments to get the athlete's complete catalog, which often runs to several hundred entries; leave limit off when you want the whole list, since a no-q call returns everything by default. Pass q to free-text search by name (returns the top ranked matches, capped by limit, default 20). Use a returned id with athlete_exercise_history, athlete_personal_records, or athlete_exercise_stats (all of which require an exercise id). If a no-q result comes back wrapped with a __truncated marker, you passed a limit smaller than the catalog and are seeing a partial list; re-call without limit for all of it. A common name returns several variants (e.g. plain 'Bench Press' id 1162 vs 'BARBELL BENCH PRESS'); each variant keeps its own separate history and PR board, so prefer the plain canonical entry, and if a PR or trend looks incomplete, the work may be split across variants, so check the others.";
 function runAthleteWorkouts(ctx, args) {
 	return attempt(async () => {
@@ -2432,6 +2557,50 @@ function registerSessionTools(server, ctx) {
 		});
 	}));
 }
+/** Set the athlete's session note / RPE on a saved workout (coach-visible). */
+function registerWorkoutNoteTool(server, ctx) {
+	server.registerTool("athlete_workout_note", {
+		title: "Set your session note or RPE",
+		description: "Athlete-facing write: set the free-text note (and/or session RPE 1–10) on a workout. This is the note box on the workout screen, not the coach's Instructions and not the per-exercise note (use athlete_exercise_note for that). programWorkoutId is the `id` from athlete_workouts for that date. Pass notes (empty string clears) and/or rpe; a notes-only write leaves rpe untouched and vice versa. Visible to your coach. Requires confirmation (elicitation or confirm:true).",
+		inputSchema: {
+			...athleteWorkoutNoteObject.shape,
+			confirm: z.boolean().optional()
+		},
+		outputSchema: toolOutputSchema(athleteWorkoutNoteOutputSchema),
+		annotations: DESTRUCTIVE
+	}, ({ date, programWorkoutId, notes, rpe, confirm }, extra) => attempt(async () => {
+		const patch = athleteWorkoutNoteArgsSchema.parse(definedProps({
+			date,
+			programWorkoutId,
+			notes,
+			rpe
+		}));
+		const blocked = confirmGate(extra, `Set the session note on workout ${toId(patch.programWorkoutId)} on ${patch.date}? This is visible to your coach.`, confirm);
+		if (blocked) return blocked;
+		return jsonResult(await setAthleteWorkoutNote(ctx.client, patch));
+	}));
+}
+/** Set the athlete's per-exercise note on a saved slot (coach-visible). */
+function registerExerciseNoteTool(server, ctx) {
+	server.registerTool("athlete_exercise_note", {
+		title: "Set a per-exercise note",
+		description: "Athlete-facing write: set the free-text note on one exercise in a workout (the 'Add exercise note' box on the exercise screen). Use this for things the weight field cannot hold, such as which band you used. Distinct from athlete_workout_note, which writes the session-level note. savedWorkoutSetExerciseId is the slot id from athlete_log_targets. Empty notes clears the note. Visible to your coach. Requires confirmation (elicitation or confirm:true).",
+		inputSchema: {
+			...athleteExerciseNoteArgsSchema.shape,
+			confirm: z.boolean().optional()
+		},
+		outputSchema: toolOutputSchema(athleteExerciseNoteOutputSchema),
+		annotations: DESTRUCTIVE
+	}, ({ savedWorkoutSetExerciseId, notes, confirm }, extra) => attempt(async () => {
+		const patch = athleteExerciseNoteArgsSchema.parse({
+			savedWorkoutSetExerciseId,
+			notes
+		});
+		const blocked = confirmGate(extra, `Set the exercise note on slot ${toId(patch.savedWorkoutSetExerciseId)}? This is visible to your coach.`, confirm);
+		if (blocked) return blocked;
+		return jsonResult(await setAthleteExerciseNote(ctx.client, patch));
+	}));
+}
 /** Map validated logSession exercises to the SDK's SessionExercise[] (ids coerced, slots trimmed). */
 function mapSessionExercises(exercises) {
 	return exercises.map((e) => {
@@ -2583,12 +2752,14 @@ function registerAthleteTrainingTools(server, ctx) {
 	registerCatalogReads(server, ctx);
 	registerLogTargetsTool(server, ctx);
 	registerSessionTools(server, ctx);
+	registerWorkoutNoteTool(server, ctx);
+	registerExerciseNoteTool(server, ctx);
 	registerLogTool(server, ctx);
 	registerSwapTool(server, ctx);
 }
 //#endregion
 //#region package.json
-var version = "3.3.3";
+var version = "3.5.0";
 //#endregion
 //#region src/server.ts
 function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trainheroic-unofficial/athlete-mcp",
-  "version": "3.3.3",
+  "version": "3.5.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -21,15 +21,15 @@
   "dependencies": {
     "@modelcontextprotocol/server": "2.0.0",
     "zod": "^4.4.3",
-    "@trainheroic-unofficial/core": "3.3.3",
-    "@trainheroic-unofficial/js": "3.3.3"
+    "@trainheroic-unofficial/core": "3.5.0",
+    "@trainheroic-unofficial/js": "3.5.0"
   },
   "devDependencies": {
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.3.0",
     "tsdown": "^0.22.14",
     "tsx": "^4.23.12",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
   },
   "scripts": {
     "start": "tsx src/server.ts",