@trainheroic-unofficial/cli 0.1.0 → 0.2.0

package/skill/trainheroic-unofficial/references/data-warehouse.md

@@ -0,0 +1,127 @@
+# Warehouse store (design reference)
+
+> **Note.** This documents the warehouse _design_ — the exercise mirror plus the
+> programming/messaging history zones, the prune-vs-accumulate rule, `source`
+> provenance, and the per-calendar month-window walk. That warehouse now lives in the
+> hosted MCP server (`@trainheroic-unofficial/cloudflare`, D1). The CLI and the local
+> server cache only the exercise library, to JSON at `~/.trainheroic/library.json`.
+> The SQLite / `library_cache.py` / `*_sync.py` names below are historical; the schema
+> and sync rules still apply to the hosted zones.
+
+`library_cache.py` manages a SQLite database at `~/.trainheroic/library.db`
+(mode 0600, outside any repo). It is both a read-through cache for exercise
+lookups and a durable local store any future tool can open and query directly.
+Stdlib `sqlite3` only — no dependencies.
+
+Import it as a module (`from library_cache import ExerciseCache`) or use the CLI:
+
+```bash
+library_cache.py resolve "<name>"   # name -> exercise (exit 3 + candidates if ambiguous)
+library_cache.py search  "<query>"  # ranked FTS search
+library_cache.py get <id>           # one exercise as JSON
+library_cache.py sync [--force]     # refresh the reference mirror from the API
+library_cache.py stats              # row counts per zone + cursors
+library_cache.py cursors            # the sync_state watermark table
+library_cache.py create '<json>'    # create a custom exercise (API) + write-through
+library_cache.py forget <id>        # drop an exercise from the mirror (cache-only)
+```
+
+Programming history and messages are synced by separate scripts:
+
+```bash
+programming_sync.py            # pull every calendar into the programming zone
+programming_sync.py <cal_id>   # one calendar/program id
+messaging_sync.py              # pull every chat stream into the messaging zone
+messaging_sync.py --full       # re-pull every stream from the beginning
+messaging_sync.py <stream_id>  # one stream id
+```
+
+## Zones
+
+The DB holds three zones that follow deliberately different rules. The split is
+load-bearing: applying the reference zone's prune logic to records would silently
+delete history on a short fetch window.
+
+### Reference zone — implemented
+
+`exercise`, `tag`, `exercise_tag`, `swap`, `exercise_fts` (FTS5 over titles).
+
+- Sourced from `GET /v5/exerciseLibrary/all` plus the tag endpoints.
+- **Read-through with a 7-day TTL.** `ensure_fresh()` backfills when the DB is
+  empty or stale; a `resolve` miss forces one refresh and retries (catches
+  exercises added through the web UI out of band).
+- **Prune-to-match.** Each full sync bumps a generation counter; rows the API no
+  longer returns are deleted — but only when the response has at least
+  `PRUNE_FLOOR` (100) rows, so a thin/garbled response never wipes the mirror.
+- **Write-through hooks** `record_upsert(ex)` / `record_delete(id)` keep the
+  mirror correct after a create/update/delete without a full re-sync.
+- IDs follow the API's own integers (Back Squat = 1, Bench Press = 1162);
+  id-less entries are skipped (this is the ~2384 → 2371 gap).
+
+### Programming zone — implemented
+
+`program`, `program_session`, `block`, `prescribed_set`, populated by
+`programming_sync.py`.
+
+- **Calendars to pull** = the union of `/1.0/coach/programs` (standalone) and each
+  team's `group_program` from `/1.0/coach/teams`.
+- **Sourced from `GET /1.0/coach/programs/edit/{cal}/{y}/{m}/1`**, walked month by
+  month across a window (`MONTHS_BACK`/`MONTHS_FWD`): that endpoint returns only
+  the queried month's sessions, not the whole calendar.
+- **Accumulate-only** — never pruned, so it retains history even after a session
+  is deleted on TrainHeroic. Each sync upserts every session and rebuilds that
+  session's own blocks/sets (delete + re-insert) to absorb edits, then advances
+  `sync_state('programming', <cal_id>)`. Re-running is idempotent.
+- `prescribed_set` holds one row per prescribed set (the API's `param_N_data_1..10`
+  slots expanded). `prescribed_set.exercise_id` is a **soft** join to
+  `exercise(id)` — not an enforced FK, since the library cache may lag custom
+  exercises and a sync must not fail on a cache miss.
+
+### Messaging zone — implemented
+
+`message_stream`, `message_comment`, populated by `messaging_sync.py`.
+
+- **Conversations** from `GET /v5/messaging/streams` (buckets `teams`, `athletes`,
+  `programs`, `coaches`). Each entry's `id` is the **stream id** — distinct from
+  `teamId`/`userId` and what every other messaging call keys on; `message_stream`
+  records `kind`, `team_id`, `user_id`, `last_viewed`.
+- **Messages** from `GET /v5/messaging/streams/{id}/comments?lastCommentId={cursor}`,
+  walked incrementally: the cursor is the highest comment id stored, written to
+  `sync_state('messaging', stream_id)`, so a normal run only pulls newer comments.
+  `--full` passes a blank cursor to re-pull a whole stream (the only way to refresh
+  reactions/replies on already-synced comments, since the incremental call returns
+  newer-than-cursor only).
+- **Accumulate-only** — comments are upserted by id and never pruned, so a message
+  soft-deleted on TrainHeroic is retained here as history (same rule as programming).
+- `message_comment.is_author` is `0` for received messages, `1` for ones this coach
+  sent. `parent_id` holds a reply's parent comment id (threaded `replies[]` are
+  flattened into rows); `reactions` keeps the API's array as JSON.
+- `message_send.py send` write-throughs the created comment so the store stays
+  correct without a re-sync; the next `messaging_sync.py` then advances the cursor.
+
+## `sync_state` — incremental watermarks
+
+One row per `(resource, scope_id)` — `scope_id` is an athlete/program id, or 0
+for global. Columns: `cursor` (ISO date / high-water mark), `synced_at`,
+`generation` (set only for prune-to-match zones). The library sync writes a
+`library` cursor. Any new incremental sync must record its watermark here, not in
+`sync_meta` (which holds only the library TTL timestamp and generation counter).
+
+## Conventions for extending the store
+
+- **Source tagging.** Every records table has `source` (default `'api'`). Write
+  synthetic/test rows with `source='seed'` so production queries can filter them
+  and a re-seed can delete only its own rows.
+- **Pick the right zone rule.** Reference-style catalogs may prune-to-match;
+  anything historical must accumulate.
+
+## Known limitations
+
+- **No API write path for performance history.** Logged sets, readiness, and
+  working-max data are produced by the athlete mobile app; they are not creatable
+  or (as far as is known) syncable through this coach API. That is why
+  there is no performance zone here.
+- **Units are per-athlete.** Weights live in each athlete's own unit (metric vs.
+  imperial). Normalize before any cross-athlete analytics.
+- **`swaps` is empty from the bulk endpoint** — it likely only appears on
+  per-exercise detail or create responses.

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

