@trainheroic-unofficial/cli 0.2.0 → 0.4.0

package/dist/cli.mjs

@@ -1,14 +1,175 @@
 #!/usr/bin/env node
-import { cp, mkdir, readFile, writeFile } from "node:fs/promises";
+import { cp, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import process from "node:process";
 import { parseArgs } from "node:util";
 import { z } from "zod";
-import { homedir } from "node:os";
 //#region ../dto/src/common.ts
 /** An entity id as it arrives over the wire — a number or a numeric string. */
 const idSchema = z.union([z.string(), z.number()]);
-z.union([z.number().int(), z.string().regex(/^\d+$/u)]);
+/**
+* An id as a tool argument: a number, or a string of digits. Unlike idSchema (which
+* tolerates whatever the API sends back), this rejects non-numeric strings up front so
+* a bad argument fails validation instead of becoming NaN in a URL or a query.
+*/
+const idArgSchema = z.union([z.number().int(), z.string().regex(/^\d+$/u)]);
+//#endregion
+//#region ../dto/src/athlete.ts
+const intLike$1 = z.union([z.number(), z.string()]);
+const intLikeOrNull$1 = z.union([
+	z.number(),
+	z.string(),
+	z.null()
+]);
+const numLikeOrNull = z.union([
+	z.number(),
+	z.string(),
+	z.null()
+]);
+z.looseObject({
+	id: intLike$1,
+	roles: z.array(z.string()).optional(),
+	org_id: intLikeOrNull$1.optional()
+});
+z.looseObject({
+	reps_sum: z.number().optional(),
+	volume_sum: z.number().optional(),
+	sessions_count: z.number().optional(),
+	first_logged_date: z.string().optional(),
+	last_logged_date: z.string().optional(),
+	duration_hours: z.number().optional()
+});
+z.looseObject({
+	id: intLike$1,
+	email: z.string().optional(),
+	name_first: z.string().optional(),
+	name_last: z.string().optional(),
+	username: z.string().optional(),
+	gender: z.string().optional(),
+	date_of_birth: z.string().optional(),
+	use_metric: z.boolean().optional()
+});
+z.looseObject({ id: intLike$1 });
+/** One item of `/2.0/athlete/workingMax` — the athlete's working max for an exercise. */
+const athleteWorkingMaxSchema = z.looseObject({
+	exercise_id: intLike$1,
+	title: z.string().optional(),
+	param_type: intLikeOrNull$1.optional(),
+	value: numLikeOrNull.optional(),
+	type_suffix: z.string().optional(),
+	working_max_id: intLikeOrNull$1.optional()
+});
+z.array(athleteWorkingMaxSchema);
+/** One item of `/v5/users/exercises/history` — an exercise the athlete has logged. */
+const exerciseHistoryListItemSchema = z.looseObject({
+	id: intLike$1,
+	title: z.string(),
+	isCircuit: z.boolean().optional(),
+	prescription: z.string().optional(),
+	param1Type: intLikeOrNull$1.optional(),
+	param2Type: intLikeOrNull$1.optional()
+});
+z.array(exerciseHistoryListItemSchema);
+/** A single completed set inside a history entry (`/v5/exercises/{id}/history`). */
+const historySetSchema = z.looseObject({
+	setNumber: z.number(),
+	formattedValue: z.string().optional(),
+	rawValue1: numLikeOrNull.optional(),
+	rawValue2: numLikeOrNull.optional(),
+	savedWorkoutSetExerciseId: intLike$1.optional()
+});
+/** A best rep-max derived for a history entry. */
+const repMaxSchema = z.looseObject({
+	reps: z.number(),
+	weight: z.number()
+});
+/** One performed session of an exercise (`/v5/exercises/{id}/history` → `history[]`). */
+const historyEntrySchema = z.looseObject({
+	dateCompleted: z.string(),
+	notes: z.string().nullable().optional(),
+	isLift: z.boolean().optional(),
+	param1Type: intLikeOrNull$1.optional(),
+	param2Type: intLikeOrNull$1.optional(),
+	savedWorkoutSetExerciseId: intLike$1.optional(),
+	teamId: intLikeOrNull$1.optional(),
+	programWorkoutId: intLikeOrNull$1.optional(),
+	abr: z.string().optional(),
+	bestEstimated1RM: z.number().optional(),
+	repMaxes: z.array(repMaxSchema).optional(),
+	sets: z.array(historySetSchema).optional()
+});
+/** A lifetime PR row from `/v5/exercises/{id}/history` → `liftPRs[]`. */
+const liftPRSchema = z.looseObject({
+	weight: z.number().optional(),
+	savedWorkoutSetExerciseId: intLike$1.optional(),
+	setNumber: z.number().optional(),
+	dateCompleted: z.string().optional(),
+	reps: z.number().optional(),
+	units: z.string().optional(),
+	isMetric: z.boolean().optional(),
+	description: z.string().optional()
+});
+z.looseObject({
+	liftPRs: z.array(liftPRSchema).optional(),
+	singleParamPRs: z.array(z.unknown()).optional(),
+	history: z.array(historyEntrySchema).optional()
+});
+/** One item of `/v5/exercises/{id}/personalRecords` — a standards-filtered PR. */
+const personalRecordSchema = z.looseObject({
+	id: intLike$1.optional(),
+	savedWorkoutSetExerciseId: intLike$1.optional(),
+	setNumber: z.number().optional(),
+	reps: z.number().optional(),
+	weight: z.number().optional(),
+	scaledWeight: z.number().optional(),
+	units: z.string().optional(),
+	isMetric: z.boolean().optional()
+});
+z.array(personalRecordSchema);
+z.looseObject({
+	isLift: z.boolean().optional(),
+	lastPerformance: z.unknown().optional(),
+	personalRecord: z.unknown().optional()
+});
+/**
+* One item of `/3.0/athlete/programworkout/range` — a scheduled/completed workout. The deep
+* `summarizedSavedWorkout` tree is left loose: the presenter in `js` flattens it, so dto only
+* pins the top-level fields the warehouse and presenter key off.
+*/
+const programWorkoutSchema = z.looseObject({
+	id: intLike$1,
+	date: z.string().optional(),
+	workout_title: z.string().optional(),
+	program_id: intLikeOrNull$1.optional(),
+	program_title: z.string().optional(),
+	team_id: intLikeOrNull$1.optional(),
+	team_title: z.string().optional(),
+	summarizedSavedWorkout: z.unknown().optional()
+});
+z.array(programWorkoutSchema);
+/** A `YYYY-MM-DD` date argument. The single definition reused across athlete tool inputs. */
+const dateString = z.string().regex(/^\d{4}-\d{2}-\d{2}$/u, "expected YYYY-MM-DD");
+z.object({
+	startDate: dateString,
+	endDate: dateString
+});
+/**
+* Args for the set-logging write. `date` (the workout's day) locates the saved
+* workout via the range endpoint; `savedWorkoutSetId` picks the set to complete; `results`
+* gives, per exercise in it, the entered value of each set (param 1 / param 2 by entry slot).
+*/
+const logSetArgsSchema = z.object({
+	date: dateString,
+	savedWorkoutSetId: idArgSchema,
+	results: z.array(z.object({
+		savedWorkoutSetExerciseId: idArgSchema,
+		sets: z.array(z.object({
+			param1: z.union([z.number(), z.string()]).optional(),
+			param2: z.union([z.number(), z.string()]).optional()
+		})).min(1)
+	})).min(1)
+});
 //#endregion
 //#region ../dto/src/exercise.ts
 /** Body for creating a custom exercise; extra fields the API accepts are preserved. */
@@ -270,12 +431,31 @@ function unitLabel(paramType) {
 	if (t === null) return null;
 	return PARAM_UNIT[t] ?? null;
 }
-/** Annotate a row with human-readable units for display. */
+/**
+* Fixed measurement units for an exercise, ordered by entry slot (param 1, then param 2).
+* Positional, not semantic: some exercises reverse the slots, so the array is not labelled
+* by role. A null entry is an unset slot.
+*/
+function exerciseUnits(param1, param2) {
+	return [unitLabel(param1), unitLabel(param2)];
+}
+/** Present a row for display: drop the raw param-type codes, surface units positionally. */
 function withUnits(row) {
+	const { param_1_type, param_2_type, ...rest } = row;
+	return {
+		...rest,
+		units: exerciseUnits(param_1_type, param_2_type)
+	};
+}
+/**
+* Present a full raw exercise object for display: drop the raw param-type codes and add the
+* positional `units` array. Keeps every other field of the raw object intact.
+*/
+function presentExercise$1(raw) {
+	const { param_1_type, param_2_type, ...rest } = raw;
 	return {
-		...row,
-		param_1_unit: unitLabel(row.param_1_type),
-		param_2_unit: unitLabel(row.param_2_type)
+		...rest,
+		units: exerciseUnits(param_1_type, param_2_type)
 	};
 }
 function buildSearchText(title) {
@@ -337,13 +517,314 @@ function rankSearch(rows, query, limit) {
 		if (title.startsWith(q)) score += 100;
 		for (const tok of tokens) if (title.includes(tok)) score += 10;
 		score -= title.length * .05;
-		if (row.can_edit === 0) score += 1;
+		if ((row.can_edit ?? 0) === 0) score += 1;
 		return {
 			row,
 			score
 		};
 	}).sort((a, b) => b.score - a.score).slice(0, limit).map((s) => s.row);
 }
