repwise 1.2.0__tar.gz → 2.0.0__tar.gz

{repwise-1.2.0/src/repwise.egg-info → repwise-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repwise
-Version: 1.2.0
+Version: 2.0.0
 Summary: Advance Garmin strength workout targets using double progression
 Author-email: Adam Żmuda <adam@zmuda.pro>
 License-Expression: MIT
@@ -21,15 +21,8 @@ Classifier: Topic :: Utilities
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: garminconnect==0.3.8
+Requires-Dist: garminconnect==0.3.11
 Requires-Dist: pyyaml==6.0.3
-Provides-Extra: dev
-Requires-Dist: commitizen==4.17.0; extra == "dev"
-Requires-Dist: mypy==2.3.0; extra == "dev"
-Requires-Dist: pre-commit==4.6.1; extra == "dev"
-Requires-Dist: pytest==9.1.1; extra == "dev"
-Requires-Dist: ruff==0.16.1; extra == "dev"
-Requires-Dist: types-PyYAML==6.0.12.20260724; extra == "dev"
 Dynamic: license-file
 
 # Garmin Double Progression
@@ -143,7 +136,8 @@ keeping an exercise in sync when it appears in more than one workout.
 | `repwise list` | Show your Garmin workouts and their ids |
 | `repwise import` | Build a `workouts.yaml` from your Garmin workouts |
 | `repwise check` | Check that your config names exercises Garmin actually has, that it still names the ones your workouts hold, and that every rep range fits what its weight step is really worth |
-| `repwise fetch` | Download raw workout JSON |
+| `repwise fetch workouts` | Download raw workout JSON |
+| `repwise fetch activities` | Download the raw JSON of the sessions you performed: the summary, the sets your watch recorded, and the workout each was run against |
 | `repwise fetch exercises` | Refresh Garmin's list of every exercise it knows, which `check` and `update` read |
 | `repwise logout` | Delete the cached Garmin token, so the next run logs in again |
 

{repwise-1.2.0 → repwise-2.0.0}/README.md

@@ -109,7 +109,8 @@ keeping an exercise in sync when it appears in more than one workout.
 | `repwise list` | Show your Garmin workouts and their ids |
 | `repwise import` | Build a `workouts.yaml` from your Garmin workouts |
 | `repwise check` | Check that your config names exercises Garmin actually has, that it still names the ones your workouts hold, and that every rep range fits what its weight step is really worth |
-| `repwise fetch` | Download raw workout JSON |
+| `repwise fetch workouts` | Download raw workout JSON |
+| `repwise fetch activities` | Download the raw JSON of the sessions you performed: the summary, the sets your watch recorded, and the workout each was run against |
 | `repwise fetch exercises` | Refresh Garmin's list of every exercise it knows, which `check` and `update` read |
 | `repwise logout` | Delete the cached Garmin token, so the next run logs in again |
 

{repwise-1.2.0 → repwise-2.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "repwise"
-version = "1.2.0"
+version = "2.0.0"
 description = "Advance Garmin strength workout targets using double progression"
 readme = "README.md"
 license = "MIT"
@@ -37,7 +37,7 @@ classifiers = [
 # raises a PR per release. garminconnect in particular has broken
 # authentication before, so the working version is recorded deliberately.
 dependencies = [
-    "garminconnect==0.3.8",
+    "garminconnect==0.3.11",
     "pyyaml==6.0.3",
 ]
 
@@ -50,14 +50,28 @@ Documentation = "https://github.com/theadzik/repwise/tree/main/docs"
 Changelog = "https://github.com/theadzik/repwise/blob/main/CHANGELOG.md"
 Issues = "https://github.com/theadzik/repwise/issues"
 
-[project.optional-dependencies]
+# Development tooling, as PEP 735 groups rather than extras. An extra is part
+# of the package - installable by anyone from PyPI, and only alongside the
+# package itself. These are neither: nobody installing repwise wants mypy, and
+# the release workflow wants commitizen *without* building repwise at all.
+# Groups install on their own, which is what makes that possible.
+#
+# `release` is split out because the release workflow needs commitizen and
+# nothing else, and the version of commitizen decides the release rules - which
+# commit types bump what, how the changelog renders. Pinning it here and
+# including the group in `dev` means a local `cz bump --dry-run` and the
+# workflow cannot disagree about the answer.
+[dependency-groups]
+release = [
+    "commitizen==4.17.1",
+]
 dev = [
-    "commitizen==4.17.0",
-    "mypy==2.3.0",
-    "pre-commit==4.6.1",
+    { include-group = "release" },
+    "mypy==2.3.1",
+    "pre-commit==4.6.2",
     "pytest==9.1.1",
-    "ruff==0.16.1",
-    "types-PyYAML==6.0.12.20260724",
+    "ruff==0.16.3",
+    "types-PyYAML==6.0.12.20260815",
 ]
 
 [project.scripts]

{repwise-1.2.0 → repwise-2.0.0}/src/repwise/__init__.py

@@ -1,4 +1,4 @@
 """Advance Garmin strength workout targets using double progression."""
 
 __all__ = ["__version__"]
-__version__ = "1.2.0"
+__version__ = "2.0.0"

{repwise-1.2.0 → repwise-2.0.0}/src/repwise/app/checking.py

@@ -4,7 +4,7 @@ import logging
 
 from ..checker import Finding, check_catalog, check_programming, check_workout
 from ..domain.models import Config, GarminSettings
-from ..errors import ExitCode, GarminError
+from ..errors import ExitCode, GarminError, NotInGarmin
 from ..garmin.catalog import ExerciseCatalog, optional
 from ..garmin.client import GarminSession
 from .report import SEVERITY
@@ -67,6 +67,20 @@ def run_check(session: GarminSession, config: Config) -> ExitCode:
             logger.info(f"{workout.key} ({workout_id})")
             try:
                 payload = session.workout(workout_id)
+            except NotInGarmin:
+                # The one failure here with a fix the user can act on: the id
+                # in workouts.yaml names a workout the account does not have,
+                # usually one deleted in Connect. Said as that rather than as
+                # the reading having failed, which is what the branch below is
+                # for and would bury the answer inside a longer sentence.
+                found.append(
+                    Finding(
+                        workout.key,
+                        f"garmin_workout_id {workout_id} is not in your Garmin "
+                        f"account - delete the id to have it created again",
+                        "error",
+                    )
+                )
             except GarminError as exc:
                 # A workout that cannot be read is itself an error-level
                 # finding, so an unreachable workout still fails the command.

repwise-2.0.0/src/repwise/app/fetch.py

@@ -0,0 +1,203 @@
+"""Download what Garmin holds as JSON: your workouts, your sessions, or its
+exercise catalog."""
+
+import logging
+import os
+from typing import Any
+
+from .. import dumps
+from ..domain.models import Config, GarminSettings
+from ..errors import ExitCode, GarminError
+from ..garmin import catalog
+from ..garmin.client import STRENGTH, GarminSession
+from ..garmin.payloads import activity_sport
+
+logger = logging.getLogger(__name__)
+
+
+def run_fetch_exercises(settings: GarminSettings) -> ExitCode:
+    """Download Garmin's exercise catalog, replacing any cached copy.
+
+    Unconditional, unlike the first-run download `check` and `update` do for
+    themselves: asking for the catalog by name is how you refresh one that has
+    gone stale, so finding a copy already there is not a reason to stop.
+
+    No session is opened. The catalog is public, and requiring a login to
+    download it would be a password prompt in exchange for nothing.
+    """
+    payload = catalog.download()
+    # Parsed for the count, and to fail before overwriting a good cache with a
+    # response that turned out not to be a catalog at all.
+    parsed = catalog.ExerciseCatalog.parse(payload)
+    path = catalog.save(settings, payload)
+    logger.info(
+        f"Saved {len(parsed)} exercises in {len(parsed.categories)} "
+        f"categories -> {path}"
+    )
+    return ExitCode.OK
+
+
+def run_fetch(
+    session: GarminSession, config: Config, workout_ids: list[str] | None = None
+) -> ExitCode:
+    # A workout Garmin does not hold yet has no definition to download, so it
+    # is simply not among the ids rather than a failure to report.
+    ids = workout_ids or [w.garmin_workout_id for w in config if w.garmin_workout_id]
+    failed = False
+    for workout_id in ids:
+        try:
+            payload = session.workout(workout_id)
+        except GarminError as exc:
+            # One unreachable workout should not cost the user the others.
+            logger.error(f"FAILED {workout_id}: {exc}")
+            failed = True
+            continue
+
+        path = dumps.write(payload, config.garmin.dump_dir, dumps.WORKOUT, workout_id)
+        logger.info(f"Saved {payload.get('workoutName', '(unnamed)')} -> {path}")
+
+    return ExitCode.NOTHING_USABLE if failed else ExitCode.OK
+
+
+def run_fetch_activities(
+    session: GarminSession, config: Config, activity_ids: list[str] | None = None
+) -> ExitCode:
+    """Save performed sessions as JSON, three payloads to a session.
+
+    None of the three is either of the others. The summary names and dates the
+    session; the sets are what the watch recorded, rep by rep and in grams; the
+    executed workout is what that session was *asked* for, and is the only
+    record of it, since `update` has since rewritten the definition Garmin
+    stores. An activity performed against no workout has no third file.
+
+    Ids name sessions directly, and are downloaded as given: asking for one by
+    id says more about what you want than its sport does, and an id is also the
+    only way to reach a session further back than the search limit. Without
+    them the recent activities are scanned and the strength ones kept - how far
+    back that reaches is `settings.garmin.activity_search_limit`.
+    """
+    ids = list(activity_ids or [])
+    if not ids:
+        recent = session.recent_activities()
+        ids = [
+            str(activity["activityId"])
+            for activity in recent
+            if activity_sport(activity) == STRENGTH and activity.get("activityId")
+        ]
+        if not ids:
+            logger.warning(
+                f"No strength activities among the {len(recent)} most recent. "
+                "Raise settings.garmin.activity_search_limit to look further "
+                "back, or name an activity id."
+            )
+            return ExitCode.NOTHING_USABLE
+
+    saved = 0
+    skipped = 0
+    failed = False
+    for activity_id in ids:
+        # Never true unless caching is on, so a run without it downloads
+        # everything it is asked for exactly as it always did. `--force` says
+        # so by opening a session with no cache behind it, which is why there
+        # is no flag to read here.
+        if session.is_cached(activity_id):
+            skipped += 1
+            logger.info(f"Already on disk: {activity_id}")
+            continue
+
+        try:
+            name, paths = _save_activity(session, config.garmin.dump_dir, activity_id)
+        except GarminError as exc:
+            # One unreachable session should not cost the user the others.
+            logger.error(f"FAILED {activity_id}: {exc}")
+            failed = True
+            continue
+
+        saved += 1
+        written = ", ".join(os.path.basename(path) for path in paths)
+        logger.info(f"Saved {name} -> {written}")
+
+    logger.info("")
+    # Counted as they land rather than taken from `ids`, so that a run which
+    # lost one to a failure does not claim to have saved it.
+    logger.info(f"{saved} session(s) -> {config.garmin.dump_dir}")
+    if skipped:
+        logger.info(f"{skipped} already on disk; --force downloads them again.")
+    return ExitCode.NOTHING_USABLE if failed else ExitCode.OK
+
+
+def cache_activities(
+    session: GarminSession, config: Config, activities: list[dict[str, Any]]
+) -> None:
+    """Bring the dump directory level with the sessions Garmin just listed.
+
+    What `update` does before it works anything out, so that the run reads
+    those sessions off disk and every run after it reads them without asking
+    at all. Only the strength ones: the rest hold no sets to learn from.
+
+    Silent unless caching is on. A session with no cache behind it holds
+    nothing, so every activity would count as missing and this would download
+    the whole search limit on every single run.
+
+    One session that cannot be downloaded is logged and stepped over. This is
+    filling a cache, not doing the work: whatever is missing afterwards is
+    fetched again when something actually reads it, and fails there if it
+    still cannot be had.
+    """
+    if not config.garmin.activity_caching:
+        return
+
+    missing = [
+        str(activity["activityId"])
+        for activity in activities
+        if activity_sport(activity) == STRENGTH
+        and activity.get("activityId")
+        and not session.is_cached(str(activity["activityId"]))
+    ]
+    if not missing:
+        logger.debug("Every strength session Garmin listed is already on disk.")
+        return
+
+    logger.info(f"Filing {len(missing)} session(s) into {config.garmin.dump_dir}")
+    for activity_id in missing:
+        try:
+            _save_activity(session, config.garmin.dump_dir, activity_id)
+        except GarminError as exc:
+            logger.warning(f"Could not file {activity_id}: {exc}")
+
+
+def _save_activity(
+    session: GarminSession, directory: str, activity_id: str
+) -> tuple[str, list[str]]:
+    """Download one session's payloads. Its name, and the files written.
+
+    The summary is fetched even for an activity a scan just listed, so that
+    `activity-<id>.json` holds the same thing however it was asked for: the
+    detail Garmin returns for one activity is fuller than the entry it returns
+    for it in a list.
+
+    All three are written, including an executed workout that came back empty.
+    A session performed against no workout is a fact worth recording, and it is
+    what lets a missing file mean one thing only - that nobody has asked yet -
+    which is what `dumps.ActivityCache` reads it as.
+
+    Behind a caching session the same bytes have just been written by the cache
+    itself, since that is what a miss does. Writing them again is what makes
+    this work identically with caching off, which is worth more than the write
+    it saves - once per session, of a file that is already open in the page
+    cache.
+    """
+    activity = session.activity(activity_id)
+    executed = session.executed_workout(activity_id)
+    if not executed:
+        logger.debug(f"{activity_id} was not performed against a workout")
+
+    paths = [
+        dumps.write(activity, directory, dumps.ACTIVITY, activity_id),
+        dumps.write(
+            session.exercise_sets(activity_id), directory, dumps.SETS, activity_id
+        ),
+        dumps.write(executed, directory, dumps.EXECUTED, activity_id),
+    ]
+
+    return activity.get("activityName") or "(unnamed)", paths

{repwise-1.2.0 → repwise-2.0.0}/src/repwise/app/update.py

@@ -6,9 +6,7 @@ replayed oldest first, and a target that moves propagated into every other
 workout containing that exercise.
 """
 
-import json
 import logging
-import os
 from collections.abc import Callable, Container, Hashable, Iterable
 from dataclasses import dataclass, field, replace
 from typing import Any
@@ -34,10 +32,12 @@ from ..planner import (
     decided_targets,
     executed_targets,
     find_workout,
+    index_specs,
     logged_for,
     plan_sync,
     plan_workout,
 )
+from .fetch import cache_activities
 from .report import report_plan
 
 logger = logging.getLogger(__name__)
@@ -49,7 +49,6 @@ class UpdateOptions:
 
     apply: bool = False
     activity: str | None = None
-    dump: bool = False
     push: bool = False
 
     def __post_init__(self) -> None:
@@ -97,14 +96,6 @@ class Payloads:
         return self._fetched[workout_id]
 
 
-def dump(payloads: dict[str, Any], directory: str, suffix: str) -> None:
-    for label, payload in payloads.items():
-        path = os.path.join(directory, f"dump-{label}-{suffix}.json")
-        with open(path, "w") as fh:
-            json.dump(payload, fh, indent=2)
-        logger.debug(f"Wrote {path}")
-
-
 def pick_sessions(
     session: GarminSession,
     config: Config,
@@ -232,9 +223,11 @@ def gather_history(
     trained under a different workout -- contributes nothing to its own history
     rather than breaking anyone else's.
     """
+    specs = index_specs(workout.exercises)
+
     trained = {}
     for spec in workout.exercises:
-        logged = logged_for(spec, latest)
+        logged = logged_for(spec, latest, specs)
         if spec.time_based:
             logged = [entry.as_time() for entry in logged]
         trained[normalise(spec.garmin_name)] = logged
@@ -259,7 +252,7 @@ def gather_history(
         for spec in workout.exercises:
             key = normalise(spec.garmin_name)
             target = targets.get(key)
-            logged = logged_for(spec, performed)
+            logged = logged_for(spec, performed, specs)
             if target is None or not logged:
                 continue
             if spec.time_based:
@@ -425,13 +418,6 @@ def advance_trained(  # noqa: PLR0913 - each argument is one independent input
         sets_payload = session.exercise_sets(activity_id)
         payload = payloads[garmin_id(workout)]
 
-        if options.dump:
-            dump(
-                {"sets": sets_payload, "workout": payload},
-                config.garmin.dump_dir,
-                activity_id,
-            )
-
         performed = performed_sets(sets_payload)
         if not any(performed):
             logger.warning("No working sets found in that activity; nothing to do.")
@@ -510,6 +496,9 @@ def run_update(
     # Fetched once and used twice: to find the session each workout was last
     # trained in, and then to read back the ones before it.
     activities = session.recent_activities()
+    # With caching on, everything below reads sessions off disk, so the disk
+    # is brought level with Garmin first. Without it, this does nothing at all.
+    cache_activities(session, config, activities)
     try:
         sessions = pick_sessions(session, config, options.activity, activities)
     except ActivityNotFound as exc:

{repwise-1.2.0 → repwise-2.0.0}/src/repwise/cli/__init__.py

@@ -12,7 +12,7 @@ import sys
 from collections.abc import Callable
 
 from ..app.checking import run_check
-from ..app.fetch import run_fetch, run_fetch_exercises
+from ..app.fetch import run_fetch, run_fetch_activities, run_fetch_exercises
 from ..app.importing import ImportOptions, run_import
 from ..app.listing import run_list
 from ..app.logout import run_logout
@@ -23,7 +23,7 @@ from ..errors import ExitCode, UsageError, WorkoutError
 from ..garmin.client import connect
 from ..log import configure
 from .completion import render
-from .parser import CATALOG, build_parser
+from .parser import ACTIVITIES, CATALOG, TARGETS, build_parser
 
 __all__ = ["main", "build_parser"]
 
@@ -40,25 +40,53 @@ Handler = Callable[[argparse.Namespace, Config], ExitCode]
 
 
 def _update(args: argparse.Namespace, config: Config) -> ExitCode:
-    options = UpdateOptions(
-        apply=args.apply, activity=args.activity, dump=args.dump, push=args.push
-    )
+    options = UpdateOptions(apply=args.apply, activity=args.activity, push=args.push)
     return run_update(connect(config.garmin), config, options)
 
 
-def _fetch(args: argparse.Namespace, config: Config) -> ExitCode:
-    if CATALOG not in args.workout_ids:
-        return run_fetch(connect(config.garmin), config, args.workout_ids)
-    if len(args.workout_ids) > 1:
-        # Refused rather than guessed at: the two downloads share a word and
-        # nothing else - different source, different destination, and one of
-        # them needs a login - so doing both from one invocation would be a
-        # coincidence of spelling, not a feature.
+def _fetch_target(args: argparse.Namespace) -> tuple[str, list[str]]:
+    """What `fetch` was asked to download, and which ids narrow it.
+
+    A target can only be the first word, since it says what the ids after it
+    are; argparse rejects anything else there. One appearing later is a mistake
+    rather than an id, and is refused rather than downloaded as though it were
+    one - which argparse cannot do for us, because the ids after the target are
+    numbers it has nothing to check against.
+    """
+    target, ids = args.target, list(args.ids)
+
+    stray = next((word for word in ids if word in TARGETS), None)
+    if stray:
         raise UsageError(
-            f"`fetch {CATALOG}` downloads the exercise catalog and takes no "
-            f"workout ids. Run it on its own."
+            f"`{stray}` says what to download, so it goes first: "
+            f"`repwise fetch {stray}`."
         )
-    return run_fetch_exercises(config.garmin)
+    return target, ids
+
+
+def _fetch(args: argparse.Namespace, config: Config) -> ExitCode:
+    target, ids = _fetch_target(args)
+
+    if target == CATALOG:
+        if ids:
+            # Refused rather than guessed at: the catalog shares a command with
+            # the other two downloads and nothing else - different source,
+            # different destination, and it alone needs no login - so doing
+            # both from one invocation would be a coincidence of spelling.
+            raise UsageError(
+                f"`fetch {CATALOG}` downloads the exercise catalog and takes no "
+                f"workout ids. Run it on its own."
+            )
+        return run_fetch_exercises(config.garmin)
+
+    # --force is spelled as a session with no cache behind it rather than as a
+    # flag the use case reads: a download that must replace what is on disk is
+    # one that must not answer from it either, and this way the use case has
+    # one path rather than two.
+    session = connect(config.garmin, cache=not args.force)
+    if target == ACTIVITIES:
+        return run_fetch_activities(session, config, ids)
+    return run_fetch(session, config, ids)
 
 
 def _list(args: argparse.Namespace, config: Config) -> ExitCode:

{repwise-1.2.0 → repwise-2.0.0}/src/repwise/cli/completion.py

@@ -20,8 +20,6 @@ from collections.abc import Callable, Iterable
 from dataclasses import dataclass
 from enum import Enum
 
-from .parser import SUGGESTIONS
-
 #: The metavar of an argument that names a file. `parser.py` spells its two
 #: that way, so this one word is what decides they complete as paths.
 PATH = "PATH"
@@ -126,22 +124,15 @@ def _options(parser: argparse.ArgumentParser) -> tuple[Option, ...]:
     )
 
 
-def _positionals(
-    command: str, parser: argparse.ArgumentParser
-) -> tuple[Positional, ...]:
+def _positionals(parser: argparse.ArgumentParser) -> tuple[Positional, ...]:
     found: list[Positional] = []
     for action in _actions(parser):
         if action.option_strings:
             continue
-        words = tuple(action.choices or ())
-        if not found:
-            # A word argparse cannot be told about belongs to the first
-            # positional, since that is the one that would read it.
-            words += SUGGESTIONS.get(command, ())
         found.append(
             Positional(
                 metavar=_metavar(action),
-                words=words,
+                words=tuple(action.choices or ()),
                 repeated=action.nargs in {"*", "+"},
             )
         )
@@ -167,7 +158,7 @@ def _commands(parser: argparse.ArgumentParser) -> tuple[Command, ...]:
                 name=name,
                 help=helps.get(name, ""),
                 options=_options(sub),
-                positionals=_positionals(name, sub),
+                positionals=_positionals(sub),
             )
             for name, sub in action.choices.items()
         )

{repwise-1.2.0 → repwise-2.0.0}/src/repwise/cli/parser.py

@@ -14,22 +14,18 @@ from typing import Any
 
 from .. import __version__
 
-#: `fetch` takes workout ids, and this word instead of them. Safe as a keyword
-#: rather than a flag because a Garmin workout id is a number, so nothing a
-#: user could legitimately pass here is ambiguous with it.
+#: What `fetch` can be asked to download, as the first word after it. Safe as
+#: keywords rather than flags because a Garmin id is a number, so no id a user
+#: could legitimately pass is ambiguous with one of these.
+WORKOUTS = "workouts"
+ACTIVITIES = "activities"
 CATALOG = "exercises"
+TARGETS = (WORKOUTS, ACTIVITIES, CATALOG)
 
 #: The shells `completion` knows how to write for. One renderer answers each,
 #: in `completion.py`.
 SHELLS = ("bash", "zsh")
 
-#: Words a positional accepts that argparse cannot be told about, keyed by the
-#: command whose positional accepts them. `fetch` takes any number of workout
-#: ids, so it has no `choices` to enumerate and cannot be given one without
-#: rejecting every id there is - but the single word that means something else
-#: to it is still worth completing, and this is what says so.
-SUGGESTIONS: dict[str, tuple[str, ...]] = {"fetch": (CATALOG,)}
-
 
 def add_verbose(
     parser: argparse.ArgumentParser, default: Any = argparse.SUPPRESS
@@ -61,10 +57,10 @@ def build_parser() -> argparse.ArgumentParser:
             "examples:\n"
             "  repwise update            show what a run would change\n"
             "  repwise update --apply    write it back to Garmin\n"
-            "  repwise update --dump     save the raw Garmin JSON, change nothing\n"
             "  repwise update --apply --push   also send them to your watch\n"
             "  repwise update --activity 1234  replay one session you skipped\n"
-            "  repwise fetch             download the workout definitions\n"
+            "  repwise fetch workouts    download the workout definitions\n"
+            "  repwise fetch activities  download your recent strength sessions\n"
             "  repwise fetch exercises   refresh Garmin's exercise catalog\n"
             "  repwise list              show your Garmin workouts and ids\n"
             "  repwise import -o f.yaml  build config from Garmin workouts\n"
@@ -135,11 +131,6 @@ def build_parser() -> argparse.ArgumentParser:
         help="update from this one activity instead of scanning for each "
         "workout's latest",
     )
-    update.add_argument(
-        "--dump",
-        action="store_true",
-        help="also save the raw Garmin JSON payloads to dump_dir",
-    )
     update.add_argument(
         "--push",
         action="store_true",
@@ -149,23 +140,43 @@ def build_parser() -> argparse.ArgumentParser:
 
     fetch = sub.add_parser(
         "fetch",
-        help="download workout definitions, or Garmin's exercise catalog",
-        description="Save workout definitions as JSON into "
-        "settings.garmin.dump_dir, for inspecting Garmin's payloads or checking "
-        "connectivity. The single word `exercises` instead of any ids "
-        "downloads something else entirely: Garmin's list of every exercise it "
-        "knows and the category each is filed under, cached in "
+        help="download workouts, performed sessions, or Garmin's exercise catalog",
+        description="Save what Garmin holds as JSON, for inspecting its "
+        "payloads by hand or checking connectivity. The first word says which. "
+        "`workouts` downloads the definitions this tool writes targets into, "
+        "one file each. `activities` downloads the sessions you performed - "
+        "the summary, the sets your watch recorded and the workout each was "
+        "run against, three files each - and only strength ones, since the "
+        "rest hold no sets to read. Both take ids to narrow them, and both "
+        "land in settings.garmin.dump_dir; without ids, `workouts` downloads "
+        "every workout in your config and `activities` every strength session "
+        "within settings.garmin.activity_search_limit. `exercises` downloads "
+        "something else entirely: Garmin's list of every exercise it knows and "
+        "the category each is filed under, cached in "
         "settings.garmin.token_store and read by `check` to tell a real "
         "exercise name from a plausible-looking one. `check` downloads that "
         "itself the first time it needs it, so this is how you refresh a copy "
         "that has gone stale, not something to run first.",
     )
     fetch.add_argument(
-        "workout_ids",
+        "target",
+        choices=TARGETS,
+        metavar="TARGET",
+        help=f"`{WORKOUTS}`, `{ACTIVITIES}` or `{CATALOG}`",
+    )
+    fetch.add_argument(
+        "ids",
         nargs="*",
         metavar="ID",
-        help="workout ids; defaults to every workout in the config. Or the "
-        "single word `exercises` to refresh the exercise catalog",
+        help="which workouts or activities to download; defaults to every "
+        "workout in the config, or every strength session found",
+    )
+    fetch.add_argument(
+        "--force",
+        action="store_true",
+        help=f"download sessions already in dump_dir again, rather than "
+        f"leaving them alone. Only means anything for `{ACTIVITIES}`, and "
+        "only with settings.garmin.activity_caching on",
     )
     add_verbose(fetch)