@@ -0,0 +1,310 @@
+# Workout Creation Playbook
+
+Building a workout is a multi-step sequence. Each step depends on an ID returned
+by the previous one, so run them in order and capture the IDs. The exercise-add
+step (step 4) is the one that returns HTTP 500 when fields are missing, so follow
+its field list exactly.
+
+All calls use the coach base (`https://api.trainheroic.com`) with the
+`session-token` header. With the client: `$TH request POST <path> '<json>'`.
+
+> **Prefer the builder.** the workout builder runs this whole sequence
+> from a JSON spec and already fills the 500-prone fields and handles RPE
+> correctly. Reach for the manual steps below only when debugging or doing
+> something the builder does not cover.
+>
+> **RPE rule (verified the hard way):** never prescribe RPE as a structured param.
+> `param_2_type: 14` is silently overridden to weight on any lift whose library
+> default param is weight, so the RPE values render as pounds. Put RPE in the
+> exercise `instruction` ("RPE 8"), prescribe reps, and leave load blank.
+
+## Step 1 — Get a program/calendar to write to
+
+Every team has an auto-created calendar (a "program"). Create a team if you need a
+fresh target:
+
+```
+POST /1.0/coach/team/createWithTitleAndCode
+{ "title": "My Team" }
+```
+
+The response and its side-effect loads expose the calendar/program ID (e.g.
+`4713246`). Existing programs come from `GET /1.0/coach/programs` (use
+`group_program` as the calendar ID for `/3.0/coach/program/{id}`).
+
+## Step 2 — Create an empty session on a date
+
+Date-based (team calendar):
+
+```
+POST /2.0/coach/calendar/workout/createWorkoutForDay/{calendarId}/{year}/{month}/{day}/0
+```
+
+Timeline-based (relative-day programs):
+
+```
+POST /2.0/coach/calendar/workout/createWorkoutForTimelineDay/{programId}/{day}/null
+```
+
+Pass an empty JSON body (`{}`). The response is a session object. Capture two
+IDs from it (verified live):
+
+- `workout_id` — the workout, needed by step 3 for blocks.
+- `id` — the programWorkout id, needed by step 5 to publish (and by
+  `removeProgramWorkout` as `pwId`).
+
+## Step 3 — Add a block to the session
+
+```
+POST /2.0/coach/calendar/saveProgramWorkoutSets
+[{
+  "workout_id": 140318787,
+  "order": 1,
+  "type": 4,
+  "instruction": "",
+  "is_redzone": null,
+  "redzone_type": 0,
+  "exercises": [],
+  "exerciseKeys": [],
+  "key": "k::9292",
+  "title": "Strength/Power"
+}]
+```
+
+`type` values: `1` = Conditioning, `2` = Hypertrophy, `4` = Strength/Power. The
+endpoint accepts an array, so multiple blocks can be created in one call. The
+response is an array of the created blocks; each block's `id` is its
+`workout_set_id`, which step 4 needs (the `key` you send comes back as `null`,
+so match blocks by `order`/`title`).
+
+## Step 4 — Add exercises to the block (the 500-prone step)
+
+```
+POST /2.0/coach/calendar/saveWorkoutSetExercises
+[ exercise1, exercise2, ... ]
+```
+
+Every exercise object must include the full field set below. Omitting any of the
+"critical" fields returns HTTP 500.
+
+```json
+{
+  "exercise_id": 1,
+  "workout_set_id": 671135671,
+  "set_id": 671135671,
+  "title": "Back Squat",
+  "instruction": "",
+  "order": 1,
+  "param_1_type": 3,
+  "param_2_type": 1,
+  "param_1_data_1": "5",
+  "param_1_data_2": "",
+  "param_1_data_3": "",
+  "param_1_data_4": "",
+  "param_1_data_5": "",
+  "param_1_data_6": "",
+  "param_1_data_7": "",
+  "param_1_data_8": "",
+  "param_1_data_9": "",
+  "param_1_data_10": "",
+  "param_2_data_1": "225",
+  "param_2_data_2": "",
+  "param_2_data_3": "",
+  "param_2_data_4": "",
+  "param_2_data_5": "",
+  "param_2_data_6": "",
+  "param_2_data_7": "",
+  "param_2_data_8": "",
+  "param_2_data_9": "",
+  "param_2_data_10": "",
+  "workout_set_exercise_template_id": null,
+  "no_sets": 0,
+  "param_count": 3,
+  "set_num": 3,
+  "key": "k::5001",
+  "setKey": 671135671,
+  "video_url": "",
+  "thumbnail_url": "",
+  "tags": [],
+  "eType": "e",
+  "use_count": 0
+}
+```
+
+Fields that cause a 500 when missing:
+
+- `set_num` — number of sets (mirror `param_count`)
+- `key` — any unique string in the form `"k::<number>"`
+- `setKey` — equal to `workout_set_id`
+- All 10 `param_1_data_N` and all 10 `param_2_data_N` slots — unused ones are `""`
+- `eType` — `"e"` for an exercise
+- `tags` — array, may be `[]`
+- `video_url`, `thumbnail_url` — strings, may be `""`
+- `use_count` — integer, may be `0`
+- `workout_set_exercise_template_id` — `null`
+
+The API ignores the `title` you send and substitutes the real title for
+`exercise_id`. It may also override `param_2_type` from the exercise's defaults.
+
+## Step 5 — Publish
+
+```
+POST /2.0/coach/calendar/programWorkout/publish
+[ 142002657 ]   // array of programWorkout IDs
+```
+
+## (Optional) Session note — Coach Instructions
+
+The session-level note (the day-note shown at the top of a session — greeting +
+writeup) is set with a PUT to the programWorkout, not on a block. Use the same
+`workout_id` from step 2:
+
+```
+PUT /3.0/coach/workout/{workout_id}
+{ ...the full programWorkout object..., "instruction": "Welcome to Week 12..." }
+```
+
+Build the body from the session object you already have (the create response, or a
+day's entry from `/1.0/coach/programs/edit`), set `instruction`, and replace
+`sets`/`setKeys` with a flat **list** of block ids sorted by `order` — the edit-GET
+returns `sets` as a dict keyed by block id, so convert it. This does **not** publish:
+`published` is echoed back as sent, so set the note **before** step 5 if the session
+should stay a draft. the workout builder does all of this when the spec has a
+top-level `"instruction"`.
+
+## Reading a session back (verified)
+
+To confirm what was built on a team calendar date:
+
+```
+GET /1.0/coach/programs/edit/{calendarId}/{year}/{month}/{day}
+```
+
+This returns `programWorkouts`, an array of every session on the calendar (it is
+not scoped to the single date you pass). Match the one you built by the `id` you
+captured at create time — do not assume `programWorkouts[0]`. On the matched
+session, `published` is `1` once published, and blocks live under its `sets`
+object keyed by `workout_set_id`; each block has an `exercises` array with the
+rendered `title`, `instruction`, and `param_*_data_N` values.
+
+---
+
+## Parameter types
+
+| Value | Meaning             | Display        |
+| ----- | ------------------- | -------------- |
+| 0     | None                | (no parameter) |
+| 1     | Weight              | `225 lb`       |
+| 2     | Weight (% of max)   | `75%`          |
+| 3     | Reps                | `5`            |
+| 4     | Time (seconds)      | `1:00`         |
+| 5     | Distance (yards)    | `50yd`         |
+| 6     | Distance (meters)   | `50m`          |
+| 7     | Height              | inches         |
+| 10    | Distance (miles)    | miles          |
+| 11    | Distance (feet)     | feet           |
+| 12    | Height (inches)     | inches         |
+| 13    | Heart Rate          | bpm            |
+| 14    | RPE                 | rating         |
+| 18    | Time (seconds, alt) | `0:30`         |
+
+Most common combos: `p1=3,p2=1` (reps @ weight, e.g. Back Squat), `p1=3,p2=0`
+(reps only / bodyweight, e.g. Push-Up), `p1=3` with `p2` absent (reps only),
+`p1=5` (distance in yards), `p1=4` (time).
+
+`param_1_data_N` is the value for param 1 in set N; `param_2_data_N` likewise for
+param 2. `param_count` is the number of sets (max 10).
+
+### The unit is fixed per exercise (verified)
+
+On save the API **discards the `param_1_type`/`param_2_type` you send and restores
+the exercise's library defaults.** Your `param_*_data_N` values are kept, so a value
+sent under the wrong assumed unit silently renders under the exercise's real unit.
+
+- **`param_1_type` (primary): always forced to the exercise default.** You cannot
+  change the primary unit at prescribe time. Stock `Run` (id 82) is miles, so a
+  "200 m run" written on `Run` renders as _200 miles_. For meters use a meters-native
+  exercise (`Sprint` 127, `Rowing` 101, `Shuttle Sprint` 42523) or a custom exercise.
+- **`param_2_type` (secondary): forced to the default too, except** you may add weight
+  (`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
+  `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.
+
+## Prescription patterns
+
+- **Superset**: send multiple exercises in one array, same `workout_set_id`/
+  `set_id`, different `order`. They render as A1, A2, ...
+- **Drop set**: one exercise, decreasing weight and increasing reps across the
+  `_data_N` slots.
+- **Pyramid**: vary both params up then down across the slots
+  (e.g. reps `5,3,1,3,5` at weight `185,225,275,225,185`).
+- **Bodyweight**: `param_2_type: 0` and leave every `param_2_data_N` empty.
+- **Weighted bodyweight** (weighted Pull-Up/Dip): add `param_2_type: 1` with loads.
+  Adding weight sticks _only_ on exercises whose default secondary is none (`0`).
+- **Max / AMRAP reps (verified)**: the rep slots are free text — put the literal
+  string `"Max"` (or `"AMRAP"`, `"ME"`) in `param_1_data_N`; it round-trips verbatim
+  and you can mix it with numbers (e.g. last set `"Max"`). The builder accepts
+  `"reps": ["Max", "Max"]` or `"reps": [5, 5, "Max"]`.
+- **RPE and % of max (verified caveat)**: `param_2_type: 14` (RPE) and `2` (% of max)
+  do **not** stick on exercises whose library default param is weight — the API
+  overrides them back to weight, so the numbers render as pounds. Reliable approach:
+  prescribe reps with `param_2_type: 0` (load left blank for athlete autoregulation)
+  and put the target in the exercise `instruction` (e.g. `"RPE 8"` or `"75% of max"`).
+  The `instruction` field round-trips intact. (This is one case of the fixed-unit
+  rule above.)
+
+## Common exercise IDs
+
+| ID   | Title       | p1  | p2  |
+| ---- | ----------- | --- | --- |
+| 1    | Back Squat  | 3   | 1   |
+| 3    | Front Squat | 3   | 1   |
+| 7    | Pull-Up     | 3   | 0   |
+| 24   | Burpee      | 3   | 0   |
+| 36   | Air Squat   | 3   | 0   |
+| 67   | Plank       | 4   | 0   |
+| 100  | Push-Up     | 3   | 0   |
+| 424  | Deadlift    | 3   | 1   |
+| 1162 | Bench Press | 3   | 1   |
+
+Full library: `GET /v5/exerciseLibrary/all`. Custom exercises:
+`POST /2.0/coach/exercise/create` with your own `title`, `param_1_type`,
+`param_2_type`.
+
+## Leaderboards (Red Zone)
+
+A block can be a **leaderboard** — TrainHeroic's "Red Zone" competition score. The
+UI shows a trophy and "FOR <UNIT>". It is encoded on the block, not the exercise,
+and is a separate unit system (it has Feet/Meters/Calories even when the exercise
+param is locked to another unit):
+
+- `redzone_type` = the score unit; setting it `> 0` flags `is_redzone = 1`.
+- `smaller_is_better = 1` makes the lowest score win (use for Time/Seconds).
+- `redzone_instruction` = optional scoring note.
+
+`redzone_type` values: `0` For Completion, `1` Weight, `2` Reps, `3` Rounds,
+`4` Time, `5` Yards, `6` Meters, `7` Feet, `8` Calories, `10` Miles, `12` Inches,
+`15` Watts, `17` Velocity, `18` Seconds.
+
+In the workout builder add `"leaderboard"` to a block: a unit string (`"rounds"`,
+`"time"`, `"calories"`, ...) or `{"unit": "time", "lowest_wins": true,
+"instruction": "..."}`. Time/Seconds default to lowest-wins.
+
+**When to set one (ask if unclear).** For an **AMRAP**, score = `rounds` (or `reps`);
+for a **"for time"** workout, score = `time` (lowest wins); for a max-distance/row,
+the distance/calorie unit. If the coach's intent is ambiguous, ask rather than guess.
+For an AMRAP also program **multiple sets** (one per expected round) — assume a fit
+athlete's round count (e.g. ~5–6 rounds for a ~10–12 min triplet) and confirm if unsure.
+
+## Editing and managing sessions
+
+- Set the session note (Coach Instructions): `PUT /3.0/coach/workout/{workoutId}`
+  with the programWorkout object + `instruction` (does not change publish state).
+- Unpublish: `POST /2.0/coach/calendar/programWorkout/unPublish/{programWorkoutId}`
+- Delete: `POST /2.0/coach/calendar/removeProgramWorkout` `{ "programId", "pwId" }`
+- Copy/repeat to a date: `POST /2.0/coach/calendar/copyProgramWorkout`
+- Save as template: `POST /2.0/coach/calendar/programWorkout/saveWorkoutAsTemplate/{workoutId}`