+/**
+* Map over items with a bounded number of concurrent workers. Used to fan out upstream
+* fetches (per-exercise history, the CLI export) without bursting the host all at once or,
+* on workerd, blowing the subrequest budget.
+*/
+async function mapPool(items, limit, fn) {
+	const out = Array.from({ length: items.length });
+	let next = 0;
+	const worker = async () => {
+		while (next < items.length) {
+			const i = next;
+			next += 1;
+			out[i] = await fn(items[i], i);
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(limit, items.length) }, () => worker()));
+	return out;
+}
+//#endregion
+//#region ../js/src/athlete.ts
+async function getJson(client, path, label) {
+	const res = await client.request("GET", path);
+	if (!res.ok) throw new Error(`${label} failed (HTTP ${res.status}).`);
+	return res.data;
+}
+async function getArray(client, path, label) {
+	const res = await client.request("GET", path);
+	if (!res.ok || !Array.isArray(res.data)) throw new Error(`${label} failed (HTTP ${res.status}).`);
+	return res.data;
+}
+/**
+* The logged-in account's numeric user id (the athlete warehouse's tenant key, and a required
+* query arg for several athlete endpoints). Works from any session — coach or athlete — and
+* even from a cached session that never went through login.
+*/
+async function resolveAthleteUserId(client) {
+	const res = await client.request("GET", "/user/simple");
+	const id = isRecord(res.data) ? coerceInt(res.data.id) : null;
+	if (!res.ok || id === null || id <= 0) throw new Error("Could not resolve athlete user id from /user/simple.");
+	return id;
+}
+/** Lifetime training totals. `use_metric` is required by the API (omitting it 400s). */
+function fetchAthleteProfileSummary(client, userId, useMetric = false) {
+	return getJson(client, `/v5/athleteProfile/summary?user_id=${userId}&use_metric=${useMetric ? 1 : 0}`, "athlete profile summary");
+}
+function fetchAthleteUser(client, userId) {
+	return getJson(client, `/v5/users/${userId}`, "athlete user");
+}
+function fetchAthletePrefs(client) {
+	return getJson(client, "/1.0/athlete/prefs", "athlete prefs");
+}
+function fetchWorkingMaxes(client) {
+	return getArray(client, "/2.0/athlete/workingMax", "athlete working maxes");
+}
+function fetchExerciseHistoryList(client) {
+	return getArray(client, "/v5/users/exercises/history", "athlete exercise history list");
+}
+/** Free-text search over the athlete's logged exercises (FTS replacement via rankSearch). */
+async function searchExerciseHistory(client, query, limit = 20) {
+	return rankSearch(await fetchExerciseHistoryList(client), query, limit);
+}
+function fetchExerciseHistoryDetail(client, exerciseId, userId) {
+	return getJson(client, `/v5/exercises/${exerciseId}/history?userId=${userId}`, "athlete exercise history");
+}
+function fetchPersonalRecords(client, exerciseId) {
+	return getArray(client, `/v5/exercises/${exerciseId}/personalRecords`, "athlete personal records");
+}
+/** Last performance + PR for an exercise. `date` (YYYY-MM-DD) is required by the API. */
+function fetchExerciseStats(client, exerciseId, userId, date) {
+	return getJson(client, `/v5/exercises/${exerciseId}/stats?userId=${userId}&date=${date}`, "athlete exercise stats");
+}
+/** Scheduled + completed workouts in an inclusive YYYY-MM-DD window. */
+function fetchAthleteWorkouts(client, startDate, endDate) {
+	return getArray(client, `/3.0/athlete/programworkout/range?startDate=${startDate}&endDate=${endDate}`, "athlete workouts");
+}
+function fetchLeaderboard(client, workoutId, opts = {}) {
+	const qs = new URLSearchParams();
+	if (opts.page !== void 0) qs.set("page", String(opts.page));
+	if (opts.pageSize !== void 0) qs.set("pageSize", String(opts.pageSize));
+	if (opts.gender !== void 0) qs.set("gender", String(opts.gender));
+	const query = qs.toString();
+	return getJson(client, `/3.0/athlete/leaderboard/${workoutId}${query ? `?${query}` : ""}`, "athlete leaderboard");
+}
+const SLOTS = 10;
+function nonEmpty(value) {
+	return value !== void 0 && value !== null && String(value).trim() !== "";
+}
+/**
+* Per-set prescriptions from the param_N_data slots, e.g. ["5 @ 225", "3 @ 245"] or ["AMRAP"].
+* Values are kept raw (a non-numeric prescription like "AMRAP" or "8-12" must survive); the
+* positional units come from the exercise's param types, mirroring the coach presenter.
+*/
+function prescribedSets(ex) {
+	const out = [];
+	for (let i = 1; i <= SLOTS; i += 1) {
+		const p1 = ex[`param_1_data_${i}`];
+		const p2 = ex[`param_2_data_${i}`];
+		const has1 = nonEmpty(p1);
+		const has2 = nonEmpty(p2);
+		if (!has1 && !has2) continue;
+		if (has1 && has2) out.push(`${p1} @ ${p2}`);
+		else if (has1) out.push(String(p1));
+		else out.push(`@ ${p2}`);
+	}
+	return out;
+}
+function presentExercise(ex) {
+	const instruction = typeof ex.instruction === "string" && ex.instruction !== "" ? ex.instruction : null;
+	return {
+		exerciseId: coerceInt(ex.exercise_id),
+		title: typeof ex.title === "string" ? ex.title : "",
+		instruction,
+		units: exerciseUnits(ex.param_1_type, ex.param_2_type),
+		prescribed: prescribedSets(ex)
+	};
+}
+function presentBlock(set) {
+	const exercises = Array.isArray(set.workoutSetExercises) ? set.workoutSetExercises : [];
+	return {
+		order: coerceInt(set.order) ?? 0,
+		title: typeof set.title === "string" && set.title !== "" ? set.title : null,
+		instruction: typeof set.instruction === "string" && set.instruction !== "" ? set.instruction : null,
+		isTest: coerceInt(set.is_test) === 1,
+		exercises: exercises.filter(isRecord).map(presentExercise)
+	};
+}
+function str$1(v) {
+	return typeof v === "string" && v !== "" ? v : null;
+}
+/** Flatten one `/3.0/athlete/programworkout/range` item into a readable workout. */
+function presentAthleteWorkout(raw) {
+	const rec = raw;
+	const ssw = isRecord(rec.summarizedSavedWorkout) ? rec.summarizedSavedWorkout : {};
+	const workout = isRecord(ssw.workout) ? ssw.workout : {};
+	const sets = Array.isArray(workout.workoutSets) ? workout.workoutSets : [];
+	return {
+		id: coerceInt(rec.id),
+		date: str$1(rec.date) ?? "",
+		title: str$1(rec.workout_title) ?? "",
+		program: str$1(rec.program_title),
+		team: str$1(rec.team_title),
+		instruction: str$1(workout.instruction),
+		blocks: sets.filter(isRecord).map(presentBlock).sort((a, b) => a.order - b.order)
+	};
+}
+function presentAthleteWorkouts(list) {
+	return list.map(presentAthleteWorkout);
+}
+const MAX_PARAM_SLOTS = 10;
+/**
+* Build the body for `PUT /1.0/athlete/savedworkoutsetexercise/{id}`. The body uses
+* snake_case keys matching the live API response shape. Each set slot (1-10) gets a
+* `param_N_made` flag (1 if data is present, 0 otherwise) and `param_1_data_N` /
+* `param_2_data_N` string values.
+*
+* Only `savedWorkoutSetExerciseId`, `savedWorkoutSetId`, and `workoutSetExerciseId` are
+* required from the live exercise record; everything else is derived from `results`.
+*
+* Exported for unit testing — callers should use `logAthleteSet` instead.
+*/
+function buildExerciseLogPayload(savedWorkoutSetExerciseId, savedWorkoutSetId, workoutSetExerciseId, results) {
+	if (results.length > MAX_PARAM_SLOTS) throw new Error(`At most ${MAX_PARAM_SLOTS} sets are supported per exercise; got ${results.length}.`);
+	const body = {
+		id: savedWorkoutSetExerciseId,
+		saved_workout_set_id: savedWorkoutSetId,
+		workout_set_exercise_id: workoutSetExerciseId,
+		completed: results.some((s) => s.param1 !== void 0 || s.param2 !== void 0) ? 1 : 0
+	};
+	for (let i = 1; i <= MAX_PARAM_SLOTS; i += 1) {
+		const slot = results[i - 1];
+		const p1 = slot?.param1 !== void 0 ? String(slot.param1) : "";
+		const p2 = slot?.param2 !== void 0 ? String(slot.param2) : "";
+		body[`param_${i}_made`] = p1 !== "" || p2 !== "" ? 1 : 0;
+		body[`param_1_data_${i}`] = p1;
+		body[`param_2_data_${i}`] = p2;
+	}
+	return body;
+}
+/**
+* Locate the target saved workout set across all program workouts on the given day.
+* Returns the `savedWorkoutId`, the matching set's `workoutSetExercises` array so callers
+* can look up `workout_set_exercise_id` by `savedWorkoutSetExerciseId`, and the raw set
+* record so callers can build the set-completion PUT body via `buildSetCompletePayload`.
+*/
+function findSavedWorkoutSet(workouts, savedWorkoutSetId) {
+	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;
+		if (!sw) continue;
+		const sets = Array.isArray(sw.workoutSets) ? sw.workoutSets : [];
+		for (const s of sets) {
+			if (!isRecord(s)) continue;
+			if (coerceInt(s.id) === savedWorkoutSetId) {
+				const savedWorkoutId = coerceInt(sw.id);
+				if (!savedWorkoutId) continue;
+				return {
+					savedWorkoutId,
+					exercises: Array.isArray(s.workoutSetExercises) ? s.workoutSetExercises.filter(isRecord) : [],
+					rawSet: s
+				};
+			}
+		}
+	}
+	throw new Error(`Saved workout set ${savedWorkoutSetId} not found on this date.`);
+}
+/**
+* Build the body for `PUT /1.0/athlete/savedworkoutset/{id}` that marks the set completed.
+*
+* The API requires the **app's camelCase in-memory model**, not the snake_case shape the
+* GET endpoints return. Key field mappings from the raw set record:
+*   saved_workout_id   → sessionId
+*   workout_set_id     → workoutSetId
+*   is_super_set (0/1) → isSuperSet (boolean)
+*   plain_text (0/1)   → isPlainText (boolean)
+*   unit ("lb"/"kg")   → isMetric (boolean)
+*   workoutSetExercises[].id → exercises (array of IDs)
+*
+* `exerciseIds` must be the savedWorkoutSetExercise IDs (not workout_set_exercise_ids).
+*
+* Exported for unit testing — callers should use `logAthleteSet` instead.
+*/
+function buildSetCompletePayload(rawSet, exerciseIds, complete) {
+	const id = coerceInt(rawSet.id);
+	const sessionId = coerceInt(rawSet.saved_workout_id);
+	const workoutSetId = coerceInt(rawSet.workout_set_id);
+	if (!id || !sessionId || !workoutSetId) throw new Error("Raw set is missing required id / saved_workout_id / workout_set_id.");
+	const unit = typeof rawSet.unit === "string" ? rawSet.unit : "";
+	return {
+		id,
+		sessionId,
+		workoutSetId,
+		completed: complete ? "1" : "0",
+		rx: coerceInt(rawSet.rx) ?? 0,
+		version: coerceInt(rawSet.version) ?? 0,
+		isMetric: unit.toLowerCase() === "kg",
+		isSuperSet: rawSet.is_super_set === 1 || rawSet.is_super_set === true,
+		isPlainText: rawSet.plain_text === 1 || rawSet.plain_text === true,
+		title: typeof rawSet.title === "string" ? rawSet.title : "",
+		instruction: typeof rawSet.instruction === "string" ? rawSet.instruction : "",
+		notes: rawSet.notes ?? null,
+		exercises: [...exerciseIds]
+	};
+}
+/**
+* Record entered set results for one saved workout set.
+*
+* **Two-step write (both required for data to persist):**
+* 1. For each exercise in `results`:
+*    `PUT /1.0/athlete/savedworkoutsetexercise/{savedWorkoutSetExerciseId}` with the
+*    per-slot `param_N_data_M` values. This is the only path that actually stores reps
+*    and weight — the `savedworkoutset` PUT accepts the same fields but silently discards
+*    them.
+* 2. `PUT /1.0/athlete/savedworkoutset/{savedWorkoutSetId}` with `completed:"1"` to
+*    mark the block done and make the entry visible as a logged set in history.
+*
+* The date is used to locate the saved workout (via the range endpoint) so we can resolve
+* `saved_workout_id` and `workout_set_exercise_id` for each exercise. Both are required
+* by the respective PUT bodies.
+*/
+async function logAthleteSet(client, args) {
+	const { exercises, rawSet } = findSavedWorkoutSet(await fetchAthleteWorkouts(client, args.date, args.date), args.savedWorkoutSetId);
+	let exercisesLogged = 0;
+	for (const result of args.results) {
+		const ex = exercises.find((e) => coerceInt(e.id) === result.savedWorkoutSetExerciseId);
+		if (!ex) throw new Error(`savedWorkoutSetExerciseId ${result.savedWorkoutSetExerciseId} not found in saved workout set ${args.savedWorkoutSetId}.`);
+		const workoutSetExerciseId = coerceInt(ex.workout_set_exercise_id);
+		if (!workoutSetExerciseId) throw new Error(`Could not resolve workout_set_exercise_id for exercise ${result.savedWorkoutSetExerciseId}.`);
+		const body = buildExerciseLogPayload(result.savedWorkoutSetExerciseId, args.savedWorkoutSetId, workoutSetExerciseId, result.sets);
+		const res = await client.request("PUT", `/1.0/athlete/savedworkoutsetexercise/${result.savedWorkoutSetExerciseId}`, { body });
+		if (!res.ok) throw new Error(`Failed to log exercise ${result.savedWorkoutSetExerciseId} (HTTP ${res.status}).`);
+		exercisesLogged += 1;
+	}
+	const setBody = buildSetCompletePayload(rawSet, exercises.map((e) => coerceInt(e.id)).filter((n) => n !== null), true);
+	const setRes = await client.request("PUT", `/1.0/athlete/savedworkoutset/${args.savedWorkoutSetId}`, { body: setBody });
+	if (!setRes.ok) throw new Error(`Failed to mark workout set ${args.savedWorkoutSetId} completed (HTTP ${setRes.status}).`);
+	return {
+		savedWorkoutSetId: args.savedWorkoutSetId,
+		exercisesLogged
+	};
+}
+/** Flatten `/v5/exercises/{id}/history` into PRs + a session time-series. */
+function presentExerciseHistory(detail) {
+	return {
+		liftPRs: (detail.liftPRs ?? []).map((p) => ({
+			description: p.description ?? null,
+			reps: p.reps ?? null,
+			weight: p.weight ?? null,
+			date: p.dateCompleted ?? null
+		})),
+		sessions: (detail.history ?? []).map((h) => ({
+			date: h.dateCompleted,
+			abr: h.abr ?? null,
+			estimated1RM: h.bestEstimated1RM ?? null,
+			sets: (h.sets ?? []).map((s) => ({
+				setNumber: s.setNumber,
+				value: s.formattedValue ?? null
+			}))
+		}))
+	};
+}
 //#endregion
 //#region ../js/src/workout-encode.ts
 const LEADERBOARD_TYPE = {
@@ -831,10 +1312,7 @@ var ExerciseLibrary = class {
 		await this.ensureFresh();
 		const s = this.#byId.get(id);
 		if (!s) return null;
-		const full = { ...s.raw };
-		full.param_1_unit = unitLabel(full.param_1_type);
-		full.param_2_unit = unitLabel(full.param_2_type);
-		return full;
+		return presentExercise$1(s.raw);
 	}
 	async defaults(id) {
 		const s = this.#byId.get(id);
@@ -972,7 +1450,7 @@ const HELP = `trainheroic — command-line tool for the TrainHeroic coaching API
 Credentials come from TRAINHEROIC_EMAIL and TRAINHEROIC_PASSWORD. Output is JSON.
 
 Setup:
-  install-skill   copy the Claude Code skill to ~/.claude/skills/trainheroic-unofficial/
+  install-skill   copy the Claude Code skills to ~/.claude/skills/
 
 Reads:
   whoami | head-coach | athletes | programs | teams | notifications | analytics
@@ -1000,6 +1478,17 @@ Messaging:
   message draft <streamId> <text> [--reply-to <id>]
   message send <streamId> <text> [--reply-to <id>] --yes
   message delete <streamId> <commentId> --yes
+
+Athlete (the logged-in user's own training; a coach account works too):
+  athlete whoami | profile [--metric] | prefs | working-maxes
+  athlete workouts --start Y-M-D --end Y-M-D [--raw]
+  athlete exercises [--q <text>] [--limit N]
+  athlete history <exerciseId> [--raw]
+  athlete prs <exerciseId>
+  athlete stats <exerciseId> --date Y-M-D
+  athlete leaderboard <workoutId> [--page N] [--page-size N] [--gender N]
+  athlete export [--out dir] [--start Y-M-D] [--end Y-M-D] [--full]
+  athlete log-set --date Y-M-D --set <id> <resultsJson>|--file f --yes   (writes to your live log)
 `;
 function out(value) {
 	process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
@@ -1236,17 +1725,182 @@ async function cmdMessage(client, rest) {
 		default: return fail("usage: trainheroic message <list|read|draft|send|delete>");
 	}
 }
+function isoDate(value, label) {
+	if (!/^\d{4}-\d{2}-\d{2}$/u.test(value)) fail(`${label} must be YYYY-MM-DD, got "${value}".`);
+	return value;
+}
+function logErr(msg) {
+	process.stderr.write(`${msg}\n`);
+}
+async function cmdAthleteExport(client, a) {
+	const { values } = parse(a, {
+		out: { type: "string" },
+		start: { type: "string" },
+		end: { type: "string" },
+		full: { type: "boolean" }
+	});
+	const dir = values.out ?? join(homedir(), ".trainheroic", "athlete-export");
+	const today = /* @__PURE__ */ new Date();
+	const past = /* @__PURE__ */ new Date();
+	past.setFullYear(past.getFullYear() - 2);
+	const start = values.start !== void 0 ? isoDate(values.start, "--start") : past.toISOString().slice(0, 10);
+	const end = values.end !== void 0 ? isoDate(values.end, "--end") : today.toISOString().slice(0, 10);
+	await mkdir(dir, { recursive: true });
+	const userId = await resolveAthleteUserId(client);
+	logErr(`exporting to ${dir} (user ${userId})`);
+	const [summary, user, prefs, workouts, exercises, workingMaxes] = await Promise.all([
+		fetchAthleteProfileSummary(client, userId),
+		fetchAthleteUser(client, userId),
+		fetchAthletePrefs(client),
+		fetchAthleteWorkouts(client, start, end),
+		fetchExerciseHistoryList(client),
+		fetchWorkingMaxes(client)
+	]);
+	await writeFile(join(dir, "profile.json"), JSON.stringify({
+		summary,
+		user,
+		prefs
+	}, null, 2));
+	await writeFile(join(dir, "workouts.json"), JSON.stringify(presentAthleteWorkouts(workouts), null, 2));
+	await writeFile(join(dir, "exercises.json"), JSON.stringify(exercises, null, 2));
+	await writeFile(join(dir, "working-maxes.json"), JSON.stringify(workingMaxes, null, 2));
+	let histories = 0;
+	if (values.full === true) {
+		await mkdir(join(dir, "history"), { recursive: true });
+		logErr(`fetching per-exercise history for ${exercises.length} exercises (--full)...`);
+		await mapPool(exercises, 5, async (ex) => {
+			const id = Number(ex.id);
+			const detail = await fetchExerciseHistoryDetail(client, id, userId).catch(() => null);
+			if (detail) {
+				await writeFile(join(dir, "history", `${id}.json`), JSON.stringify(presentExerciseHistory(detail), null, 2));
+				histories += 1;
+			}
+		});
+	}
+	out({
+		exported: dir,
+		range: {
+			start,
+			end
+		},
+		workouts: workouts.length,
+		exercises: exercises.length,
+		workingMaxes: workingMaxes.length,
+		histories: values.full === true ? histories : "skipped (use --full)"
+	});
+}
+const LOG_SET_USAGE = "athlete log-set --date Y-M-D --set <id> <resultsJson> --yes";
+async function cmdAthleteLogSet(client, a) {
+	const { values, positionals } = parse(a, {
+		date: { type: "string" },
+		set: { type: "string" },
+		file: { type: "string" },
+		yes: { type: "boolean" }
+	});
+	const date = isoDate(need(values.date, LOG_SET_USAGE), "--date");
+	const savedWorkoutSetId = toInt(need(values.set, LOG_SET_USAGE), "--set");
+	const args = validate(logSetArgsSchema, {
+		date,
+		savedWorkoutSetId,
+		results: await jsonInput(positionals[0], values.file)
+	}, "log-set args");
+	if (values.yes !== true) fail(`logging to set ${savedWorkoutSetId} writes to your coach-visible log; add --yes.`);
+	const mapped = args.results.map((r) => ({
+		savedWorkoutSetExerciseId: toInt(String(r.savedWorkoutSetExerciseId), "savedWorkoutSetExerciseId"),
+		sets: r.sets.map((s) => {
+			const slot = {};
+			if (s.param1 !== void 0) slot.param1 = s.param1;
+			if (s.param2 !== void 0) slot.param2 = s.param2;
+			return slot;
+		})
+	}));
+	return out(await logAthleteSet(client, {
+		date: args.date,
+		savedWorkoutSetId,
+		results: mapped
+	}));
+}
+async function cmdAthlete(client, rest) {
+	const [sub, ...a] = rest;
+	switch (sub) {
+		case "whoami": return out(await get(client, "/user/simple"));
+		case "profile": {
+			const { values } = parse(a, { metric: { type: "boolean" } });
+			const userId = await resolveAthleteUserId(client);
+			const [summary, user] = await Promise.all([fetchAthleteProfileSummary(client, userId, values.metric === true), fetchAthleteUser(client, userId)]);
+			return out({
+				summary,
+				user
+			});
+		}
+		case "prefs": return out(await fetchAthletePrefs(client));
+		case "workouts": {
+			const { values } = parse(a, {
+				start: { type: "string" },
+				end: { type: "string" },
+				raw: { type: "boolean" }
+			});
+			const workouts = await fetchAthleteWorkouts(client, isoDate(need(values.start, "athlete workouts --start Y-M-D --end Y-M-D"), "--start"), isoDate(need(values.end, "athlete workouts --start Y-M-D --end Y-M-D"), "--end"));
+			return out(values.raw === true ? workouts : presentAthleteWorkouts(workouts));
+		}
+		case "exercises": {
+			const { values } = parse(a, {
+				q: { type: "string" },
+				limit: { type: "string" }
+			});
+			const limit = values.limit !== void 0 ? toInt(values.limit, "--limit") : 20;
+			const q = values.q;
+			return out(q !== void 0 ? await searchExerciseHistory(client, q, limit) : await fetchExerciseHistoryList(client));
+		}
+		case "history": {
+			const { values, positionals } = parse(a, { raw: { type: "boolean" } });
+			const detail = await fetchExerciseHistoryDetail(client, toInt(need(positionals[0], "athlete history <exerciseId>"), "exerciseId"), await resolveAthleteUserId(client));
+			return out(values.raw === true ? detail : presentExerciseHistory(detail));
+		}
+		case "prs": return out(await fetchPersonalRecords(client, toInt(need(a[0], "athlete prs <exerciseId>"), "exerciseId")));
+		case "stats": {
+			const { values, positionals } = parse(a, { date: { type: "string" } });
+			const id = toInt(need(positionals[0], "athlete stats <exerciseId> --date Y-M-D"), "exerciseId");
+			const date = isoDate(need(values.date, "athlete stats <exerciseId> --date Y-M-D"), "--date");
+			return out(await fetchExerciseStats(client, id, await resolveAthleteUserId(client), date));
+		}
+		case "working-maxes": return out(await fetchWorkingMaxes(client));
+		case "leaderboard": {
+			const { values, positionals } = parse(a, {
+				page: { type: "string" },
+				"page-size": { type: "string" },
+				gender: { type: "string" }
+			});
+			const workoutId = toInt(need(positionals[0], "athlete leaderboard <workoutId>"), "workoutId");
+			const opts = {};
+			if (values.page !== void 0) opts.page = toInt(values.page, "--page");
+			if (values["page-size"] !== void 0) opts.pageSize = toInt(values["page-size"], "--page-size");
+			if (values.gender !== void 0) opts.gender = toInt(values.gender, "--gender");
+			return out(await fetchLeaderboard(client, workoutId, opts));
+		}
+		case "export": return cmdAthleteExport(client, a);
+		case "log-set": return cmdAthleteLogSet(client, a);
+		default: return fail("usage: trainheroic athlete <whoami|profile|prefs|workouts|exercises|history|prs|stats|working-maxes|leaderboard|export|log-set>");
+	}
+}
 async function cmdInstallSkill() {
 	const home = process.env.HOME ?? process.env.USERPROFILE;
 	if (!home) fail("cannot determine home directory.");
-	const skillSrc = join(import.meta.dirname, "../skill/trainheroic-unofficial");
-	const skillDest = join(home, ".claude/skills/trainheroic-unofficial");
-	await mkdir(join(home, ".claude/skills"), { recursive: true });
-	await cp(skillSrc, skillDest, {
-		recursive: true,
-		force: true
-	});
-	out({ installed: skillDest });
+	const skillRoot = join(import.meta.dirname, "../skill");
+	const skillsDir = join(home, ".claude/skills");
+	await mkdir(skillsDir, { recursive: true });
+	const entries = await readdir(skillRoot, { withFileTypes: true });
+	const installed = [];
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const dest = join(skillsDir, entry.name);
+		await cp(join(skillRoot, entry.name), dest, {
+			recursive: true,
+			force: true
+		});
+		installed.push(dest);
+	}
+	out({ installed });
 }
 async function dispatch(client, group, rest) {
 	switch (group) {
@@ -1264,6 +1918,7 @@ async function dispatch(client, group, rest) {
 		case "exercise": return cmdExercise(client, rest);
 		case "workout": return cmdWorkout(client, rest);
 		case "message": return cmdMessage(client, rest);
+		case "athlete": return cmdAthlete(client, rest);
 		default: return fail(`unknown command "${group}". Run 'trainheroic help'.`);
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trainheroic-unofficial/cli",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -21,8 +21,8 @@
   ],
   "dependencies": {
     "zod": "^4.4.3",
-    "@trainheroic-unofficial/dto": "0.2.0",
-    "@trainheroic-unofficial/js": "0.2.0"
+    "@trainheroic-unofficial/dto": "0.4.0",
+    "@trainheroic-unofficial/js": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",

package/skill/trainheroic-athlete/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: trainheroic-athlete
+description: Read and analyze your own TrainHeroic training — scheduled and completed workouts, per-exercise history, PRs, working maxes, and lifetime totals — and optionally log completed sets. Use when the user wants to review their training history, track progress on a lift over time, look up PRs or working maxes, see what's programmed, export their training data, or log a workout result. Works for an athlete account or a coach account (a coach also has athlete-scoped training).
+metadata:
+  author: alandotcom
+  version: "1.0.0"
+---
+
+# TrainHeroic Athlete API
+
+Authenticated access to the logged-in user's **own** training through the `trainheroic`
+command-line tool (`@trainheroic-unofficial/cli`), which wraps the
+`@trainheroic-unofficial/js` SDK. This is the athlete surface: history, scheduled workouts,
+PRs, working maxes. For coaching (rosters, teams, programming, messaging) use the
+`trainheroic-unofficial` skill instead.
+
+- Base URL: `https://api.trainheroic.com`
+- Login endpoint: `https://apis.trainheroic.com/auth`
+
+A coach account works here too: a coach login also carries athlete scope, so these commands
+return the coach's own training data.
+
+## Setup
+
+### CLI
+
+Verify the CLI is available, then install if missing (no credentials required):
+
+```bash
+which trainheroic || npm install -g @trainheroic-unofficial/cli
+trainheroic install-skill   # refreshes skill files in ~/.claude/skills/
+```
+
+Set `TH` for the commands below:
+
+```bash
+TH="trainheroic"
+```
+
+### Credentials
+
+Credentials come from the environment (if unset, ask the user — do not guess):
+
+```bash
+export TRAINHEROIC_EMAIL="athlete@example.com"
+export TRAINHEROIC_PASSWORD="..."
+```
+
+The CLI logs in, caches the session at `~/.trainheroic/session.json`, and re-authenticates
+on a 401/403. Start with `$TH athlete whoami` to confirm auth and get your `id`. Run
+`$TH help` for the full command list.
+
+## What you can do
+
+| Goal                                  | Command                                                  |
+| ------------------------------------- | -------------------------------------------------------- |
+| Lifetime totals + profile             | `$TH athlete profile [--metric]`                         |
+| Scheduled / completed workouts        | `$TH athlete workouts --start Y-M-D --end Y-M-D [--raw]` |
+| Find an exercise you've logged        | `$TH athlete exercises [--q <text>] [--limit N]`         |
+| One lift's PRs + history over time    | `$TH athlete history <exerciseId> [--raw]`               |
+| Personal records for a lift           | `$TH athlete prs <exerciseId>`                           |
+| Last performance + PR as of a date    | `$TH athlete stats <exerciseId> --date Y-M-D`            |
+| Working maxes (drive % prescriptions) | `$TH athlete working-maxes`                              |
+| Benchmark leaderboard                 | `$TH athlete leaderboard <workoutId>`                    |
+| Download all historicals to JSON      | `$TH athlete export [--out dir] [--full]`                |
+| Log completed set results (gated)     | `$TH athlete log-set --date Y-M-D --set <id> ... --yes`  |
+
+## Reading training
+
+Most analysis starts by finding the exercise id, then pulling its history:
+
+```bash
+$TH athlete exercises --q "back squat"     # -> id + title + positional units
+$TH athlete history 1659830                # PRs + dated session time-series
+$TH athlete stats 1659830 --date 2026-06-01
+```
+
+`history` returns a presented view (PRs plus each session's date, summary `abr`, estimated
+1RM, and sets). Add `--raw` for the untouched API object.
+
+`workouts` flattens each day into blocks and exercises with per-set prescriptions and
+positional units:
+
+```bash
+$TH athlete workouts --start 2026-06-01 --end 2026-06-14
+```
+
+`profile` returns lifetime totals (reps, volume, sessions, first/last logged, hours) plus
+the profile. Pass `--metric` for kg/metric totals.
+
+## Exporting your history
+
+`$TH athlete export` writes your historicals to JSON files (default
+`~/.trainheroic/athlete-export`): `profile.json`, `workouts.json` (a 2-year window by
+default; override with `--start`/`--end`), `exercises.json` (the catalog), and
+`working-maxes.json`. Add `--full` to also fetch each exercise's history into
+`history/<id>.json` — that is one request per exercise (hundreds), so it is slower.
+
+```bash
+$TH athlete export --out ./my-training            # fast: workouts, catalog, maxes, profile
+$TH athlete export --out ./my-training --full     # also per-exercise history (slow)
+```
+
+## Logging a set
+
+`$TH athlete log-set` writes completed results back to a workout (reps/weight per set),
+marks the set completed, and the result shows up in your exercise history. **It is
+athlete-facing**: it mutates your training log, which your coach can see, so confirm before
+running and re-read the workout to check the result landed.
+
+Get the `savedWorkoutSetId` and each `savedWorkoutSetExerciseId` from the raw workout
+(`$TH athlete workouts --start <day> --end <day> --raw`, under
+`summarizedSavedWorkout.saved_workout.workoutSets`). Then:
+
+```bash
+$TH athlete log-set --date 2026-06-01 --set 1593305783 --yes \
+  '[{"savedWorkoutSetExerciseId": 2712369448, "sets": [{"param1": 3, "param2": 225}]}]'
+```
+
+`--yes` is required. Confirm with the user before running it, and re-read the workout to
+check the result landed as intended. `param1`/`param2` are the entered values by entry slot
+(check the exercise's positional units first).
+
+## Gotchas
+
+- `profile` must send `use_metric` and `stats` must send `date`, or the API returns 400.
+  The CLI fills `use_metric` (toggle with `--metric`); pass `--date` to `stats`.
+- Units are **fixed per exercise** and surfaced positionally as `[param 1, param 2]` (e.g.
+  `["reps", "lb"]`). They are not labelled by role: some exercises reverse the slots.
+- `log-set` writes to your coach-visible log. Gate it behind explicit user confirmation,
+  never run it autonomously, and verify the result. Its request shape was reverse-engineered
+  from the mobile app (a two-step write: log the exercise data, then mark the set completed).
+- This API is undocumented and can change. `references/athlete-api.md` lists the endpoints
+  and shapes.
+
+## Beyond the CLI
+
+The same SDK powers the local `@trainheroic-unofficial/athlete-mcp` stdio server (the same
+tools as MCP tools) and the hosted Cloudflare worker. The hosted worker adds a **training
+warehouse** (D1): `athlete_workouts_sync` / `athlete_training_sync` download your
+historicals, and `athlete_workouts_stored` / `athlete_training_stored` query them — so you
+can research your training over time without re-hitting the API. See
+`references/athlete-api.md` for the warehouse tools.

package/skill/trainheroic-athlete/references/athlete-api.md

@@ -0,0 +1,100 @@
+# Athlete API reference
+
+The athlete endpoints operate on the **logged-in user** (no athlete id in the path — the
+session identifies you). Several need the numeric user id as a query arg; get it from
+`GET /user/simple` (`.id`). All are on the default host `https://api.trainheroic.com` and
+authenticate with the `session-token` header. Response schemas are loose (the API drifts);
+only the fields below are relied on.
+
+## Identity & profile
+
+| Endpoint                                                        | Notes                                                                                                                                                                                          |
+| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GET /user/simple`                                              | `id`, `roles`, `org_id`, name. The id is the tenant key for everything else.                                                                                                                   |
+| `GET /v5/athleteProfile/summary?user_id={id}&use_metric={0\|1}` | Lifetime totals: `reps_sum`, `volume_sum`, `sessions_count`, `first_logged_date`, `last_logged_date`, `duration_hours`. **`use_metric` is required** — omitting it returns `400 Invalid data`. |
+| `GET /v5/users/{id}`                                            | Detailed profile: dob, gender, height/weight, `use_metric`, trial status.                                                                                                                      |
+| `GET /1.0/athlete/prefs`                                        | Notification + display preference flags.                                                                                                                                                       |
+
+## Workouts
+
+`GET /3.0/athlete/programworkout/range?startDate={Y-M-D}&endDate={Y-M-D}` — scheduled and
+completed workouts in an inclusive window. Each item:
+
+- Top level: `id` (the programWorkout id), `date`, `workout_title`, `program_id`,
+  `program_title`, `team_id`, `team_title`.
+- `summarizedSavedWorkout.workout`: `title`, `instruction` (coach note), `workoutSets[]`.
+  - Each set: `title`, `order`, `instruction`, `is_test`, `workoutSetExercises[]`.
+    - Each exercise: `exercise_id`, `title`, `instruction`, `param_1_type`, `param_2_type`,
+      and the prescription in `param_1_data_1..10` / `param_2_data_1..10` (one slot per set;
+      empty string for unused). Non-numeric prescriptions (`AMRAP`, `8-12`) appear as-is.
+- `summarizedSavedWorkout.saved_workout`: the athlete's logged copy, with `workoutSets[]`
+  whose `id` is the **savedWorkoutSetId** and whose `workoutSetExercises[].id` is the
+  **savedWorkoutSetExerciseId** — the ids the logging write targets.
+
+The SDK's `presentAthleteWorkout` flattens this to `{ id, date, title, program, team,
+instruction, blocks: [{ order, title, instruction, isTest, exercises: [{ exerciseId, title,
+instruction, units, prescribed }] }] }`.
+
+## Exercises, history, PRs
+
+| Endpoint                                                | Notes                                                                                                                                                                      |
+| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GET /v5/users/exercises/history`                       | The exercises you've logged: `id`, `title`, `param1Type`, `param2Type`, `prescription`, `isCircuit`. Use it to find an exercise id.                                        |
+| `GET /v5/exercises/{id}/history?userId={id}`            | `liftPRs[]` (rep-max PRs), `history[]` (per-session: `dateCompleted`, `abr`, `bestEstimated1RM`, `savedWorkoutSetExerciseId`, `programWorkoutId`, `sets[]`, `repMaxes[]`). |
+| `GET /v5/exercises/{id}/personalRecords`                | PR rows with strength-standard `filters`.                                                                                                                                  |
+| `GET /v5/exercises/{id}/stats?userId={id}&date={Y-M-D}` | `isLift`, `lastPerformance`, `personalRecord`. **`date` is required** — omitting it returns `400 Invalid date parameter`.                                                  |
+| `GET /v5/exercises/{id}`                                | Exercise detail: description, `param1Type`/`param2Type`, `units`, video.                                                                                                   |
+| `GET /2.0/athlete/workingMax`                           | Working max per exercise: `exercise_id`, `title`, `param_type`, `value`, `type_suffix`.                                                                                    |
+| `GET /3.0/athlete/leaderboard/{workoutId}`              | Leaderboard for a benchmark/test workout (`tests`, `results`, `testStats`).                                                                                                |
+
+## Logging a set (write)
+
+Logging is a **two-step** write, reverse-engineered from the mobile app (verified against
+captured traffic). The SDK's `logAthleteSet` performs both; it fetches the day's range to
+resolve the ids from `summarizedSavedWorkout.saved_workout`.
+
+1. **Persist the entered data** — `PUT /1.0/athlete/savedworkoutsetexercise/{savedWorkoutSetExerciseId}`
+   with `{ id, saved_workout_set_id, workout_set_exercise_id, completed:1, param_N_made,
+param_1_data_N, param_2_data_N (10 slots) }`. This is the only path that actually stores
+   reps/weight (and it alone surfaces the result in exercise history). The
+   `savedworkoutset`/`savedworkout` PUTs accept the same fields but **silently discard** the
+   `param_N_data` values.
+2. **Mark the set completed** — `PUT /1.0/athlete/savedworkoutset/{savedWorkoutSetId}` with
+   the camelCase in-memory model (`sessionId` ← `saved_workout.id`, `workoutSetId` ←
+   `workout_set_id`, `isSuperSet`, `exercises: [savedWorkoutSetExerciseId, …]`, `completed`).
+   A minimal `{id, sessionId, completed}` body returns 500 — the full mapped body is required.
+
+There is no GET for a single saved workout set; read it from the workout range's
+`saved_workout.workoutSets[]` (`id` = savedWorkoutSetId, `workoutSetExercises[].id` =
+savedWorkoutSetExerciseId, `workoutSetExercises[].workout_set_exercise_id` = the template id).
+
+## MCP tools
+
+The local `@trainheroic-unofficial/athlete-mcp` server and the hosted worker (for any
+account) expose:
+
+- Live reads: `athlete_whoami`, `athlete_profile`, `athlete_prefs`, `athlete_workouts`,
+  `athlete_exercises`, `athlete_exercise_history`, `athlete_personal_records`,
+  `athlete_exercise_stats`, `athlete_working_maxes`, `athlete_leaderboard`.
+- Gated write: `athlete_log_set` (elicitation or `confirm:true`).
+
+## Warehouse tools (hosted worker only, D1-backed)
+
+Download historicals into D1 so they can be queried over time without re-hitting the API.
+One sync verb populates each zone; one query tool reads it.
+
+- `athlete_workouts_sync { startDate, endDate }` → `athlete_workouts_stored { workoutId? |
+startDate?/endDate? }`.
+- `athlete_training_sync { exerciseId? | batchSize?, full? }` → `athlete_training_stored
+{ q? | exerciseId? (+prs?) | workingMaxes? }`. Omitting `exerciseId` syncs the catalog +
+  working maxes and drains a **batch** of un-synced exercises (repeat until `remaining` is 0
+  — bounded per call to respect Worker subrequest limits). `full:true` re-pulls every
+  exercise.
+
+## Still unexplored
+
+- `PUT /1.0/athlete/savedworkout/{id}` (whole-workout sync; not needed for per-set logging,
+  which uses the two-step path above).
+- `GET /v5/users/circuits/{recent,history}` (circuit history; shapes mirror the exercise
+  history list).
+- `GET /1.0/athlete/programming/programs` (subscribed programs; empty for the test account).