incremnt 0.8.1 → 0.8.3

package/src/queries.js

@@ -2763,6 +2763,128 @@ export function getWeeklyVolume(snapshot, { today = new Date() } = {}) {
   });
 }
 
+// Light muscle-label normalizer: keys synonymous groups together without pulling
+// in the sync-service movement-family map (CLI stays self-contained). Display
+// label is the canonical group name.
+function normalizeMuscleLabel(raw) {
+  const text = String(raw ?? '').trim().toLowerCase().replace(/[-_]/g, ' ').replace(/\s+/g, ' ');
+  if (text === '') return { key: 'unattributed', label: 'Unattributed' };
+  const synonyms = {
+    delts: 'shoulders', delt: 'shoulders', shoulder: 'shoulders',
+    quad: 'quads', quadriceps: 'quads',
+    ham: 'hamstrings', hams: 'hamstrings', hamstring: 'hamstrings',
+    glute: 'glutes', calf: 'calves', tricep: 'triceps', bicep: 'biceps',
+    lat: 'lats', ab: 'abs', abdominals: 'abs', core: 'abs'
+  };
+  const key = synonyms[text] ?? text;
+  const label = key.charAt(0).toUpperCase() + key.slice(1);
+  return { key, label };
+}
+
+function isoWeekStartOffset(weekStart, weeksBack) {
+  const ms = new Date(`${weekStart}T00:00:00.000Z`).getTime() - weeksBack * 7 * 24 * 60 * 60 * 1000;
+  return new Date(ms).toISOString().slice(0, 10);
+}
+
+function isoDateOffset(isoDate, days) {
+  const ms = new Date(`${isoDate}T00:00:00.000Z`).getTime() + days * 24 * 60 * 60 * 1000;
+  return new Date(ms).toISOString().slice(0, 10);
+}
+
+// Per-muscle strength volume (weight×reps over completed working sets) for the
+// last N ISO weeks, plus each muscle's share of that week's total. Answers
+// "volume per muscle relative to previous weeks' overall volume". Computed from
+// raw sessions so it reflects actual logged load, not sets-vs-target.
+export function getMuscleVolumeTrend(snapshot, { today = new Date(), weeks = 4 } = {}) {
+  const todayIso = dateOnlyString(today);
+  const currentWeekStart = startOfCurrentIsoWeek(today);
+  const boundedWeeks = Math.max(1, Math.min(12, Math.round(Number(weeks) || 4)));
+
+  // Oldest -> newest so downstream arrays read chronologically.
+  const weekStarts = [];
+  for (let i = boundedWeeks - 1; i >= 0; i -= 1) {
+    weekStarts.push(isoWeekStartOffset(currentWeekStart, i));
+  }
+
+  const sourceIds = [];
+  const sourceDates = [];
+  const muscleAccum = new Map(); // key -> { label, weeklyVolume: number[] }
+  const weeklyTotals = weekStarts.map(() => 0);
+
+  weekStarts.forEach((weekStart, weekIndex) => {
+    const isCurrent = weekStart === currentWeekStart;
+    const weekEnd = isCurrent ? todayIso : isoDateOffset(weekStart, 6);
+    const sessions = sessionsInDateRange(snapshot, weekStart, weekEnd);
+    for (const session of sessions) {
+      let contributed = false;
+      for (const exercise of session.exercises ?? []) {
+        const { key, label } = normalizeMuscleLabel(exercise.muscleGroup);
+        const volume = completedWorkingSets(exercise.sets).reduce((sum, set) => sum + set.volume, 0);
+        if (volume <= 0) continue;
+        if (!muscleAccum.has(key)) {
+          muscleAccum.set(key, { label, weeklyVolume: weekStarts.map(() => 0) });
+        }
+        muscleAccum.get(key).weeklyVolume[weekIndex] += volume;
+        weeklyTotals[weekIndex] += volume;
+        contributed = true;
+      }
+      if (contributed) {
+        if (session.id) sourceIds.push(session.id);
+        sourceDates.push(completionDateForSession(session));
+      }
+    }
+  });
+
+  const latestIndex = boundedWeeks - 1;
+  const priorIndices = weekStarts.map((_, i) => i).filter((i) => i !== latestIndex);
+  const muscles = [...muscleAccum.values()].map(({ label, weeklyVolume }) => {
+    const rounded = weeklyVolume.map((value) => Math.round(value));
+    const latestVolume = rounded[latestIndex];
+    const latestTotal = weeklyTotals[latestIndex];
+    const priorVolumes = priorIndices.map((i) => weeklyVolume[i]);
+    const priorAvg = priorVolumes.length > 0
+      ? priorVolumes.reduce((sum, value) => sum + value, 0) / priorVolumes.length
+      : 0;
+    const sharePct = (volume, total) => (total > 0 ? Math.round((volume / total) * 100) : 0);
+    return {
+      muscle: label,
+      weeklyVolume: rounded,
+      latestVolume,
+      latestSharePct: sharePct(weeklyVolume[latestIndex], latestTotal),
+      priorAvgVolume: Math.round(priorAvg),
+      deltaVsPriorAvgPct: priorAvg > 0 ? Math.round(((weeklyVolume[latestIndex] - priorAvg) / priorAvg) * 100) : null
+    };
+  }).sort((a, b) => b.latestVolume - a.latestVolume);
+
+  const rows = muscles.flatMap((row) => weekStarts.map((weekStart, i) => ({
+    week: weekStart,
+    muscle: row.muscle,
+    volume: row.weeklyVolume[i],
+    sharePct: weeklyTotals[i] > 0 ? Math.round((row.weeklyVolume[i] / weeklyTotals[i]) * 100) : 0
+  })));
+
+  const missingDataFlags = [];
+  if (muscles.length === 0) missingDataFlags.push('no_muscle_volume_in_window');
+  if (muscleAccum.has('unattributed')) missingDataFlags.push('some_volume_unattributed_to_muscle');
+
+  return coachToolResult('get_muscle_volume_trend', {
+    today: todayIso,
+    weeks: boundedWeeks,
+    weekStarts
+  }, {
+    rows,
+    facts: {
+      weekStarts,
+      weeklyTotals: weeklyTotals.map((value) => Math.round(value)),
+      muscleCount: muscles.length,
+      muscles
+    },
+    sourceIds,
+    sourceTimestamp: latestSourceTimestampFromDates(sourceDates),
+    missingDataFlags
+  });
+}
+
 export function getRecentSessions(snapshot, { limit = 3, today = new Date(), recencyCutoffDays = 14, includeStale = true } = {}) {
   const sortedSessions = sortedSessionsNewestFirst(snapshot);
   const rows = sortedSessions.map((session) => {
@@ -3051,9 +3173,11 @@ export function getBodyWeightSnapshot(snapshot, { recentDays = 30, exclude = new
 
   const profileWeightKg = Number(snapshot.user?.weightKg);
   const resolvedProfileWeightKg = Number.isFinite(profileWeightKg) && profileWeightKg > 0
-    ? Math.round(profileWeightKg * 10) / 10
+      ? Math.round(profileWeightKg * 10) / 10
     : null;
   const cutoff = relativeDateString(today, -recentDays);
+  const sevenDayCutoff = relativeDateString(today, -7);
+  const thirtyDayCutoff = relativeDateString(today, -30);
   const bodyWeightRows = (snapshot.healthMetrics?.bodyWeight ?? [])
     .filter((entry) => entry?.date && Number.isFinite(Number(entry.value ?? entry.weight)))
     .map((entry) => ({
@@ -3067,13 +3191,34 @@ export function getBodyWeightSnapshot(snapshot, { recentDays = 30, exclude = new
   const trendKg = latest && earliestRecent && recentRows.length >= 2
     ? Math.round((latest.weightKg - earliestRecent.weightKg) * 10) / 10
     : null;
+  const averageWeightKg = (rows) => {
+    if (!rows.length) return null;
+    return Math.round((rows.reduce((sum, row) => sum + row.weightKg, 0) / rows.length) * 10) / 10;
+  };
+  const trendDirection = trendKg == null
+    ? null
+    : trendKg > 0.1
+      ? 'rising'
+      : trendKg < -0.1
+        ? 'falling'
+        : 'flat';
+  const sevenDayRows = bodyWeightRows.filter((entry) => entry.date >= sevenDayCutoff);
+  const thirtyDayRows = bodyWeightRows.filter((entry) => entry.date >= thirtyDayCutoff);
   const facts = {
     recentDays,
     profileWeightKg: resolvedProfileWeightKg,
     latestBodyWeightKg: latest?.weightKg ?? resolvedProfileWeightKg,
     latestBodyWeightDate: latest?.date ?? null,
     readingCount: recentRows.length,
-    trendKg
+    trendKg,
+    trendDirection,
+    average7DayBodyWeightKg: averageWeightKg(sevenDayRows),
+    average30DayBodyWeightKg: averageWeightKg(thirtyDayRows),
+    earliestRecentBodyWeightKg: earliestRecent?.weightKg ?? null,
+    earliestRecentBodyWeightDate: earliestRecent?.date ?? null,
+    latestRecentBodyWeightKg: recentRows.at(-1)?.weightKg ?? null,
+    latestRecentBodyWeightDate: recentRows.at(-1)?.date ?? null,
+    sampleWindowDays: recentDays
   };
   const missingDataFlags = [];
   if (facts.latestBodyWeightKg == null) missingDataFlags.push('no_body_weight');
@@ -3111,9 +3256,30 @@ export function getGoalStatus(snapshot, { limit = 5 } = {}) {
   });
 }
 
+function round1(value) {
+  return Math.round(value * 10) / 10;
+}
+
+function priorBestSetBefore(sets, recordDateIso) {
+  let prior = null;
+  for (const set of sets) {
+    const setDate = normalizeDateOnly(set.date);
+    if (setDate == null || recordDateIso == null || setDate >= recordDateIso) continue;
+    if (!prior || set.e1rm > prior.e1rm) prior = set;
+  }
+  return prior;
+}
+
+function classifyRecordKind(record, priorBest) {
+  if (!priorBest) return 'first';
+  // A PR achieved by adding reps at the same (or even lower) load reads as a
+  // stall to anything reasoning on bar weight, so distinguish it explicitly.
+  return record.weight > priorBest.weight ? 'load_pr' : 'rep_pr';
+}
+
 export function getRecords(snapshot, { exercises = [], limit = 15, recentSince = null, today = new Date() } = {}) {
   const filter = exercises.length > 0 ? new Set(exercises.map((exercise) => exercise.canonical ?? canonicalExerciseName(exercise))) : null;
-  const bestByExercise = new Map();
+  const setsByExercise = new Map();
   for (const session of snapshot.sessions ?? []) {
     for (const exercise of session.exercises ?? []) {
       const key = canonicalExerciseName(exercise.name);
@@ -3121,27 +3287,85 @@ export function getRecords(snapshot, { exercises = [], limit = 15, recentSince =
       for (const set of exercise.sets ?? []) {
         if (!set.isComplete) continue;
         const e1rm = Number(set.weight) * (1 + Number(set.reps) / 30);
-        const current = bestByExercise.get(key);
-        if (!current || e1rm > current.e1rm) {
-          bestByExercise.set(key, {
-            name: exercise.name,
-            e1rm,
-            date: completionDateForSession(session),
-            sessionId: session.id ?? null
-          });
+        if (!(e1rm > 0)) continue;
+        let entry = setsByExercise.get(key);
+        if (!entry) {
+          entry = { sets: [] };
+          setsByExercise.set(key, entry);
         }
+        entry.sets.push({
+          name: exercise.name,
+          e1rm,
+          weight: Number(set.weight),
+          reps: Number(set.reps),
+          date: completionDateForSession(session),
+          sessionId: session.id ?? null
+        });
       }
     }
   }
-  const allRows = [...bestByExercise.values()]
-    .filter((record) => record.e1rm > 0)
+
+  const records = [];
+  for (const entry of setsByExercise.values()) {
+    let best = null;
+    for (const set of entry.sets) {
+      // Strictly greater keeps the earliest set that reached the best e1RM.
+      if (!best || set.e1rm > best.e1rm) best = set;
+    }
+    if (!best) continue;
+    records.push({
+      name: best.name,
+      e1rm: best.e1rm,
+      weight: best.weight,
+      reps: best.reps,
+      date: best.date,
+      sessionId: best.sessionId,
+      sets: entry.sets
+    });
+  }
+
+  const allRows = records
+    .map((record) => ({
+      name: record.name,
+      e1rm: record.e1rm,
+      weight: record.weight,
+      reps: record.reps,
+      date: record.date,
+      sessionId: record.sessionId
+    }))
     .sort((a, b) => b.e1rm - a.e1rm);
+
   const todayIso = dateOnlyString(today);
-  const recentRecords = recentSince
-    ? allRows.filter((record) => {
-      const recordDate = normalizeDateOnly(record.date);
-      return recordDate != null && recordDate >= recentSince && recordDate <= todayIso;
-    })
+  const recentSinceIso = recentSince ? normalizeDateOnly(recentSince) : null;
+  const recentRecords = recentSinceIso
+    ? records
+      .filter((record) => {
+        const recordDate = normalizeDateOnly(record.date);
+        return recordDate != null && recordDate >= recentSinceIso && recordDate <= todayIso;
+      })
+      .sort((a, b) => b.e1rm - a.e1rm)
+      .map((record) => {
+        const recordDateIso = normalizeDateOnly(record.date);
+        const priorBest = priorBestSetBefore(record.sets, recordDateIso);
+        const delta = priorBest ? round1(record.e1rm - priorBest.e1rm) : null;
+        const deltaPct = priorBest && priorBest.e1rm > 0
+          ? round1(((record.e1rm - priorBest.e1rm) / priorBest.e1rm) * 100)
+          : null;
+        return {
+          name: record.name,
+          e1rm: record.e1rm,
+          weight: record.weight,
+          reps: record.reps,
+          date: record.date,
+          sessionId: record.sessionId,
+          priorBest: priorBest
+            ? { e1rm: priorBest.e1rm, weight: priorBest.weight, reps: priorBest.reps, date: priorBest.date }
+            : null,
+          delta,
+          deltaPct,
+          kind: classifyRecordKind(record, priorBest)
+        };
+      })
     : [];
   const rows = allRows.slice(0, limit);
 
@@ -3156,7 +3380,8 @@ export function getRecords(snapshot, { exercises = [], limit = 15, recentSince =
       recordCount: rows.length,
       totalRecordCount: allRows.length,
       recentRecordCount: recentRecords.length,
-      recentRecordNames: recentRecords.map((record) => record.name)
+      recentRecordNames: recentRecords.map((record) => record.name),
+      recentRecords
     },
     sourceIds: rows.map((row) => row.sessionId),
     sourceTimestamp: latestSourceTimestampFromDates(rows.map((row) => row.date)),
@@ -3484,6 +3709,201 @@ export function getTrainingProfile(snapshot, { since = null, today = new Date()
   });
 }
 
+function normalizeExcludeSet(exclude) {
+  if (exclude instanceof Set) return new Set([...exclude].map((item) => String(item)));
+  return new Set(Array.isArray(exclude) ? exclude.map((item) => String(item)) : []);
+}
+
+function compactRecordRow(row) {
+  if (!row) return null;
+  return {
+    exercise: row.name ?? null,
+    e1rm: round1(Number(row.e1rm ?? 0)),
+    weight: Number(row.weight ?? 0),
+    reps: Number(row.reps ?? 0),
+    date: dateOnlyString(row.date),
+    sessionId: row.sessionId ?? null
+  };
+}
+
+function compactRecentRecord(record) {
+  const base = compactRecordRow(record);
+  if (!base) return null;
+  return {
+    ...base,
+    delta: record.delta ?? null,
+    deltaPct: record.deltaPct ?? null,
+    kind: record.kind ?? null
+  };
+}
+
+function compactSessionHighlights(row, limit = 2) {
+  return (row.exercises ?? [])
+    .map((exercise) => {
+      const topSet = exercise.topSet ?? null;
+      if (!topSet) return null;
+      const weight = Number(topSet.weight ?? 0);
+      const reps = Number(topSet.reps ?? 0);
+      if (!(reps > 0)) return null;
+      return {
+        exercise: exercise.name ?? null,
+        weight,
+        reps,
+        e1rm: weight > 0 ? round1(estimateE1RM(weight, reps)) : null
+      };
+    })
+    .filter(Boolean)
+    .slice(0, limit);
+}
+
+function compactSessionRow(row) {
+  return {
+    date: row.date ?? null,
+    label: row.label ?? 'Workout',
+    volume: Math.round(Number(row.volume ?? 0)),
+    highlights: compactSessionHighlights(row)
+  };
+}
+
+function compactReadinessFacts(readinessFacts, load) {
+  return {
+    status: load?.status ?? null,
+    loadReadiness: load?.readiness?.band ?? load?.readiness?.status ?? null,
+    loadRatio: load?.readiness?.loadRatio ?? null,
+    last7DayLoad: load?.last7Days?.totalLoad ?? null,
+    last28DayLoad: load?.last28Days?.totalLoad ?? null,
+    hrv: readinessFacts.latestHRV?.value ?? null,
+    hrvDelta: readinessFacts.hrvDelta ?? null,
+    restingHR: readinessFacts.latestRestingHR?.value ?? null,
+    restingHRDelta: readinessFacts.restingHRDelta ?? null,
+    sleepHrs: readinessFacts.latestSleep?.value ?? null,
+    sleepDelta: readinessFacts.sleepDelta ?? null
+  };
+}
+
+export function getAthleteSnapshot(snapshot, { today = new Date(), windowDays = 35, exclude = [] } = {}) {
+  const asOf = dateOnlyString(today);
+  const boundedWindowDays = boundedInteger(windowDays, { defaultValue: 35, min: 1, max: 365 });
+  const since = relativeDateString(asOf, -boundedWindowDays);
+  const excluded = normalizeExcludeSet(exclude);
+  const profile = getTrainingProfile(snapshot, { since, today: asOf });
+  const sourceIds = [...profile.sourceIds];
+  const sourceTimestamps = [profile.sourceTimestamp];
+  const missingDataFlags = [...profile.missingDataFlags];
+  const facts = {
+    asOf,
+    windowDays: boundedWindowDays,
+    profile: {
+      program: profile.facts.currentProgram?.name ?? null,
+      programId: profile.facts.currentProgram?.id ?? null,
+      daysPerWeek: profile.facts.currentProgram?.daysPerWeek ?? null,
+      trainingWeekdays: profile.facts.trainingWeekdays ?? [],
+      loggedSessionCount: profile.facts.loggedSessionCount ?? 0,
+      trainedExerciseCount: profile.facts.trainedExerciseCount ?? 0,
+      completedCycles: profile.facts.currentProgram?.completedCyclesCount ?? 0
+    }
+  };
+
+  if (!excluded.has('score')) {
+    const score = getIncrementScore(snapshot, { historyDays: Math.min(boundedWindowDays, 60) });
+    facts.score = Object.keys(score.facts ?? {}).length > 0 ? {
+      value: score.facts.score ?? null,
+      band: score.facts.scoreBand ?? null,
+      dayOverDayDelta: score.facts.dayOverDayDelta ?? null,
+      positiveDrivers: score.facts.topPositiveDrivers ?? [],
+      negativeDrivers: score.facts.topNegativeDrivers ?? []
+    } : null;
+    sourceIds.push(...score.sourceIds);
+    sourceTimestamps.push(score.sourceTimestamp);
+    missingDataFlags.push(...score.missingDataFlags);
+  }
+
+  if (!excluded.has('volume')) {
+    const volume = getWeeklyVolume(snapshot, { today: asOf });
+    facts.volume = {
+      currentWeek: volume.facts.currentWeekVolume ?? 0,
+      currentWeekSessions: volume.facts.currentWeekSessionCount ?? 0,
+      previousWeek: volume.facts.previousWeekVolume ?? 0,
+      previousWeekSessions: volume.facts.previousWeekSessionCount ?? 0,
+      deltaPct: volume.facts.deltaPct ?? null
+    };
+    sourceIds.push(...volume.sourceIds);
+    sourceTimestamps.push(volume.sourceTimestamp);
+    missingDataFlags.push(...volume.missingDataFlags);
+  }
+
+  if (!excluded.has('muscleVolume')) {
+    const trendWeeks = Math.max(2, Math.min(5, Math.round(boundedWindowDays / 7)));
+    const muscleTrend = getMuscleVolumeTrend(snapshot, { today: asOf, weeks: trendWeeks });
+    facts.muscleVolume = {
+      weekStarts: muscleTrend.facts.weekStarts,
+      weeklyTotals: muscleTrend.facts.weeklyTotals,
+      muscles: (muscleTrend.facts.muscles ?? []).slice(0, 6).map((row) => ({
+        muscle: row.muscle,
+        weeklyVolume: row.weeklyVolume,
+        latestSharePct: row.latestSharePct,
+        deltaVsPriorAvgPct: row.deltaVsPriorAvgPct
+      }))
+    };
+    sourceIds.push(...muscleTrend.sourceIds);
+    sourceTimestamps.push(muscleTrend.sourceTimestamp);
+    missingDataFlags.push(...muscleTrend.missingDataFlags);
+  }
+
+  if (!excluded.has('recovery')) {
+    const readiness = getReadinessSnapshot(snapshot, {
+      recentDays: Math.min(boundedWindowDays, 60),
+      today: asOf
+    });
+    const load = trainingLoad(snapshot);
+    facts.readiness = compactReadinessFacts(readiness.facts, load);
+    sourceIds.push(...readiness.sourceIds);
+    sourceTimestamps.push(readiness.sourceTimestamp, load?.asOf);
+    missingDataFlags.push(...readiness.missingDataFlags);
+  }
+
+  if (!excluded.has('records')) {
+    const records = getRecords(snapshot, { limit: 6, recentSince: since, today: asOf });
+    facts.records = {
+      topPRs: records.rows.map(compactRecordRow).filter(Boolean).slice(0, 6),
+      recentRecords: (records.facts.recentRecords ?? []).map(compactRecentRecord).filter(Boolean).slice(0, 5)
+    };
+    sourceIds.push(...records.sourceIds);
+    sourceTimestamps.push(records.sourceTimestamp);
+    missingDataFlags.push(...records.missingDataFlags);
+  }
+
+  const recentSessions = getRecentSessions(snapshot, {
+    limit: 4,
+    today: asOf,
+    recencyCutoffDays: boundedWindowDays,
+    includeStale: false
+  });
+  facts.recentSessions = recentSessions.rows.map(compactSessionRow).slice(0, 4);
+  sourceIds.push(...recentSessions.sourceIds);
+  sourceTimestamps.push(recentSessions.sourceTimestamp);
+  missingDataFlags.push(...recentSessions.missingDataFlags);
+
+  if (!excluded.has('notes')) {
+    facts.notes = (profile.facts.recentNotes ?? []).map((note) => ({
+      date: note.date ?? null,
+      text: note.note ?? ''
+    })).slice(0, 5);
+  }
+
+  return coachToolResult('get_athlete_snapshot', {
+    today: asOf,
+    windowDays: boundedWindowDays,
+    exclude: [...excluded]
+  }, {
+    rows: [],
+    facts,
+    sourceIds,
+    sourceTimestamp: latestSourceTimestamp(sourceTimestamps),
+    missingDataFlags
+  });
+}
+
 function scoreComponentNumber(value) {
   const num = typeof value === 'number' ? value : value?.score;
   return typeof num === 'number' && Number.isFinite(num) ? num : null;
@@ -3543,7 +3963,15 @@ export function incrementScoreSummary(snapshot, { historyDays = 14 } = {}) {
 
   const trimmedHistory = history.slice(0, boundedHistoryDays);
   const prior = trimmedHistory[1];
-  const dayOverDayDelta = (typeof prior?.score === 'number')
+  // Scores are only comparable within the same formula version. The Increment
+  // Score formula changed mid-2026 (it started counting recovery data it did not
+  // have before), so subtracting an older-formula score from a newer one is the
+  // "+36 / 77% up" cross-ruler artifact. Null the delta across a formula change
+  // so downstream voice cannot frame a non-comparable jump as real progress.
+  const latestFormulaVersion = latest.formulaVersion ?? null;
+  const dayOverDayComparable = (typeof prior?.score === 'number')
+    && (prior.formulaVersion ?? null) === latestFormulaVersion;
+  const dayOverDayDelta = dayOverDayComparable
     ? latest.score - prior.score
     : null;
 
@@ -3570,6 +3998,11 @@ export function incrementScoreSummary(snapshot, { historyDays = 14 } = {}) {
       dataTier: entry.dataTier ?? null,
       formulaVersion: entry.formulaVersion ?? null
     }));
+  // A multi-day trend is only meaningful if every point shares the latest
+  // formula version; otherwise the "rising/falling" steer mixes rulers.
+  const trendComparable = recentTrend.every(
+    (entry) => (entry.formulaVersion ?? null) === latestFormulaVersion
+  );
 
   return {
     available: true,
@@ -3581,6 +4014,8 @@ export function incrementScoreSummary(snapshot, { historyDays = 14 } = {}) {
     topPositiveDrivers: scoreDriverLabels(latest.topPositiveDrivers),
     topNegativeDrivers: scoreDriverLabels(latest.topNegativeDrivers),
     dayOverDayDelta,
+    dayOverDayComparable,
+    trendComparable,
     recentTrend,
     dataQualityNotes,
     missingDataFlags,
@@ -3961,7 +4396,7 @@ export const COACH_READ_TOOL_SCHEMAS = Object.freeze({
     outputSchema: COACH_TOOL_RESULT_SCHEMA
   }),
   get_body_weight_snapshot: Object.freeze({
-    description: 'Read the user profile body weight and recent HealthKit body-mass readings when body weight sharing is enabled.',
+    description: 'Read profile body weight plus recent HealthKit body-mass readings, compact trend facts, and chartable rows when body weight sharing is enabled.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -4089,6 +4524,35 @@ export const COACH_READ_TOOL_SCHEMAS = Object.freeze({
     },
     outputSchema: COACH_TOOL_RESULT_SCHEMA
   }),
+  get_athlete_snapshot: Object.freeze({
+    description: 'Read a compact athlete-state snapshot for Coach curation: profile, score, volume, readiness, records, recent sessions, and notes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        today: { type: 'string', format: 'date', description: 'Optional anchor date; defaults to today.' },
+        windowDays: { type: 'integer', minimum: 1, maximum: 365, default: 35 },
+        exclude: {
+          type: 'array',
+          items: { type: 'string', enum: ['recovery', 'records', 'notes', 'score', 'volume', 'muscleVolume'] },
+          default: []
+        }
+      },
+      additionalProperties: false
+    },
+    outputSchema: COACH_TOOL_RESULT_SCHEMA
+  }),
+  get_muscle_volume_trend: Object.freeze({
+    description: 'Per-muscle strength volume (weight×reps) per ISO week for the last N weeks, with each muscle\'s share of weekly total.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        today: { type: 'string', format: 'date', description: 'Optional anchor date; defaults to today.' },
+        weeks: { type: 'integer', minimum: 1, maximum: 12, default: 4 }
+      },
+      additionalProperties: false
+    },
+    outputSchema: COACH_TOOL_RESULT_SCHEMA
+  }),
   get_cycle_progression_summary: Object.freeze({
     description: 'Summarize completed cycle progression counts and adherence.',
     inputSchema: {
@@ -4244,6 +4708,19 @@ function normalizeCoachToolInput(toolName, input = {}) {
       today: normalizedToolDateOnly(source.today)
     };
   }
+  if (toolName === 'get_athlete_snapshot') {
+    return {
+      today: normalizedToolDateOnly(source.today),
+      windowDays: boundedInteger(source.windowDays, { defaultValue: 35, min: 1, max: 365 }),
+      exclude: Array.isArray(source.exclude) ? source.exclude.map((item) => String(item)) : []
+    };
+  }
+  if (toolName === 'get_muscle_volume_trend') {
+    return {
+      today: normalizedToolDateOnly(source.today),
+      weeks: boundedInteger(source.weeks, { defaultValue: 4, min: 1, max: 12 })
+    };
+  }
   if (toolName === 'get_cycle_progression_summary') {
     return {
       programId: source.programId ? String(source.programId) : null,
@@ -4289,6 +4766,8 @@ export function executeCoachReadTool(snapshot, toolName, input = {}) {
   if (toolName === 'get_exercise_progress_summary') return getExerciseProgressSummary(snapshot, params);
   if (toolName === 'get_program_progress') return getProgramProgress(snapshot, params);
   if (toolName === 'get_training_profile') return getTrainingProfile(snapshot, params);
+  if (toolName === 'get_athlete_snapshot') return getAthleteSnapshot(snapshot, params);
+  if (toolName === 'get_muscle_volume_trend') return getMuscleVolumeTrend(snapshot, params);
   if (toolName === 'get_cycle_progression_summary') return getCycleProgressionSummary(snapshot, params);
   if (toolName === 'get_current_coach_observations') return getCurrentCoachObservations(snapshot, params);
   if (toolName === 'compare_session_to_observations') return compareSessionToObservations(snapshot, params);