trainerroad-cli 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.4.0 - 2026-09-02
+
+- Added `add-annotation`, `remove-annotation`, and `annotation-details`: create time off, illness, injury, and note entries (single or multi-day via `--days` or `--end-date`), remove them by id (no-op when already gone), and read the title and notes that the timeline rows omit. Uses `POST/DELETE /app/api/calendar/annotations` and `GET /app/api/react-calendar/annotation/{id}`, confirmed live.
+- Added `add-event`: creates a race or event via `POST /app/api/calendar/plannedactivities/event` with discipline (by name or id), A/B/C priority, duration, and either a TSS or a 1-10 intensity estimate. Confirmed live. Events are removed with `remove-workout`.
+- Added `remove-workout`: deletes a planned workout or event by planned-activity id via `DELETE /app/api/calendar/plannedactivities/{id}` (confirmed live), with `--dry-run` and a no-op when the record is already gone.
+- Fixed swapped annotation type labels: typeId 2 is illness and typeId 4 is time off (checked against the web app's enum and real calendar entries). Plan-marker ids 5 to 10 are now labelled too.
+- Added `workout-image`: saves a workout's power-profile chart as PNG (default, via the optional `@resvg/resvg-js` package) or SVG. Workout records from `workout-library` and `workout-details` now include `chartUrl`.
+- Fixed `power-records`: the web app moved to `POST /app/api/personal-records/{memberId}`; the old `/for-date-range` path stays as a 404 fallback.
+- Key normalisation now runs per object at every depth, because personal-records nests PascalCase rows inside a camelCase envelope.
+- Help output uses per-command flag descriptions, so shared names like `--type` and `--days` read correctly for each command.
+- Write commands report an `adaptiveTraining` note, and the README explains how Adaptive Training reacts to calendar changes and how an agent should read an athlete's situation.
+- Fixed `login`: TrainerRoad replaced the server-rendered login form with a React app, so the token scrape failed. `login` now posts JSON to `/app/api/login/login` the way the web app does, and falls back to the old form flow if that route ever disappears. A bad password now fails with "TrainerRoad rejected the username or password" instead of a redirect error.
+- Fixed `plan` returning 404s: plan-builder endpoints are requested by numeric `memberId` instead of username (the username stays in the referer). The career-summary endpoint had the same problem and now takes a `memberId` too.
+- Made a missing `current-custom-plan` (HTTP 404) non-fatal. The web app no longer calls that endpoint at all, so when it is absent `currentPlan` is derived from `all-user-plans` (the plan whose start/end window contains today) and its matching `plan-phases` rows. `currentPlan.source` reports which path produced it, and `currentPhaseName` names the active phase.
+- Every API request now sends `trainerroad-jsonformat: camel-case` by default, and a PascalCase payload is normalised to camelCase if the header is ever ignored, so a dropped header or a casing change cannot blank the output.
+- Request failures throw `HttpError` with `status`, `statusText`, `path`, and `payload` (message unchanged).
+- Added tests for the JSON login flow and its fallback, memberId-keyed URLs, the format header, PascalCase normalisation, non-fatal 404 handling, and date-window current-plan derivation.
+
 ## 0.3.0 - 2026-03-25
 
 - Added richer command help with examples, required-flag metadata, and machine-readable help payloads.

package/README.md

@@ -26,6 +26,10 @@ It can also perform a small set of verified calendar writes for planned workouts
 - list TrainerRoad alternate workout options
 - replace a workout with a specific alternate
 - switch a workout between inside and outside
+- remove a planned workout or event
+- add a race or event with discipline, priority, and a TSS or intensity estimate
+- add and remove calendar annotations: time off, illness, injury, notes
+- save a workout's power-profile chart as PNG or SVG
 
 ## Agent-Friendly Behavior
 
@@ -34,6 +38,30 @@ It can also perform a small set of verified calendar writes for planned workouts
 - Command help includes concrete examples and flag descriptions.
 - Write commands support `--dry-run` previews.
 - Common retry cases are idempotent no-ops instead of duplicate calendar writes.
+- Every write returns `before`/`after` (or the created record) so the caller can verify without a second call.
+
+## How TrainerRoad Reacts To Calendar Changes
+
+TrainerRoad's Adaptive Training treats the calendar as input. Agents managing an athlete's plan should expect:
+
+- Removing or skipping a planned workout can cause TrainerRoad to rebuild the upcoming plan around the gap.
+- Adding a workout, or marking time off, illness, or injury, can likewise shift the surrounding planned workouts.
+- Planned workouts carry `recommendationReason`, `adaptationLocked`, and `adaptationAltered` fields that show whether TrainerRoad chose or altered them.
+- After any write, re-read `future --days 14 --details` before deciding the next step. Do not assume the calendar looks the way it did before the write.
+
+Write commands echo this in an `adaptiveTraining` field so it is visible in machine-readable output.
+
+## Reading The Athlete's Situation
+
+A useful order for an agent building a picture of how training is going:
+
+1. `whoami` for FTP, weight, and timezone.
+2. `plan --view current` for the plan, its phases, and the phase the athlete is in today.
+3. `past --days 28 --details` and `future --days 14 --details` for what happened and what is scheduled.
+4. `levels` for progression levels by zone, and `ftp-prediction` for where FTP is heading.
+5. `annotations --from <date>` for time off, illness, and injury, and `annotation-details --id` for the notes behind them.
+6. `events` for upcoming races.
+7. `workout-image --id <workout-id>` when a picture of a workout's intervals helps explain it.
 
 ## Install
 
@@ -111,12 +139,29 @@ trainerroad-cli move-workout --id <planned-activity-id> --to 2026-03-13 --json
 trainerroad-cli replace-workout --id <planned-activity-id> --alternate-id <workout-id> --json
 trainerroad-cli switch-workout --id <planned-activity-id> --mode outside --json
 trainerroad-cli copy-workout --id <planned-activity-id> --date 2026-03-16 --json
+trainerroad-cli remove-workout --id <planned-activity-id> --dry-run
 ```
 
 `copy-workout` is the reliable way to place an existing planned workout on another date.
 `add-workout` exists, but TrainerRoad's add endpoints are still inconsistent and may fail even after retry/reconciliation.
 
-4. Discover all commands
+4. Events, annotations, and images
+
+```bash
+trainerroad-cli add-event --name "Black Fork" --date 2027-05-01 --discipline gravel --priority A --duration 300 --tss 340 --dry-run
+trainerroad-cli add-event --name "Tuesday crit" --date 2026-10-06 --discipline criterium --priority C --duration 60 --intensity 9 --json
+trainerroad-cli remove-workout --id <planned-activity-id> --json   # events and workouts share this
+trainerroad-cli add-annotation --type time-off --date 2026-09-21 --days 3 --title "Travel" --dry-run
+trainerroad-cli add-annotation --type illness --date 2026-09-21 --end-date 2026-09-23 --notes "Head cold" --json
+trainerroad-cli annotation-details --id <annotation-id> --json
+trainerroad-cli remove-annotation --id <annotation-id> --json
+trainerroad-cli workout-image --id 1592808 --file fishers.png
+trainerroad-cli workout-image --id 1592808 --format svg --file fishers.svg
+```
+
+PNG output uses the optional `@resvg/resvg-js` package. If it is not installed, use `--format svg`.
+
+5. Discover all commands
 
 ```bash
 trainerroad-cli help

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trainerroad-cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Unofficial CLI for authenticating with TrainerRoad and querying timeline/workout data",
   "main": "src/cli.mjs",
   "bin": {
@@ -45,7 +45,11 @@
     "move-workout": "node src/cli.mjs move-workout",
     "replace-workout": "node src/cli.mjs replace-workout",
     "switch-workout": "node src/cli.mjs switch-workout",
-    "logout": "node src/cli.mjs logout"
+    "logout": "node src/cli.mjs logout",
+    "workout-image": "node src/cli.mjs workout-image",
+    "add-annotation": "node src/cli.mjs add-annotation",
+    "remove-annotation": "node src/cli.mjs remove-annotation",
+    "annotation-details": "node src/cli.mjs annotation-details"
   },
   "keywords": [
     "trainerroad",
@@ -60,5 +64,8 @@
   "type": "module",
   "dependencies": {
     "playwright": "^1.58.2"
+  },
+  "optionalDependencies": {
+    "@resvg/resvg-js": "^2.6.2"
   }
 }

package/src/cli.mjs

@@ -20,6 +20,7 @@ import {
   COMMAND_REQUIRED_FLAGS,
   COMMANDS,
   FLAG_DETAILS,
+  COMMAND_FLAG_DETAILS,
   FILTERABLE_COMMANDS,
   GLOBAL_NOTES,
   PROJECT_NOTICE,
@@ -43,7 +44,15 @@ import {
   commandReplaceWorkout,
   commandSwitchWorkout,
   commandWorkoutAlternates,
+  commandRemoveWorkout,
 } from "./commands/workout-mutations.mjs";
+import {
+  commandAddAnnotation,
+  commandAnnotationDetails,
+  commandRemoveAnnotation,
+} from "./commands/annotation-mutations.mjs";
+import { commandWorkoutImage } from "./commands/workout-image.mjs";
+import { commandAddEvent } from "./commands/event-mutations.mjs";
 import { commandFuture, commandPast, commandToday } from "./commands/workouts.mjs";
 import {
   formatDateTimeInTimeZone,
@@ -201,8 +210,12 @@ function validateCommandFlags(command, flags) {
   return { unknownFlags, allowlist: Array.from(allowlist) };
 }
 
-function formatFlagLabel(name) {
-  const detail = FLAG_DETAILS[name] ?? {};
+function flagDetail(command, name) {
+  return COMMAND_FLAG_DETAILS[command]?.[name] ?? FLAG_DETAILS[name] ?? {};
+}
+
+function formatFlagLabel(command, name) {
+  const detail = flagDetail(command, name);
   return `--${name}${detail.placeholder ? ` ${detail.placeholder}` : ""}`;
 }
 
@@ -211,8 +224,8 @@ function getCommandHelpOptions(command) {
   const requiredFlags = new Set(COMMAND_REQUIRED_FLAGS[command] ?? []);
   return allowlist.map((name) => ({
     name,
-    label: formatFlagLabel(name),
-    description: FLAG_DETAILS[name]?.description ?? "No description available.",
+    label: formatFlagLabel(command, name),
+    description: flagDetail(command, name).description ?? "No description available.",
     required: requiredFlags.has(name),
   }));
 }
@@ -405,14 +418,14 @@ function getLastItem(values) {
 
 function compactPersonalRecord(record) {
   return {
-    seconds: record?.Seconds ?? null,
-    watts: record?.Watts ?? null,
-    workoutDate: record?.WorkoutDate ?? null,
-    workoutSeconds: record?.WorkoutSeconds ?? null,
-    workoutGuid: record?.WorkoutGuid ?? null,
-    workoutRecordId: record?.WorkoutRecordId ?? null,
-    workoutRecordName: record?.WorkoutRecordName ?? null,
-    surveyResponse: record?.SurveyResponseTranslated ?? null,
+    seconds: record?.seconds ?? record?.Seconds ?? null,
+    watts: record?.watts ?? record?.Watts ?? null,
+    workoutDate: record?.workoutDate ?? record?.WorkoutDate ?? null,
+    workoutSeconds: record?.workoutSeconds ?? record?.WorkoutSeconds ?? null,
+    workoutGuid: record?.workoutGuid ?? record?.WorkoutGuid ?? null,
+    workoutRecordId: record?.workoutRecordId ?? record?.WorkoutRecordId ?? null,
+    workoutRecordName: record?.workoutRecordName ?? record?.WorkoutRecordName ?? null,
+    surveyResponse: record?.surveyResponseTranslated ?? record?.SurveyResponseTranslated ?? null,
   };
 }
 
@@ -786,6 +799,24 @@ async function main() {
     case "switch-workout":
       await commandSwitchWorkout(flags, commandDeps);
       return;
+    case "add-event":
+      await commandAddEvent(flags, commandDeps);
+      return;
+    case "remove-workout":
+      await commandRemoveWorkout(flags, commandDeps);
+      return;
+    case "workout-image":
+      await commandWorkoutImage(flags, commandDeps);
+      return;
+    case "annotation-details":
+      await commandAnnotationDetails(flags, commandDeps);
+      return;
+    case "add-annotation":
+      await commandAddAnnotation(flags, commandDeps);
+      return;
+    case "remove-annotation":
+      await commandRemoveAnnotation(flags, commandDeps);
+      return;
     case "logout":
       await commandLogout(flags, commandDeps);
       return;

package/src/commands/annotation-mutations.mjs

@@ -0,0 +1,253 @@
+import {
+  ANNOTATION_TYPE_IDS,
+  ANNOTATION_TYPE_LABELS,
+  compactAnnotationDetail,
+} from "../lib/planning-normalizers.mjs";
+import { shiftDateOnly } from "../lib/timezone.mjs";
+import { isHttpStatus } from "../trainerroad-client.mjs";
+
+const DAY_SECONDS = 86_400;
+
+function dateOnlyDiffDays(fromDateOnly, toDateOnly) {
+  const [fy, fm, fd] = fromDateOnly.split("-").map(Number);
+  const [ty, tm, td] = toDateOnly.split("-").map(Number);
+  return Math.round((Date.UTC(ty, tm - 1, td) - Date.UTC(fy, fm - 1, fd)) / DAY_SECONDS / 1000);
+}
+
+// TrainerRoad's Adaptive Training reacts to calendar changes: time off, illness, and injury
+// entries can prompt it to adjust the surrounding planned workouts. Surface that to agents.
+const ADAPTIVE_NOTE =
+  "TrainerRoad may adapt nearby planned workouts in response to this change. Re-read `future` afterwards.";
+
+function resolveAnnotationType(value) {
+  if (value === undefined || value === null || value === "") return null;
+  const raw = String(value).trim().toLowerCase();
+  if (/^\d+$/.test(raw)) {
+    const typeId = Number(raw);
+    return { typeId, typeLabel: ANNOTATION_TYPE_LABELS[typeId] ?? `type-${typeId}` };
+  }
+  const typeId = ANNOTATION_TYPE_IDS[raw] ?? ANNOTATION_TYPE_IDS[raw.replace(/[\s_]+/g, "-")];
+  if (typeId === undefined) return null;
+  return { typeId, typeLabel: ANNOTATION_TYPE_LABELS[typeId] };
+}
+
+function validTypeNames() {
+  return Object.keys(ANNOTATION_TYPE_IDS).join(", ");
+}
+
+function annotationTitleFor(typeLabel) {
+  return typeLabel
+    .split("-")
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+async function requirePrivateMember(flags, deps) {
+  const { withClient } = deps;
+  const client = await withClient(flags);
+  let memberInfo;
+  try {
+    memberInfo = await client.getMemberInfo();
+  } catch {
+    throw new Error(
+      "This command requires private authenticated mode. Login first with trainerroad-cli login.",
+    );
+  }
+  return { client, memberInfo };
+}
+
+async function annotationIdsOnCalendar(client, memberInfo) {
+  const timeline = await client.getTimeline(memberInfo.memberId, memberInfo.username);
+  const rows = Array.isArray(timeline?.annotations) ? timeline.annotations : [];
+  return new Set(rows.map((row) => String(row?.id)).filter((id) => id && id !== "undefined"));
+}
+
+export async function commandAnnotationDetails(flags, deps) {
+  const { isJsonMode, requireFlag, writeOutput } = deps;
+  const annotationId = String(requireFlag("annotation-details", flags, "id"));
+  const { client, memberInfo } = await requirePrivateMember(flags, deps);
+  const raw = await client.getAnnotation(annotationId, memberInfo.username);
+  const annotation = compactAnnotationDetail(raw);
+
+  const payload = {
+    generatedAt: new Date().toISOString(),
+    command: "annotation-details",
+    member: { memberId: memberInfo.memberId, username: memberInfo.username },
+    query: { annotationId },
+    annotation,
+    raw: flags.full ? raw : undefined,
+  };
+
+  if (!isJsonMode(flags)) {
+    await writeOutput(payload, flags, (value) => {
+      const a = value.annotation;
+      return [
+        `${a.typeLabel} ${a.dateOnly}..${a.endDateOnly} (${a.durationDays}d) | id=${a.id}`,
+        `title: ${a.title ?? "(none)"}`,
+        `notes: ${a.text ?? "(none)"}`,
+      ].join("\n");
+    });
+    return;
+  }
+  await writeOutput(payload, { ...flags, json: !flags.jsonl });
+}
+
+export async function commandAddAnnotation(flags, deps) {
+  const { isJsonMode, requireFlag, toBoolean, normalizeDateOnlyInput, requirePositiveInteger, writeOutput } = deps;
+  const dryRun = toBoolean(flags["dry-run"], false);
+  const type = resolveAnnotationType(requireFlag("add-annotation", flags, "type"));
+  if (!type) {
+    throw new Error(`Invalid --type "${flags.type}". Expected one of: ${validTypeNames()}, or a numeric typeId.`);
+  }
+  const date = normalizeDateOnlyInput(requireFlag("add-annotation", flags, "date"), null);
+  if (!date) throw new Error(`Invalid --date "${flags.date}". Expected YYYY-MM-DD.`);
+
+  let durationDays = requirePositiveInteger(flags.days, 1);
+  if (flags["end-date"] !== undefined && flags["end-date"] !== null && flags["end-date"] !== "") {
+    const endDate = normalizeDateOnlyInput(flags["end-date"], null);
+    if (!endDate) throw new Error(`Invalid --end-date "${flags["end-date"]}". Expected YYYY-MM-DD.`);
+    const diff = dateOnlyDiffDays(date, endDate);
+    if (diff === null || diff < 0) {
+      throw new Error(`--end-date ${endDate} is before --date ${date}.`);
+    }
+    durationDays = diff + 1;
+  }
+  const endDateOnly = shiftDateOnly(date, durationDays - 1);
+
+  const title = flags.title !== undefined && flags.title !== null && String(flags.title) !== ""
+    ? String(flags.title)
+    : annotationTitleFor(type.typeLabel);
+  const text = flags.notes !== undefined && flags.notes !== null ? String(flags.notes) : "";
+  const colorId = requirePositiveInteger(flags["color-id"], 2);
+
+  const request = {
+    date,
+    timeOfDay: null,
+    duration: durationDays * DAY_SECONDS,
+    title,
+    text,
+    typeId: type.typeId,
+    colorId,
+  };
+  const preview = {
+    typeId: type.typeId,
+    typeLabel: type.typeLabel,
+    dateOnly: date,
+    endDateOnly,
+    durationDays,
+    title,
+    text,
+    colorId,
+  };
+
+  const { client, memberInfo } = await requirePrivateMember(flags, deps);
+
+  const base = {
+    generatedAt: new Date().toISOString(),
+    command: "add-annotation",
+    member: { memberId: memberInfo.memberId, username: memberInfo.username },
+    query: preview,
+    adaptiveTraining: ADAPTIVE_NOTE,
+  };
+
+  if (dryRun) {
+    const payload = {
+      ...base,
+      dryRun: true,
+      annotation: null,
+      request,
+      message: `Would add ${type.typeLabel} "${title}" on ${date}${durationDays > 1 ? ` through ${endDateOnly}` : ""}.`,
+    };
+    if (!isJsonMode(flags)) {
+      await writeOutput(payload, flags, (value) => `${value.message}\nNo changes made.`);
+      return;
+    }
+    await writeOutput(payload, { ...flags, json: !flags.jsonl });
+    return;
+  }
+
+  const before = await annotationIdsOnCalendar(client, memberInfo);
+  await client.createAnnotation(request, memberInfo.username);
+  const after = await annotationIdsOnCalendar(client, memberInfo);
+  const createdIds = [...after].filter((id) => !before.has(id));
+
+  let annotation = null;
+  for (const id of createdIds) {
+    const detail = compactAnnotationDetail(await client.getAnnotation(id, memberInfo.username));
+    if (detail.typeId === type.typeId && detail.dateOnly === date) {
+      annotation = detail;
+      break;
+    }
+  }
+
+  const payload = {
+    ...base,
+    dryRun: false,
+    annotation,
+    request,
+    message: annotation
+      ? `Added ${annotation.typeLabel} "${annotation.title}" on ${annotation.dateOnly}${annotation.durationDays > 1 ? ` through ${annotation.endDateOnly}` : ""} (id=${annotation.id}).`
+      : "TrainerRoad accepted the annotation but it could not be located on the calendar afterwards. Run `annotations` to inspect.",
+  };
+
+  if (!isJsonMode(flags)) {
+    await writeOutput(payload, flags, (value) => `${value.message}\n${value.adaptiveTraining}`);
+    return;
+  }
+  await writeOutput(payload, { ...flags, json: !flags.jsonl });
+}
+
+export async function commandRemoveAnnotation(flags, deps) {
+  const { isJsonMode, requireFlag, toBoolean, writeOutput } = deps;
+  const dryRun = toBoolean(flags["dry-run"], false);
+  const annotationId = String(requireFlag("remove-annotation", flags, "id"));
+  const { client, memberInfo } = await requirePrivateMember(flags, deps);
+
+  let before = null;
+  try {
+    before = compactAnnotationDetail(await client.getAnnotation(annotationId, memberInfo.username));
+  } catch (error) {
+    if (!isHttpStatus(error, 404)) throw error;
+  }
+  const noop = before === null;
+
+  const base = {
+    generatedAt: new Date().toISOString(),
+    command: "remove-annotation",
+    member: { memberId: memberInfo.memberId, username: memberInfo.username },
+    query: { annotationId },
+    before,
+    adaptiveTraining: ADAPTIVE_NOTE,
+  };
+
+  if (dryRun || noop) {
+    const payload = {
+      ...base,
+      dryRun,
+      noop,
+      message: noop
+        ? `No annotation with id ${annotationId} exists on the calendar.`
+        : `Would remove ${before.typeLabel} "${before.title}" on ${before.dateOnly}.`,
+    };
+    if (!isJsonMode(flags)) {
+      await writeOutput(payload, flags, (value) => (value.noop ? value.message : `${value.message}\nNo changes made.`));
+      return;
+    }
+    await writeOutput(payload, { ...flags, json: !flags.jsonl });
+    return;
+  }
+
+  await client.deleteAnnotation(annotationId, memberInfo.username);
+  const payload = {
+    ...base,
+    dryRun: false,
+    noop: false,
+    message: `Removed ${before.typeLabel} "${before.title}" on ${before.dateOnly} (id=${annotationId}).`,
+  };
+
+  if (!isJsonMode(flags)) {
+    await writeOutput(payload, flags, (value) => `${value.message}\n${value.adaptiveTraining}`);
+    return;
+  }
+  await writeOutput(payload, { ...flags, json: !flags.jsonl });
+}

package/src/commands/event-mutations.mjs

@@ -0,0 +1,174 @@
+import { compactEventRecord } from "../lib/planning-normalizers.mjs";
+
+// Discipline ids from the web app's event picker (2026-09-02).
+export const EVENT_DISCIPLINES = {
+  "climbing-road-race": 0,
+  "rolling-road-race": 1,
+  "time-trial": 2,
+  criterium: 3,
+  "gran-fondo": 4,
+  cyclocross: 5,
+  "sprint-triathlon": 6,
+  "olympic-triathlon": 7,
+  "half-triathlon": 8,
+  "full-triathlon": 9,
+  "off-road-triathlon": 10,
+  "xc-olympic": 11,
+  "xc-marathon": 12,
+  "short-track": 13,
+  gravity: 14,
+  enduro: 15,
+  gravel: 16,
+};
+
+const RACE_PRIORITIES = { a: 3, b: 2, c: 1 };
+const STRESS_ESTIMATE_TSS = 1;
+const STRESS_ESTIMATE_INTENSITY = 2;
+
+const ADAPTIVE_NOTE =
+  "TrainerRoad builds and adapts the plan around A and B events, so adding one can reshape upcoming workouts. Re-read `future` afterwards.";
+
+function disciplineLabel(id) {
+  return Object.entries(EVENT_DISCIPLINES).find(([, value]) => value === id)?.[0] ?? `discipline-${id}`;
+}
+
+function resolveDiscipline(value) {
+  if (value === undefined || value === null || value === "") return null;
+  const raw = String(value).trim().toLowerCase();
+  if (/^\d+$/.test(raw)) {
+    const id = Number(raw);
+    return { id, label: disciplineLabel(id) };
+  }
+  const key = raw.replace(/[\s_]+/g, "-");
+  if (EVENT_DISCIPLINES[key] === undefined) return null;
+  return { id: EVENT_DISCIPLINES[key], label: key };
+}
+
+function resolvePriority(value) {
+  const raw = String(value ?? "b").trim().toLowerCase();
+  if (/^[123]$/.test(raw)) return Number(raw);
+  return RACE_PRIORITIES[raw] ?? null;
+}
+
+async function requirePrivateMember(flags, deps) {
+  const { withClient } = deps;
+  const client = await withClient(flags);
+  try {
+    const memberInfo = await client.getMemberInfo();
+    return { client, memberInfo };
+  } catch {
+    throw new Error(
+      "This command requires private authenticated mode. Login first with trainerroad-cli login.",
+    );
+  }
+}
+
+async function eventIdsOnCalendar(client, memberInfo) {
+  const timeline = await client.getTimeline(memberInfo.memberId, memberInfo.username);
+  const rows = Array.isArray(timeline?.events) ? timeline.events : [];
+  return new Map(rows.filter((row) => row?.id).map((row) => [String(row.id), row]));
+}
+
+export async function commandAddEvent(flags, deps) {
+  const { isJsonMode, requireFlag, toBoolean, normalizeDateOnlyInput, requirePositiveInteger, requireNumber, writeOutput } = deps;
+  const dryRun = toBoolean(flags["dry-run"], false);
+  const name = String(requireFlag("add-event", flags, "name"));
+  const date = normalizeDateOnlyInput(requireFlag("add-event", flags, "date"), null);
+  if (!date) throw new Error(`Invalid --date "${flags.date}". Expected YYYY-MM-DD.`);
+  const discipline = resolveDiscipline(requireFlag("add-event", flags, "discipline"));
+  if (!discipline) {
+    throw new Error(
+      `Invalid --discipline "${flags.discipline}". Expected one of: ${Object.keys(EVENT_DISCIPLINES).join(", ")}, or a numeric id.`,
+    );
+  }
+  const priority = resolvePriority(flags.priority);
+  if (priority === null) throw new Error(`Invalid --priority "${flags.priority}". Expected A, B, or C.`);
+  const durationMinutes = requirePositiveInteger(flags.duration, null);
+  if (!durationMinutes) throw new Error("--duration <minutes> is required for add-event.");
+
+  const tss = flags.tss !== undefined && flags.tss !== null && flags.tss !== "" ? requireNumber(flags.tss, null) : null;
+  const intensity =
+    flags.intensity !== undefined && flags.intensity !== null && flags.intensity !== ""
+      ? requireNumber(flags.intensity, null)
+      : null;
+  if (tss === null && intensity === null) {
+    throw new Error("add-event needs either --tss <number> or --intensity <1-10> so TrainerRoad can estimate the event's stress.");
+  }
+  const notes = flags.notes !== undefined && flags.notes !== null ? String(flags.notes) : "";
+
+  const request = {
+    customPlanId: null,
+    name,
+    date,
+    time: null,
+    discipline: discipline.id,
+    duration: durationMinutes * 60,
+    notes,
+    racePriority: priority,
+    stressEstimateType: tss !== null ? STRESS_ESTIMATE_TSS : STRESS_ESTIMATE_INTENSITY,
+    stressEstimateValue: tss !== null ? null : intensity,
+    tss: tss !== null ? tss : null,
+    manuallyCompleted: false,
+  };
+  const priorityLabel = Object.entries(RACE_PRIORITIES).find(([, value]) => value === priority)[0].toUpperCase();
+  const preview = {
+    name,
+    date,
+    discipline: discipline.label,
+    disciplineId: discipline.id,
+    priority: priorityLabel,
+    racePriority: priority,
+    durationMinutes,
+    tss,
+    intensity,
+    notes,
+  };
+
+  const { client, memberInfo } = await requirePrivateMember(flags, deps);
+  const base = {
+    generatedAt: new Date().toISOString(),
+    command: "add-event",
+    member: { memberId: memberInfo.memberId, username: memberInfo.username },
+    query: preview,
+    adaptiveTraining: ADAPTIVE_NOTE,
+  };
+
+  if (dryRun) {
+    const payload = {
+      ...base,
+      dryRun: true,
+      event: null,
+      request,
+      message: `Would add ${priorityLabel} event "${name}" (${discipline.label}) on ${date}.`,
+    };
+    if (!isJsonMode(flags)) {
+      await writeOutput(payload, flags, (value) => `${value.message}\nNo changes made.`);
+      return;
+    }
+    await writeOutput(payload, { ...flags, json: !flags.jsonl });
+    return;
+  }
+
+  const before = await eventIdsOnCalendar(client, memberInfo);
+  const response = await client.createEvent(request, memberInfo.username);
+  const after = await eventIdsOnCalendar(client, memberInfo);
+  const createdRow = [...after.entries()].find(([id]) => !before.has(id))?.[1] ?? null;
+  const event = createdRow ? compactEventRecord(createdRow) : null;
+
+  const payload = {
+    ...base,
+    dryRun: false,
+    event,
+    request,
+    response: flags.full ? response : undefined,
+    message: event
+      ? `Added ${priorityLabel} event "${event.name}" on ${event.dateOnly} (plannedActivityId=${event.id}). Remove it with remove-workout --id ${event.id}.`
+      : "TrainerRoad accepted the event but it could not be located on the calendar afterwards. Run `events` to inspect.",
+  };
+
+  if (!isJsonMode(flags)) {
+    await writeOutput(payload, flags, (value) => `${value.message}\n${value.adaptiveTraining}`);
+    return;
+  }
+  await writeOutput(payload, { ...flags, json: !flags.jsonl });
+}