@trainheroic-unofficial/cli 0.4.2 → 0.5.0

package/README.md

@@ -4,6 +4,13 @@ A command-line tool for the TrainHeroic coaching API. Takes credentials from the
 
 Part of the [trainheroic-unofficial](../../README.md) workspace.
 
+## Contents
+
+- [Install](#install)
+- [Usage](#usage)
+- [Conventions](#conventions)
+- [Develop](#develop)
+
 ## Install
 
 ```bash
@@ -11,39 +18,99 @@ npm install -g @trainheroic-unofficial/cli
 # or: npx @trainheroic-unofficial/cli <command>
 ```
 
+Needs Node >= 18 and an existing TrainHeroic account.
+
 ## Usage
 
+Set your TrainHeroic login in the environment (stored in plaintext and shell history — treat
+it as a secret), then run a command. Every command prints JSON to stdout.
+
 ```bash
 export TRAINHEROIC_EMAIL="coach@example.com"
 export TRAINHEROIC_PASSWORD="..."
 
-trainheroic whoami
-trainheroic exercise resolve "Back Squat"
-trainheroic workout build --program 12345 --date 2026-6-22 --file day.json
+trainheroic whoami                                # confirm auth; prints your account
+trainheroic coach exercise resolve "Back Squat"   # name -> exercise (id, units)
 ```
 
-During development, run from source with `pnpm start <args>`; after `pnpm build`, the
-`trainheroic` binary (`dist/cli.mjs`) does the same.
+**Driving this from an AI agent?** Run `trainheroic skill` first — it prints the full
+workflow guide (with copy-paste workout-spec examples) to stdout, version-matched to the
+binary; `trainheroic skill --full` adds the API and workout-creation reference docs. It's the
+fastest way to get the spec shapes right instead of guessing from flags.
+
+Commands split into three groups. `whoami` and `request` are **shared** (role-agnostic).
+Everything for managing a roster lives under **`coach`** — reads (`coach athletes`,
+`coach programs`, `coach teams`, `coach program <id>`, …), the exercise library
+(`coach exercise resolve|search|get|sync|create|forget|stats`), the workout lifecycle
+(`coach workout build|read|publish|remove`), and messaging
+(`coach message list|read|draft|send|delete`). Your own training lives under **`athlete`**.
+Run `trainheroic` with no command for the full reference. Dates are `Y-M-D` with a 1-based
+month, e.g. `2026-6-22` or `2026-06-22` for 22 June 2026.
 
-Run `trainheroic` with no command to print the full help. Commands group into reads
-(`whoami`, `athletes`, `programs`, `teams`, `program <id>`, and the rest), a raw `request`
-escape hatch, exercise-library operations (`resolve`, `search`, `get`, `sync`, `create`,
-`forget`, `stats`), the workout lifecycle (`build`, `read`, `publish`, `remove`), and
-messaging (`list`, `read`, `draft`, `send`, `delete`).
+### Building a workout
+
+`coach workout build` reads a workout spec — a JSON file (`--file`), an inline argument, or
+stdin — and writes it into a program on a date. `--program` is a program id (find it in the
+program's URL in the TrainHeroic web app, or run `trainheroic coach programs`). The spec is
+`{ blocks, instruction? }` (a bare blocks array is also accepted). Each exercise's `id` is a
+library id; get one with `coach exercise resolve`. `reps` and `weight` take a scalar or a
+per-set array (`"reps": [5, 5, 3]`); loads use the exercise's configured unit. The full schema
+is `WorkoutSpec` in [`@trainheroic-unofficial/dto`](../dto).
+
+```jsonc
+// day.json — one block with one exercise (id 41822 is a library exercise id)
+{
+  "instruction": "Warm up first.",
+  "blocks": [
+    {
+      "title": "Strength",
+      "exercises": [{ "id": 41822, "sets": 5, "reps": 5, "weight": 225, "rpe": 8 }],
+    },
+  ],
+}
+```
+
+```bash
+# Build as a draft (988 is the program id):
+trainheroic coach workout build --program 988 --date 2026-6-22 --file day.json
+
+# Build and publish to athletes (publishing is athlete-facing, so it needs --yes):
+trainheroic coach workout build --program 988 --date 2026-6-22 --file day.json --publish --yes
+```
+
+### Raw requests
+
+For an endpoint with no dedicated command, call it directly:
+
+```bash
+trainheroic request GET /user/simple
+trainheroic request POST /some/path '{"key":"value"}' --base apis
+```
+
+`--base` selects the host: `coach` (the default, `api.trainheroic.com`) or `apis`
+(`apis.trainheroic.com`). The body can be inline JSON (as above) or `--file <path>`.
 
 ## Conventions
 
-- Output is JSON on stdout; errors go to stderr with a non-zero exit code.
-- Actions that touch an athlete or delete data require an explicit `--yes`. That covers
-  `workout publish`, `workout remove`, `exercise forget`, `message send`, `message delete`,
-  and `workout build --publish`.
+- Output is JSON on stdout; errors go to stderr with a non-zero exit code and a readable
+  validation path on bad input.
+- Actions that touch an athlete or delete data require an explicit `--yes`:
+  `coach workout publish`, `coach workout remove`, `coach exercise forget`,
+  `coach message send`, `coach message delete`, `athlete log-set`, and
+  `coach workout build --publish`. (`coach workout build` alone creates a draft; `--publish`
+  makes it visible to athletes, which is why that combination needs `--yes`.)
 - JSON input can be passed inline, with `--file <path>`, or piped on stdin. Inputs are
-  validated against the shared schemas from `@trainheroic-unofficial/dto`.
+  validated against the shared schemas from `@trainheroic-unofficial/dto` before sending.
 - The session token and the exercise library are cached under `~/.trainheroic/`. The library
-  file is the same shape the local server uses, so the two share a cache.
+  file matches the shape the local coach server (`@trainheroic-unofficial/coach-mcp`) writes,
+  so the CLI and that server share one cache.
 
 ## Develop
 
+Run `pnpm install` once at the repo root (Node >= 22, pnpm 10), then from this package. During
+development, run from source with `pnpm start <args>`; after `pnpm build`, the `trainheroic`
+binary (`dist/cli.mjs`) does the same.
+
 ```bash
 pnpm start whoami   # tsx src/cli.ts
 pnpm build          # tsdown -> dist/cli.mjs

package/dist/cli.mjs

@@ -1448,38 +1448,48 @@ async function saveSession(sessionId) {
 const HELP = `trainheroic — command-line tool for the TrainHeroic coaching API
 
 Credentials come from TRAINHEROIC_EMAIL and TRAINHEROIC_PASSWORD. Output is JSON.
+Coaching commands live under 'coach'; your own training lives under 'athlete'.
+
+Start here (for AI agents):
+  trainheroic skill          full workflow guide + copy-paste examples (esp. workout specs)
+  trainheroic skill --full   also print the API + workout-creation reference docs
+  trainheroic skill list     list the available guides (coach, athlete)
 
 Setup:
   install-skill   copy the Claude Code skills to ~/.claude/skills/
 
-Reads:
-  whoami | head-coach | athletes | programs | teams | notifications | analytics
-  program <id> | team <id> | team-codes <id>
-  request <METHOD> <path> [json] [--base coach|apis] [--file f]   raw API call
+Shared:
+  whoami                                                          the logged-in account
+  request <METHOD> <path> [json] [--base coach|apis] [--file f]   raw API call (--base defaults to coach)
+
+Coach — manage a roster (needs a coach account):
+  coach head-coach | athletes | programs | teams | notifications | analytics
+  coach program <id> | team <id> | team-codes <id>
 
-Exercises (cached at ~/.trainheroic/library.json):
-  exercise resolve <name>
-  exercise search <query> [--limit N]
-  exercise get <id>
-  exercise sync [--force]
-  exercise create <json>|--file f
-  exercise forget <id> --yes
-  exercise stats
+  exercise library (cached at ~/.trainheroic/library.json):
+  coach exercise resolve <name>
+  coach exercise search <query> [--limit N]
+  coach exercise get <id>
+  coach exercise sync [--force]
+  coach exercise create <json>|--file f
+  coach exercise forget <id> --yes
+  coach exercise stats
 
-Workouts:
-  workout build --program <id> (--date Y-M-D | --timeline-day <n>) [--publish --yes] <spec.json>|--file f
-  workout read --program <id> --date Y-M-D --pw <id>
-  workout publish --pw <id> --yes
-  workout remove --program <id> --pw <id> --yes
+  workouts (spec: {"blocks":[{"title","exercises":[{"id","sets"?,"reps"?,"weight"?,"rpe"?}]}],"instruction"?};
+            reps/weight may be a scalar or per-set array; omit --publish to leave a draft):
+  coach workout build --program <id> (--date Y-M-D | --timeline-day <n>) [--publish --yes] <spec.json>|--file f
+  coach workout read --program <id> --date Y-M-D --pw <id>
+  coach workout publish --pw <id> --yes
+  coach workout remove --program <id> --pw <id> --yes
 
-Messaging:
-  message list
-  message read <streamId> [--limit N]
-  message draft <streamId> <text> [--reply-to <id>]
-  message send <streamId> <text> [--reply-to <id>] --yes
-  message delete <streamId> <commentId> --yes
+  messaging:
+  coach message list
+  coach message read <streamId> [--limit N]
+  coach message draft <streamId> <text> [--reply-to <id>]
+  coach message send <streamId> <text> [--reply-to <id>] --yes
+  coach message delete <streamId> <commentId> --yes
 
-Athlete (the logged-in user's own training; a coach account works too):
+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]
@@ -1507,9 +1517,9 @@ function toInt(value, label) {
 	return n;
 }
 /** Validate input against a dto schema, failing with a readable message on mismatch. */
-function validate(schema, value, label) {
+function validate(schema, value, label, hint) {
 	const result = schema.safeParse(value);
-	if (!result.success) fail(`invalid ${label} — ${result.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+	if (!result.success) fail(`invalid ${label} — ${result.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}${hint ? `\n${hint}` : ""}`);
 	return result.data;
 }
 function parse(args, options) {
@@ -1577,14 +1587,14 @@ async function cmdExercise(client, rest) {
 	const [sub, ...a] = rest;
 	const lib = library(client);
 	switch (sub) {
-		case "resolve": return out(await lib.resolve(need(a.join(" ").trim() || void 0, "exercise resolve <name>")));
+		case "resolve": return out(await lib.resolve(need(a.join(" ").trim() || void 0, "coach exercise resolve <name>")));
 		case "search": {
 			const { values, positionals } = parse(a, { limit: { type: "string" } });
-			const query = need(positionals.join(" ").trim() || void 0, "exercise search <query>");
+			const query = need(positionals.join(" ").trim() || void 0, "coach exercise search <query>");
 			const limit = values.limit !== void 0 ? toInt(values.limit, "--limit") : 20;
 			return out(await lib.search(query, limit));
 		}
-		case "get": return out(await lib.get(toInt(need(a[0], "exercise get <id>"), "id")));
+		case "get": return out(await lib.get(toInt(need(a[0], "coach exercise get <id>"), "id")));
 		case "sync": {
 			const { values } = parse(a, { force: { type: "boolean" } });
 			if (values.force === true) return out(await lib.refresh());
@@ -1598,13 +1608,13 @@ async function cmdExercise(client, rest) {
 		}
 		case "forget": {
 			const { values, positionals } = parse(a, { yes: { type: "boolean" } });
-			const id = toInt(need(positionals[0], "exercise forget <id> --yes"), "id");
+			const id = toInt(need(positionals[0], "coach exercise forget <id> --yes"), "id");
 			if (values.yes !== true) fail(`add --yes to forget exercise ${id} from the local cache.`);
 			await lib.recordDelete(id);
 			return out({ forgotten: id });
 		}
 		case "stats": return out(await lib.stats());
-		default: return fail("usage: trainheroic exercise <resolve|search|get|sync|create|forget|stats>");
+		default: return fail("usage: trainheroic coach exercise <resolve|search|get|sync|create|forget|stats>");
 	}
 }
 async function cmdWorkout(client, rest) {
@@ -1619,10 +1629,10 @@ async function cmdWorkout(client, rest) {
 				yes: { type: "boolean" },
 				file: { type: "string" }
 			});
-			const programId = toInt(need(values.program, "workout build --program <id> ..."), "--program");
+			const programId = toInt(need(values.program, "coach workout build --program <id> ..."), "--program");
 			if (values.date === void 0 && values["timeline-day"] === void 0) fail("provide --date YYYY-M-D or --timeline-day <n>.");
 			const parsed = await jsonInput(positionals[0], values.file);
-			const spec = validate(workoutSpecSchema, Array.isArray(parsed) ? { blocks: parsed } : parsed, "workout spec");
+			const spec = validate(workoutSpecSchema, Array.isArray(parsed) ? { blocks: parsed } : parsed, "workout spec", "run 'trainheroic skill' for the workout spec format and copy-paste examples.");
 			const publish = values.publish === true;
 			if (publish && values.yes !== true) fail("publishing is athlete-facing; add --yes to build and publish.");
 			const opts = {
@@ -1649,14 +1659,14 @@ async function cmdWorkout(client, rest) {
 				date: { type: "string" },
 				pw: { type: "string" }
 			});
-			return out(await readSession(client, toInt(need(values.program, "workout read --program <id> --date Y-M-D --pw <id>"), "--program"), parseWorkoutDate(need(values.date, "workout read --program <id> --date Y-M-D --pw <id>")), toInt(need(values.pw, "workout read --program <id> --date Y-M-D --pw <id>"), "--pw")));
+			return out(await readSession(client, toInt(need(values.program, "coach workout read --program <id> --date Y-M-D --pw <id>"), "--program"), parseWorkoutDate(need(values.date, "coach workout read --program <id> --date Y-M-D --pw <id>")), toInt(need(values.pw, "coach workout read --program <id> --date Y-M-D --pw <id>"), "--pw")));
 		}
 		case "publish": {
 			const { values } = parse(a, {
 				pw: { type: "string" },
 				yes: { type: "boolean" }
 			});
-			const pw = toInt(need(values.pw, "workout publish --pw <id> --yes"), "--pw");
+			const pw = toInt(need(values.pw, "coach workout publish --pw <id> --yes"), "--pw");
 			if (values.yes !== true) fail(`publishing makes pw ${pw} athlete-visible; add --yes.`);
 			await publishSession(client, pw);
 			return out({ published: pw });
@@ -1667,13 +1677,13 @@ async function cmdWorkout(client, rest) {
 				pw: { type: "string" },
 				yes: { type: "boolean" }
 			});
-			const programId = toInt(need(values.program, "workout remove --program <id> --pw <id> --yes"), "--program");
-			const pw = toInt(need(values.pw, "workout remove --program <id> --pw <id> --yes"), "--pw");
+			const programId = toInt(need(values.program, "coach workout remove --program <id> --pw <id> --yes"), "--program");
+			const pw = toInt(need(values.pw, "coach workout remove --program <id> --pw <id> --yes"), "--pw");
 			if (values.yes !== true) fail(`removing pw ${pw} deletes the session; add --yes.`);
 			await removeSession(client, programId, pw);
 			return out({ removed: pw });
 		}
-		default: return fail("usage: trainheroic workout <build|read|publish|remove>");
+		default: return fail("usage: trainheroic coach workout <build|read|publish|remove>");
 	}
 }
 async function cmdMessage(client, rest) {
@@ -1688,14 +1698,14 @@ async function cmdMessage(client, rest) {
 		})));
 		case "read": {
 			const { values, positionals } = parse(a, { limit: { type: "string" } });
-			return out(await readLive(client, toInt(need(positionals[0], "message read <streamId> [--limit N]"), "streamId"), values.limit !== void 0 ? toInt(values.limit, "--limit") : 20));
+			return out(await readLive(client, toInt(need(positionals[0], "coach message read <streamId> [--limit N]"), "streamId"), values.limit !== void 0 ? toInt(values.limit, "--limit") : 20));
 		}
 		case "draft": {
 			const { values, positionals } = parse(a, { "reply-to": { type: "string" } });
 			return out({
 				draft: true,
 				note: "NOT sent. Run 'message send' with --yes to deliver.",
-				payload: buildCommentPayload(toInt(need(positionals[0], "message draft <streamId> <text>"), "streamId"), need(positionals.slice(1).join(" ").trim() || void 0, "message draft <streamId> <text>"), values["reply-to"] !== void 0 ? toInt(values["reply-to"], "--reply-to") : null)
+				payload: buildCommentPayload(toInt(need(positionals[0], "coach message draft <streamId> <text>"), "streamId"), need(positionals.slice(1).join(" ").trim() || void 0, "coach message draft <streamId> <text>"), values["reply-to"] !== void 0 ? toInt(values["reply-to"], "--reply-to") : null)
 			});
 		}
 		case "send": {
@@ -1703,8 +1713,8 @@ async function cmdMessage(client, rest) {
 				"reply-to": { type: "string" },
 				yes: { type: "boolean" }
 			});
-			const streamId = toInt(need(positionals[0], "message send <streamId> <text> --yes"), "streamId");
-			const text = need(positionals.slice(1).join(" ").trim() || void 0, "message send <streamId> <text> --yes");
+			const streamId = toInt(need(positionals[0], "coach message send <streamId> <text> --yes"), "streamId");
+			const text = need(positionals.slice(1).join(" ").trim() || void 0, "coach message send <streamId> <text> --yes");
 			const replyTo = values["reply-to"] !== void 0 ? toInt(values["reply-to"], "--reply-to") : null;
 			if (values.yes !== true) fail(`sending to stream ${streamId} is athlete-facing and immediate; add --yes.`);
 			return out({
@@ -1714,15 +1724,15 @@ async function cmdMessage(client, rest) {
 		}
 		case "delete": {
 			const { values, positionals } = parse(a, { yes: { type: "boolean" } });
-			const streamId = toInt(need(positionals[0], "message delete <streamId> <commentId> --yes"), "streamId");
-			const commentId = toInt(need(positionals[1], "message delete <streamId> <commentId> --yes"), "commentId");
+			const streamId = toInt(need(positionals[0], "coach message delete <streamId> <commentId> --yes"), "streamId");
+			const commentId = toInt(need(positionals[1], "coach message delete <streamId> <commentId> --yes"), "commentId");
 			if (values.yes !== true) fail(`deleting comment ${commentId} acts on the live account; add --yes.`);
 			return out({
 				deleted: true,
 				response: await deleteComment(client, streamId, commentId)
 			});
 		}
-		default: return fail("usage: trainheroic message <list|read|draft|send|delete>");
+		default: return fail("usage: trainheroic coach message <list|read|draft|send|delete>");
 	}
 }
 function isoDate(value, label) {
@@ -1883,6 +1893,28 @@ async function cmdAthlete(client, rest) {
 		default: return fail("usage: trainheroic athlete <whoami|profile|prefs|workouts|exercises|history|prs|stats|working-maxes|leaderboard|export|log-set>");
 	}
 }
+async function cmdSkill(rest) {
+	const skillRoot = join(import.meta.dirname, "../skill");
+	const positional = rest.find((r) => !r.startsWith("-"));
+	if (positional === "list") return out((await readdir(skillRoot, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name));
+	const name = positional ?? "trainheroic-unofficial";
+	const dir = join(skillRoot, name);
+	let text;
+	try {
+		text = await readFile(join(dir, "SKILL.md"), "utf8");
+	} catch {
+		return fail(`unknown skill "${name}". Run 'trainheroic skill list'.`);
+	}
+	process.stdout.write(text);
+	if (rest.includes("--full")) try {
+		const refDir = join(dir, "references");
+		const refs = (await readdir(refDir)).filter((f) => f.endsWith(".md")).sort();
+		for (const f of refs) {
+			process.stdout.write(`\n\n===== references/${f} =====\n\n`);
+			process.stdout.write(await readFile(join(refDir, f), "utf8"));
+		}
+	} catch {}
+}
 async function cmdInstallSkill() {
 	const home = process.env.HOME ?? process.env.USERPROFILE;
 	if (!home) fail("cannot determine home directory.");
@@ -1902,22 +1934,30 @@ async function cmdInstallSkill() {
 	}
 	out({ installed });
 }
-async function dispatch(client, group, rest) {
-	switch (group) {
-		case "whoami": return out(await get(client, "/user/simple"));
+const COACH_USAGE = "usage: trainheroic coach <head-coach|athletes|programs|teams|notifications|analytics|program <id>|team <id>|team-codes <id>|exercise|workout|message>";
+async function cmdCoach(client, rest) {
+	const [sub, ...a] = rest;
+	switch (sub) {
 		case "head-coach": return out(await get(client, "/v5/headCoach"));
 		case "athletes": return out(await get(client, "/v5/athletes"));
 		case "programs": return out(await get(client, "/1.0/coach/programs"));
 		case "teams": return out(await get(client, "/1.0/coach/teams"));
 		case "notifications": return out(await get(client, "/v5/notifications/counts"));
 		case "analytics": return out(await get(client, "/v5/analytics"));
-		case "program": return out(await get(client, `/3.0/coach/program/${encodeURIComponent(need(rest[0], "program <id>"))}`));
-		case "team": return out(await get(client, `/v5/teams/${encodeURIComponent(need(rest[0], "team <id>"))}`));
-		case "team-codes": return out(await get(client, `/v5/teams/${encodeURIComponent(need(rest[0], "team-codes <id>"))}/teamCodes`));
+		case "program": return out(await get(client, `/3.0/coach/program/${encodeURIComponent(need(a[0], "coach program <id>"))}`));
+		case "team": return out(await get(client, `/v5/teams/${encodeURIComponent(need(a[0], "coach team <id>"))}`));
+		case "team-codes": return out(await get(client, `/v5/teams/${encodeURIComponent(need(a[0], "coach team-codes <id>"))}/teamCodes`));
+		case "exercise": return cmdExercise(client, a);
+		case "workout": return cmdWorkout(client, a);
+		case "message": return cmdMessage(client, a);
+		default: return fail(COACH_USAGE);
+	}
+}
+async function dispatch(client, group, rest) {
+	switch (group) {
+		case "whoami": return out(await get(client, "/user/simple"));
 		case "request": return cmdRequest(client, rest);
-		case "exercise": return cmdExercise(client, rest);
-		case "workout": return cmdWorkout(client, rest);
-		case "message": return cmdMessage(client, rest);
+		case "coach": return cmdCoach(client, rest);
 		case "athlete": return cmdAthlete(client, rest);
 		default: return fail(`unknown command "${group}". Run 'trainheroic help'.`);
 	}
@@ -1932,6 +1972,10 @@ async function main() {
 		await cmdInstallSkill();
 		return;
 	}
+	if (group === "skill") {
+		await cmdSkill(rest);
+		return;
+	}
 	const email = process.env.TRAINHEROIC_EMAIL;
 	const password = process.env.TRAINHEROIC_PASSWORD;
 	if (!email || !password) fail("set TRAINHEROIC_EMAIL and TRAINHEROIC_PASSWORD in the environment.");

package/package.json

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

package/skill/trainheroic-unofficial/SKILL.md

@@ -76,24 +76,25 @@ cat block.json | $TH request POST /2.0/coach/calendar/saveProgramWorkoutSets
 ```
 
 A few endpoints live on the login host (`apis.trainheroic.com`); reach them with
-`--base apis` (the default base is the coach host). Named shortcuts cover the common
-reads: `whoami`, `head-coach`, `athletes`, `programs`, `teams`, `notifications`,
-`analytics`, `program <id>`, `team <id>`, `team-codes <id>`.
+`--base apis` (the default base is the coach host). `whoami` and `request` are top-level;
+the coach reads live under the `coach` group: `coach head-coach`, `coach athletes`,
+`coach programs`, `coach teams`, `coach notifications`, `coach analytics`,
+`coach program <id>`, `coach team <id>`, `coach team-codes <id>`.
 
 Load `references/api-reference.md` when you need an endpoint's exact request or
 response shape, or an area not covered here.
 
 ## What you can do
 
-| Area                | How                                                                                                                       |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| Athletes            | `$TH athletes`; invite/archive/restore via `$TH request ...`                                                              |
-| Teams               | `$TH teams`, `$TH team <id>`, `$TH team-codes <id>`; create via `$TH request POST /1.0/coach/team/createWithTitleAndCode` |
-| Programs            | `$TH programs`, `$TH program <id>`                                                                                        |
-| Exercises           | `$TH exercise resolve\|search\|get\|sync\|create\|forget\|stats` (below)                                                  |
-| Sessions / workouts | `$TH workout build\|read\|publish\|remove` (below)                                                                        |
-| Messaging           | `$TH message list\|read\|draft\|send\|delete` (below)                                                                     |
-| Analytics           | `$TH analytics`, then `$TH request POST /v5/analytics/*`                                                                  |
+| Area                | How                                                                                                                                         |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| Athletes            | `$TH coach athletes`; invite/archive/restore via `$TH request ...`                                                                          |
+| Teams               | `$TH coach teams`, `$TH coach team <id>`, `$TH coach team-codes <id>`; create via `$TH request POST /1.0/coach/team/createWithTitleAndCode` |
+| Programs            | `$TH coach programs`, `$TH coach program <id>`                                                                                              |
+| Exercises           | `$TH coach exercise resolve\|search\|get\|sync\|create\|forget\|stats` (below)                                                              |
+| Sessions / workouts | `$TH coach workout build\|read\|publish\|remove` (below)                                                                                    |
+| Messaging           | `$TH coach message list\|read\|draft\|send\|delete` (below)                                                                                 |
+| Analytics           | `$TH coach analytics`, then `$TH request POST /v5/analytics/*`                                                                              |
 
 ## Resolving exercises
 
@@ -102,9 +103,9 @@ cache, which mirrors the library into `~/.trainheroic/library.json` and serves l
 locally:
 
 ```bash
-$TH exercise resolve "Back Squat"      # exact/best match -> id (+ unit labels)
-$TH exercise search  "incline press"   # ranked candidates
-$TH exercise sync --force              # refresh the mirror (7-day TTL otherwise)
+$TH coach exercise resolve "Back Squat"      # exact/best match -> id (+ unit labels)
+$TH coach exercise search  "incline press"   # ranked candidates
+$TH coach exercise sync --force              # refresh the mirror (7-day TTL otherwise)
 ```
 
 `resolve` returns `match: null` plus a candidate list when a name is ambiguous; pick the
@@ -114,11 +115,11 @@ After creating a custom exercise, go through the cache so the mirror stays curre
 deleting one via the API, drop it from the mirror:
 
 ```bash
-$TH exercise create '{"title":"Sandbag Clean","param_1_type":3,"param_2_type":1}'
-$TH exercise forget 7721170 --yes      # cache-only, run after an API delete
+$TH coach exercise create '{"title":"Sandbag Clean","param_1_type":3,"param_2_type":1}'
+$TH coach exercise forget 7721170 --yes      # cache-only, run after an API delete
 ```
 
-`$TH exercise stats` shows the cached row count.
+`$TH coach exercise stats` shows the cached row count.
 
 ## Building a workout
 
@@ -130,7 +131,7 @@ follow-up questions first; do not guess.** Restate the program you intend to bui
 explicit confirmation before publishing. Build a draft (the default), show the read-back
 for review, and only publish once the user confirms.
 
-`$TH workout build` runs the whole sequence (program → session → blocks → exercises),
+`$TH coach workout build` runs the whole sequence (program → session → blocks → exercises),
 fills every field that otherwise makes the exercise step return HTTP 500, encodes
 prescriptions correctly, and prints unit advisories plus a read-back. Feed it a JSON spec
 (inline, `--file`, or stdin):
@@ -146,15 +147,15 @@ cat > day.json <<'JSON'
 ] }
 JSON
 
-$TH workout build --program 4980851 --date 2026-6-22 --file day.json     # draft
-$TH workout publish --pw <id> --yes                                       # publish after review
+$TH coach workout build --program 4980851 --date 2026-6-22 --file day.json   # draft
+$TH coach workout publish --pw <id> --yes                                     # publish after review
 ```
 
 The build defaults to a **draft** (unpublished). Add `--publish --yes` to publish in one
-step, or publish later with `$TH workout publish --pw <id> --yes`. Read a built session
-back with `$TH workout read --program <id> --date Y-M-D --pw <id>`. There is no in-place
+step, or publish later with `$TH coach workout publish --pw <id> --yes`. Read a built session
+back with `$TH coach workout read --program <id> --date Y-M-D --pw <id>`. There is no in-place
 replace: to rebuild a date, remove the old session first with
-`$TH workout remove --program <id> --pw <id> --yes`.
+`$TH coach workout remove --program <id> --pw <id> --yes`.
 
 Two exercises in one block become a superset. Add `"leaderboard": "rounds"` (or
 `reps`/`time`/`calories`/`meters`/… or `{"unit":"time","lowest_wins":true}`) to a block to
@@ -178,17 +179,17 @@ draft state, so a POST is delivered at once. The CLI therefore separates draftin
 sending and requires `--yes` to actually send or delete.
 
 ```bash
-$TH message list                                  # conversations (id, kind, title)
-$TH message read   37730920                        # recent messages
-$TH message draft  37730920 "Great session today!" # PREVIEW only — never sends
-$TH message send   37730920 "Great session today!" --yes              # delivers (gate behind user OK)
-$TH message send   37730920 "Nice PR!" --reply-to 125652586 --yes     # threaded reply
-$TH message delete 37730920 <commentId> --yes                          # soft delete (destructive)
+$TH coach message list                                  # conversations (id, kind, title)
+$TH coach message read   37730920                        # recent messages
+$TH coach message draft  37730920 "Great session today!" # PREVIEW only — never sends
+$TH coach message send   37730920 "Great session today!" --yes              # delivers (gate behind user OK)
+$TH coach message send   37730920 "Nice PR!" --reply-to 125652586 --yes     # threaded reply
+$TH coach message delete 37730920 <commentId> --yes                          # soft delete (destructive)
 ```
 
 Default to `draft`: it prints the exact payload and target without touching the account.
 Run `send` only after the user confirms the wording and recipient. Check
-`$TH notifications` (`countMessagingNotViewed`) first as a cheap "anything new?" gate.
+`$TH coach notifications` (`countMessagingNotViewed`) first as a cheap "anything new?" gate.
 
 ## Gotchas
 
@@ -204,7 +205,7 @@ Environment-specific facts that defy reasonable assumptions:
   "200 m run" on it shows as 200 _miles_. And `param_2_type` `2` (% of max) and `14` (RPE)
   coerce to weight on a weight lift, rendering as pounds — put % or RPE in the
   `instruction` (the builder does this from `rpe`). You _can_ add weight (`1`) to a
-  no-secondary-param lift (weighted Pull-Ups). Check units with `$TH exercise resolve`
+  no-secondary-param lift (weighted Pull-Ups). Check units with `$TH coach exercise resolve`
   (the `units` array, ordered by entry slot `[param 1, param 2]`); the builder prints a
   warning when a sent type will be overridden. "Max"/"AMRAP" reps work as free text in the
   rep slots.
@@ -235,9 +236,9 @@ Environment-specific facts that defy reasonable assumptions:
   3. **offer the user the option to do it themselves** — hand them the exact command (e.g.
      `$TH request DELETE /v5/teamCodes/874586`) or the UI steps.
 
-  The CLI enforces a `--yes` flag on `message send`/`message delete`, `workout publish`,
-  `workout remove`, and `exercise forget`, but the gate above still applies: confirm in the
-  moment before adding `--yes`.
+  The CLI enforces a `--yes` flag on `coach message send`/`coach message delete`,
+  `coach workout publish`, `coach workout remove`, and `coach exercise forget`, but the gate
+  above still applies: confirm in the moment before adding `--yes`.
 
 ## Beyond the CLI
 

package/skill/trainheroic-unofficial/references/api-reference.md

@@ -554,7 +554,7 @@ This creates A1: Back Squat, A2: Front Squat displayed as a superset.
 >   `Run` (id 82) is `10` (miles); sending `6` (meters) is ignored and `200` shows as
 >   _200 miles_. To program meters, pick a meters-native exercise (`Sprint` 127,
 >   `Rowing` 101, `Shuttle Sprint` 42523) or a custom exercise — there is no metric
->   "Run". `$TH exercise resolve` now prints a `units` array (ordered by entry slot,
+>   "Run". `$TH coach exercise resolve` now prints a `units` array (ordered by entry slot,
 >   `[param 1, param 2]`); check it.
 > - **`param_2_type` (secondary) is forced to the default too, with one exception:**
 >   if the exercise has no secondary param (default `0`/none) you may add weight
@@ -753,7 +753,7 @@ Creates a reusable session template in the library.
 
 Chat between a coach and athletes/teams. A **stream** is a conversation; a
 **comment** is a message in it. Verified against a live
-account (see `$TH message`).
+account (see `$TH coach message`).
 
 | Method | Endpoint                                                       | Description                                                                    |
 | ------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------ |

package/skill/trainheroic-unofficial/references/workout-creation.md

@@ -229,7 +229,7 @@ sent under the wrong assumed unit silently renders under the exercise's real uni
   (`1`) to an exercise that has no secondary param (default `0`/none) — that is how
   weighted Pull-Ups/Dips work. `2` (% of max) and `14` (RPE) do **not** stick on a
   weight-default lift; both coerce to weight and render as pounds.
-- Check an exercise's real units first: `$TH exercise resolve "<name>"` prints a
+- Check an exercise's real units first: `$TH coach exercise resolve "<name>"` prints a
   `units` array, ordered by entry slot (`[param 1, param 2]`). the workout builder also
   prints a `WARNING` when a sent param type will be overridden, and its read-back labels
   the stored units.