Merge pull request 'Package skill as installable zip (Gitea Actions)' (#2) from ci/skill-zip-release into main

- Release step now authenticates with the RELEASE_TOKEN Actions secret
  (repo write) instead of the automatic token; drop the now-unneeded
  permissions block.
- Add a step that publishes the skill zip to the Gitea generic packages
  registry (cycling-training-skill@<tag>) using the REGISTRY_TOKEN secret,
  handling 200/201/409 responses.
- README: document the registry download URL and both secrets.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TqrhBhC3GEcKyaw8RTk8G6

.gitea/workflows/release-skill.yml

@@ -0,0 +1,114 @@
+name: Package skill
+
+# Builds the installable Claude-skill zip (dist/cycling-training-<version>.zip).
+#
+#   - Push a tag  v*   -> builds the zip AND attaches it to a Gitea release.
+#   - Run manually     -> builds the zip and uploads it as a run artifact.
+#
+# Requirements on the Gitea side (already provisioned):
+#   * A registered Actions runner (image with bash/zip/curl, e.g. catthehacker/ubuntu).
+#   * Actions enabled for this repo (Settings > Actions).
+#   * Actions secrets:
+#       - RELEASE_TOKEN  : token with repo write, used to create the release + upload the asset.
+#       - REGISTRY_TOKEN : token with package write, used to publish the zip to the
+#                          Gitea generic packages registry.
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version label for the zip (e.g. v1.0.0)'
+        required: false
+        default: 'manual'
+
+jobs:
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Determine version
+        id: ver
+        run: |
+          if [ "${{ github.ref_type }}" = "tag" ]; then
+            echo "version=${{ github.ref_name }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "version=${{ github.event.inputs.version }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build skill zip
+        run: bash scripts/build-skill-zip.sh "${{ steps.ver.outputs.version }}"
+
+      - name: Upload run artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: cycling-training-skill-${{ steps.ver.outputs.version }}
+          path: dist/*.zip
+          if-no-files-found: error
+
+      - name: Attach zip to release
+        if: github.ref_type == 'tag'
+        env:
+          TOKEN: ${{ secrets.RELEASE_TOKEN }}
+          SERVER: ${{ github.server_url }}
+          REPO: ${{ github.repository }}
+          VERSION: ${{ steps.ver.outputs.version }}
+        run: |
+          set -euo pipefail
+          ZIP="$(ls dist/*.zip | head -1)"
+          echo "Publishing ${ZIP} to ${SERVER}/${REPO} release ${VERSION}"
+
+          # Create the release for this tag; if it already exists, look up its id.
+          REL_ID="$(curl -sS -X POST \
+            -H "Authorization: token ${TOKEN}" \
+            -H "Content-Type: application/json" \
+            "${SERVER}/api/v1/repos/${REPO}/releases" \
+            -d "{\"tag_name\":\"${VERSION}\",\"name\":\"${VERSION}\",\"body\":\"Installable Claude-skill package for cycling-training. Download the .zip below and import it in Claude Desktop / claude.ai (Settings > Skills) or unzip into your Claude Code skills directory.\"}" \
+            | grep -o '"id":[0-9]*' | head -1 | cut -d: -f2 || true)"
+
+          if [ -z "${REL_ID}" ]; then
+            REL_ID="$(curl -sS \
+              -H "Authorization: token ${TOKEN}" \
+              "${SERVER}/api/v1/repos/${REPO}/releases/tags/${VERSION}" \
+              | grep -o '"id":[0-9]*' | head -1 | cut -d: -f2)"
+          fi
+
+          if [ -z "${REL_ID}" ]; then
+            echo "ERROR: could not create or find a release for tag ${VERSION}" >&2
+            exit 1
+          fi
+
+          curl -sS -X POST \
+            -H "Authorization: token ${TOKEN}" \
+            -F "attachment=@${ZIP}" \
+            "${SERVER}/api/v1/repos/${REPO}/releases/${REL_ID}/assets?name=$(basename "${ZIP}")"
+          echo "Attached $(basename "${ZIP}") to release ${VERSION} (id ${REL_ID})."
+
+      - name: Publish zip to Gitea packages registry
+        if: github.ref_type == 'tag'
+        env:
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+          SERVER: ${{ github.server_url }}
+          OWNER: ${{ github.repository_owner }}
+          VERSION: ${{ steps.ver.outputs.version }}
+        run: |
+          set -euo pipefail
+          ZIP="$(ls dist/*.zip | head -1)"
+          FILE="$(basename "${ZIP}")"
+          PACKAGE="cycling-training-skill"
+          URL="${SERVER}/api/packages/${OWNER}/generic/${PACKAGE}/${VERSION}/${FILE}"
+          echo "Uploading ${FILE} to generic package ${PACKAGE}@${VERSION}"
+          CODE="$(curl -sS -o /tmp/reg_resp.txt -w '%{http_code}' -X PUT \
+            -H "Authorization: token ${REGISTRY_TOKEN}" \
+            --upload-file "${ZIP}" \
+            "${URL}")"
+          echo "HTTP ${CODE}"; cat /tmp/reg_resp.txt 2>/dev/null || true; echo
+          case "${CODE}" in
+            200|201) echo "Published ${FILE} to packages registry." ;;
+            409) echo "Version ${VERSION} already present in registry — skipping." ;;
+            *) echo "ERROR: registry upload failed (HTTP ${CODE})" >&2; exit 1 ;;
+          esac

.gitignore

@@ -0,0 +1,9 @@
+# Local Claude Code settings (machine-specific)
+.claude/settings.local.json
+
+# Build output (skill zip packages)
+dist/
+
+# OS / editor cruft
+.DS_Store
+*.swp

README.md

@@ -0,0 +1,116 @@
+# cycling-training
+
+A modular **Claude skill** that provides periodization logic, workout design, research-backed
+protocols, and interpretation guidance for endurance and off-road cycling training — designed to
+**companion an Intervals.icu MCP server**, not replace it.
+
+## The companion-to-MCP architecture
+
+This skill deliberately holds **no data and no calculators**. It is the *reasoning* half of a
+two-part system:
+
+| Layer | Owns | Examples |
+|-------|------|----------|
+| **Intervals.icu MCP server** (data + computed metrics) | Fetching and computing everything numeric | activities, wellness, power curves, CTL / ATL / TSB, training-load ramp, zones, TSS, best efforts, streams |
+| **`cycling-training` skill** (knowledge + reasoning) | Deciding what the numbers *mean* and what to do next | periodization logic, workout design, research-backed protocols, interpretation of trends, confound-aware caveats |
+
+**The split is a hard rule.** If a script would only reproduce math the MCP API already returns
+(zones, TSS, load metrics, CTL/ATL/TSB), it is intentionally absent. Ask the MCP server for the
+number; ask this skill what to do about it.
+
+### How they work together (typical flow)
+
+1. **MCP** returns the data — e.g. `get_athlete_summary` (CTL/ATL/TSB), `get_wellness_data`
+   (HRV, RHR, sleep), `get_athlete_power_curves`, `get_activities`.
+2. **Skill** supplies the reasoning — e.g. "TSB is −25 eight days out from an A-race; the taper
+   doc targets +5 to +15 by race day, so shed fatigue," or "this VO2 session banked little time
+   ≥90% VO2max; the interval doc says check whether rep length / work:rest kept power in the band."
+3. **You (Claude)** combine them into a recommendation, always citing which layer supplied what.
+
+## Repository layout
+
+```
+cycling-training/
+├── SKILL.md                      # Router — loads the right reference doc by need
+├── README.md                     # This file
+├── references/
+│   ├── durability.md             # Fatigue resistance as a trainable quality + field test
+│   ├── mtb-xco-demands.md        # MTB/XCO demand profile; power governs, HR caveat
+│   ├── strength-for-cyclists.md  # Heavy strength; masters rationale; from-zero ramp
+│   ├── vo2max-intervals.md       # Maximizing time ≥90% VO2max; work:rest; rep length
+│   ├── periodization.md          # Distribution philosophy; base/build/peak; CTL ramp; taper
+│   ├── data-confounds.md         # HR reliability; power-governs; decoupling/RHR caveats
+│   └── citations.md              # Master citation list with PMID/DOI — single source of truth
+└── assets/
+    ├── plan-template-base.md         # Backward-mapped base mesocycle skeleton (3:1 / 2:1)
+    ├── plan-template-build.md        # Build block: VO2 + durability + strength integration
+    └── field-test-durability.md      # The ~1,500 kJ → 1-min hill durability field test
+```
+
+## Installing as a Claude skill
+
+A Claude skill is a directory containing a `SKILL.md` with YAML frontmatter (`name` +
+`description`). To install:
+
+**Claude Code (project or personal):**
+```bash
+# Personal (available in every project):
+git clone <this-repo> ~/.claude/skills/cycling-training
+
+# Or project-scoped (checked in with a repo):
+git clone <this-repo> .claude/skills/cycling-training
+```
+
+Claude auto-discovers any `SKILL.md` under a `skills/` directory. The `description` field in the
+frontmatter is what Claude matches against to decide when to load the skill, so keep it intact.
+
+**Claude Desktop / claude.ai (import a zip):** the skill ships as a packaged `.zip` whose single
+top-level `cycling-training/` folder holds `SKILL.md` and the docs — the layout Claude expects. Get
+the zip one of two ways, then import it in **Settings → Skills**:
+
+- **From a release:** download `cycling-training-<version>.zip` from the repo's Releases (produced
+  automatically — see *Packaging & releases* below).
+- **From the packages registry:** the same zip is published to the Gitea generic packages registry:
+  ```
+  https://git.farh.net/api/packages/farhoodlabs/generic/cycling-training-skill/<version>/cycling-training-<version>.zip
+  ```
+- **Build it yourself:**
+  ```bash
+  scripts/build-skill-zip.sh v1.0.0   # -> dist/cycling-training-v1.0.0.zip
+  ```
+
+Once installed, this skill loads automatically when you ask cycling-training questions, and it
+pairs with your connected Intervals.icu MCP server for the live data.
+
+## Packaging & releases
+
+`scripts/build-skill-zip.sh [version]` stages the installable files and produces
+`dist/cycling-training-<version>.zip` (validating that `SKILL.md` carries `name`/`description`
+frontmatter). A Gitea Actions workflow, `.gitea/workflows/release-skill.yml`, runs it:
+
+- **Push a tag `v*`** (e.g. `git tag v1.0.0 && git push origin v1.0.0`) → builds the zip,
+  **attaches it to a Gitea release** for that tag, and **publishes it to the packages registry**.
+- **Run the workflow manually** (workflow_dispatch) → builds the zip and uploads it as a run
+  artifact you can download.
+
+The workflow uses two Actions secrets: `RELEASE_TOKEN` (repo write — creates the release and
+uploads the asset) and `REGISTRY_TOKEN` (package write — publishes to the generic packages
+registry). A registered Actions runner and Actions-enabled repo are also required.
+
+## How to read the docs
+
+- **`SKILL.md` is a router, not a manual.** It points to the one reference doc that answers the
+  question at hand. Load docs on demand; don't read them all up front.
+- **Every quantitative claim carries a citation** (author/year, with PMID/DOI in `citations.md`).
+  This is deliberate: it lets future-you *verify* rather than trust.
+- **Where the mechanism is established but the optimal dose is not, the docs say so** — marked
+  `⚠️ under-researched — track individual response`. Treat those as hypotheses to test on
+  yourself, not settled protocol.
+
+## Scope & honesty notes
+
+- Content is written for **balanced road/TT and MTB** use; discipline-specific numbers are
+  labelled and not over-transferred (small-n elite XCO data ≠ masters marathon reality).
+- This skill gives **general training-science reasoning, not individualized medical advice.**
+  Nothing here overrides a physician, and readiness/overtraining calls should use the
+  confound-aware logic in `references/data-confounds.md`, never naive single-number rules.

SKILL.md

@@ -0,0 +1,69 @@
+---
+name: cycling-training
+description: >-
+  Periodization logic, workout design, and research-backed protocols for endurance and off-road
+  cycling (road/TT + MTB/XCO). Companions an Intervals.icu MCP server that supplies all data and
+  computed metrics. Use when planning training blocks, designing VO2max/threshold/durability
+  workouts, integrating heavy strength (esp. masters), setting CTL ramp or A-race taper targets,
+  interpreting CTL/ATL/TSB or wellness trends, or deciding whether to trust HR vs power. Routes to
+  focused, individually loadable reference docs; every quantitative claim is cited.
+---
+
+# Cycling Training — knowledge & reasoning skill
+
+This skill is the **reasoning half** of a two-part system. The **Intervals.icu MCP server owns all
+data and computed metrics**; this skill owns the **knowledge and interpretation**. Get the numbers
+from MCP, then use these docs to decide what they mean and what to do next.
+
+## Data / knowledge split (read this first)
+
+| Ask the **MCP server** for… | Ask **this skill** for… |
+|---|---|
+| Activities, streams, best efforts, power curves | What workout to prescribe and why |
+| CTL / ATL / TSB, training-load ramp, TSS | How fast to ramp CTL; what TSB to target for an A-race |
+| Zones, sport settings, thresholds (FTP, MAP) | How to structure work:rest and rep length within a zone |
+| Wellness: HRV, RHR, sleep, readiness | Whether a wellness signal is trustworthy or confounded |
+
+**Never recompute what MCP already returns** (zones, TSS, load metrics). This skill contains no
+calculators by design — only periodization logic, workout design, protocols, and interpretation.
+
+> Relevant MCP tools (names may vary by server): `get_athlete_summary`, `get_athlete_profile`,
+> `get_sport_settings`, `get_activities` / `search_activities`, `get_activity_details` /
+> `_streams` / `_intervals` / `_best_efforts`, `get_athlete_power_curves`, `get_wellness_data`,
+> `get_training_readiness`, `get_events` / `add_or_update_event` (to schedule planned workouts).
+
+## Router — load the doc that matches the need
+
+| If the question is about… | Load |
+|---|---|
+| **Fatigue resistance / durability** — training it, why fatigued-state power matters, the field test | `references/durability.md` |
+| **MTB / XCO** — race demands, why power (not HR) governs off-road, marathon vs lap XCO | `references/mtb-xco-demands.md` |
+| **Strength training** — heavy lifting for cyclists, masters muscle loss, from-zero ramp, in-season | `references/strength-for-cyclists.md` |
+| **VO2max / high-intensity intervals** — rep length, work:rest, maximizing time ≥90% VO2max | `references/vo2max-intervals.md` |
+| **Season structure** — base/build/peak, mesocycles, CTL ramp, A-race taper & TSB targets, polarized vs pyramidal | `references/periodization.md` |
+| **Trusting the data** — when HR is unreliable, decoupling, RHR/HRV, heat/alcohol/sleep/travel confounds | `references/data-confounds.md` |
+| **A specific citation / PMID / DOI** | `references/citations.md` |
+
+### Plan & protocol templates (assets)
+
+| Template | Use when |
+|---|---|
+| `assets/plan-template-base.md` | Building a base mesocycle, backward-mapped from an A-race |
+| `assets/plan-template-build.md` | Building a build block that integrates VO2, durability, and strength |
+| `assets/field-test-durability.md` | Running the ~1,500 kJ → 1-min hill durability field test |
+
+## Operating principles
+
+1. **Cite as you reason.** Every quantitative recommendation should name its source (author/year;
+   full identifier in `references/citations.md`). This is so the athlete can verify, not just trust.
+2. **Separate mechanism from dose.** Where a doc marks a protocol
+   `⚠️ under-researched — track individual response`, present it as a hypothesis to test on this
+   athlete, not a fixed prescription.
+3. **Power governs; HR is conditional.** Prescribe from power. Use HR only where it is reliable
+   (durability decoupling on steady rides, recovery trends) and always screen for the confounds in
+   `references/data-confounds.md`. Never apply naive single-number rules
+   (e.g. "decoupling <5% = fresh", "RHR +5 = overtrained") without those caveats.
+4. **Distribution is a principle, not a recipe.** Training age, volume, life stress, and phase
+   decide the intensity distribution — see `references/periodization.md`.
+5. **Don't over-transfer.** Keep discipline-specific numbers labelled; small-n elite XCO data does
+   not automatically apply to masters marathon riders.

assets/field-test-durability.md

@@ -0,0 +1,51 @@
+# Durability field test — fatigued-state power on a fixed hill
+
+A repeatable field test for **fatigue resistance**: how much of your fresh power survives after
+substantial work. Fatigued-state power discriminates real-world cycling performance better than
+fresh power (see `references/durability.md` and `references/citations.md`).
+
+> ⚠️ **Under-researched dose.** The *concept* is well supported; the *optimal* kJ pre-load and
+> effort length are not standardized. Treat the numbers below as a sensible, repeatable default —
+> hold them **constant** across tests so the comparison is valid, and track your own response.
+
+## The protocol
+
+**Fresh baseline (do once, on a rested day):**
+- Warm up, then a maximal **1-minute effort** on your chosen fixed hill.
+- Record: average power, the segment, gearing, and conditions. This is your *fresh* anchor.
+
+**Fatigued test (the actual durability measure):**
+1. Ride until you have accumulated **~1,500 kJ of work** (typically ~2.5 h; read the kJ total from
+   the MCP `get_activity_*` data / head unit — do **not** estimate it by feel). Keep this ride
+   mostly endurance so the fatigue is from *duration*, not a second hard effort.
+2. Immediately do the **same 1-minute maximal effort on the same hill**, same gearing.
+3. Record average power.
+
+**The number that matters:**
+```
+Durability % = fatigued 1-min power ÷ fresh 1-min power × 100
+```
+Higher = more durable. Track the *trend* across a season, not a single value.
+
+## Keep it a valid comparison (hold these constant)
+
+| Variable | Why it must be fixed |
+|---|---|
+| The hill / segment & gearing | Grade and cadence change the power–speed relationship |
+| The **1,500 kJ** pre-load | The whole point is matched accumulated work |
+| Nutrition during the pre-load | Glycogen status drives fatigued power; fuel it consistently |
+| Time of day, rough temperature | Heat and circadian effects move power (`references/data-confounds.md`) |
+
+## Reading it
+
+- **Prescribe and judge from power, not HR.** HR after 1,500 kJ is confounded by cardiac drift,
+  heat, and fueling — use it only as a secondary decoupling signal (`references/data-confounds.md`).
+- A rising durability % across a block, with fresh power flat or up, is the signal you want.
+- A durability % that only holds when overall training load is high is *expected* — durability
+  depends on sustained load, unlike fresh power (see Spragg et al. in `references/citations.md`).
+
+## Logging it back to Intervals.icu
+
+Record the fresh and fatigued efforts as tagged activities/intervals, or note the durability % in
+the activity message / wellness comment, so the MCP server can retrieve the series later. This
+skill does not store data — Intervals.icu does.

assets/plan-template-base.md

@@ -0,0 +1,62 @@
+# Plan template — base mesocycle (backward-mapped from an A-race)
+
+A fill-in skeleton for a **base** block. This is a *knowledge template*, not a calculator — pull
+every number (current CTL/ATL/TSB, FTP, MAP, TSS) from the Intervals.icu MCP server and reason with
+the logic in `references/periodization.md`.
+
+## Step 0 — anchor to the A-race (backward mapping)
+
+```
+A-race date:            __________
+Weeks until A-race:     __________
+Race demands:           (road/TT? MTB/XCO? marathon? — see references/mtb-xco-demands.md)
+Target race-week TSB:   +5 to +15   (see periodization.md → taper)
+Current CTL / ATL / TSB: ____ / ____ / ____   (from MCP get_athlete_summary)
+```
+Work **backwards**: peak → build → base. Base's job is to raise sustainable CTL and aerobic
+durability so the build block has something to sharpen.
+
+## Step 1 — mesocycle rhythm
+
+| Athlete profile | Loading rhythm |
+|---|---|
+| Younger / high recoverability | **3:1** (3 build weeks : 1 recovery week) |
+| **Masters / higher life stress** | **2:1** (2 build : 1 recovery) — favors recovery |
+
+Pick one and hold it. Recovery weeks are ~40–60% of the preceding load week's TSS.
+
+## Step 2 — weekly shape (base phase)
+
+Base is **mostly low intensity with a small hard dose kept alive.** Distribution is a principle,
+not a recipe (Seiler — see `references/periodization.md`): let volume, training age, and life
+stress set the exact split.
+
+```
+Weekly TSS target:        ____  (ramp CTL ~3–7 pts/week; see periodization.md → CTL ramp)
+Long endurance ride:      1 × ____ h   (durability driver — see references/durability.md)
+Endurance / Z2 rides:     __ × ____ h
+Aerobic-support intensity: 1 × threshold OR sub-threshold session (keep top-end from decaying)
+Strength:                 2 × /week heavy (see strength-for-cyclists.md; from-zero ramp if new)
+Recovery / off:           as needed
+```
+
+## Step 3 — build in durability early
+
+- Progressively lengthen the long ride; late in base, place **fatigued-state efforts late** in the
+  long ride (hard work after accumulated kJ) — see `references/durability.md`.
+- Fuel these to spare glycogen; the point is durability, not depletion.
+- Schedule the durability field test (`field-test-durability.md`) at the **start and end** of base
+  to measure the block.
+
+## Step 4 — strength through base
+
+- Base is the ideal time to build heavy-strength capacity: 2×/week, heavy compound lifts, 3–6 reps.
+- Sequence strength-first or on separate days to mute interference (`references/strength-for-cyclists.md`).
+- Plan to **preserve** (not abandon) strength into build/in-season — 1×/week maintenance.
+
+## Checkpoints (pull from MCP, judge with the skill)
+
+- [ ] CTL ramp within target (not runaway) — `get_athlete_summary`
+- [ ] Recovery weeks actually recovered — wellness trend, `references/data-confounds.md`
+- [ ] Durability % improving across the block — `field-test-durability.md`
+- [ ] Strength load progressing — logged sessions

assets/plan-template-build.md

@@ -0,0 +1,66 @@
+# Plan template — build block (VO2 + durability + strength)
+
+A fill-in skeleton for a **build** mesocycle that sharpens the aerobic engine while preserving the
+base's durability and strength gains. A *knowledge template*, not a calculator — pull all metrics
+(CTL/ATL/TSB, FTP, MAP, TSS) from the Intervals.icu MCP server; reason with the referenced docs.
+
+## Position in the season
+
+Build sits between base and peak (backward-mapped from the A-race — see
+`assets/plan-template-base.md` and `references/periodization.md`). Its job: raise sustained power at
+and above threshold, add race-specific top-end, and keep durability from base intact.
+
+```
+Weeks of build:              __________
+Weeks until A-race:          __________
+Current CTL / ATL / TSB:     ____ / ____ / ____   (MCP get_athlete_summary)
+Primary limiter this block:  (VO2max? threshold? repeatability? — pick ONE emphasis)
+Race demands:                (road/TT steady? MTB/XCO intermittent? — mtb-xco-demands.md)
+```
+
+## Mesocycle rhythm
+
+Same as base: **3:1** (higher recoverability) or **2:1** (masters / high life stress). Build weeks
+carry more *intensity*, so recovery weeks matter more, not less.
+
+## Weekly shape (build phase)
+
+Fewer but sharper hard sessions. **Getting enough quality hard sessions in tends to matter more
+than the exact polarized-vs-pyramidal label** — a heuristic grounded in Seiler 2024, not a
+quantified law (see `references/periodization.md`). A common shape:
+
+```
+VO2max session:     1–2 × /week   (see references/vo2max-intervals.md for rep length / work:rest)
+Threshold / race-specific: 1 × /week   (or fold into the durability ride for MTB)
+Long durability ride: 1 × ____ h with hard efforts placed LATE (references/durability.md)
+Endurance / Z2:     fill remaining volume — protect the low end
+Strength (maintenance): 1 × /week heavy, low volume (references/strength-for-cyclists.md)
+Recovery / off:     as needed
+```
+
+### VO2max prescription (from `references/vo2max-intervals.md`)
+- Goal is **maximizing time ≥90% VO2max**, not just "going hard."
+- **No rep length is proven superior in cycling.** Default to **medium reps (~2–4 min, near the
+  pooled ~140 s optimum)** at ~0.85 work:rest; use short (30/15 s) or long (4–5 min) by athlete and
+  goal. Do not assume "longer is better" — see the modality conflict in `references/vo2max-intervals.md`.
+- Prescribe from **power**; for MTB, HR will lag and mislead (`references/data-confounds.md`).
+
+## Keep durability alive
+
+- Maintain at least one long ride; add fatigued-state efforts late (hard work after accumulated
+  kJ). Durability decays if overall load drops (Spragg et al. — `references/citations.md`).
+- Re-run the durability field test (`assets/field-test-durability.md`) at block end to confirm it
+  held while you added intensity.
+
+## Preserve strength (don't drop it)
+
+- **1×/week heavy maintenance** retains in-season strength gains; interference is muted with
+  strength-first/separate-day sequencing and at older age (`references/strength-for-cyclists.md`).
+
+## Checkpoints (pull from MCP, judge with the skill)
+
+- [ ] VO2 sessions actually spending time ≥90% VO2max (power sustained across reps) — streams/intervals
+- [ ] TSB not chronically buried — `get_athlete_summary`; screen wellness (`data-confounds.md`)
+- [ ] Durability % holding or rising — `field-test-durability.md`
+- [ ] Race-specific demand rehearsed (steady TT vs intermittent MTB) — `mtb-xco-demands.md`
+- [ ] Strength maintained — logged sessions

references/citations.md

@@ -0,0 +1,195 @@
+# Master citation list
+
+The single source of truth for every quantitative claim in this skill. Each entry: full citation,
+PMID/DOI, and a **confidence flag** from verification against PubMed / DOI resolvers.
+
+**Confidence key:**
+- ✅ **Confirmed** — PMID and/or DOI verified; title, authors, journal internally consistent.
+- ⚠️ **Confirmed metadata, claim = commonly-cited/approximate** — the paper exists as cited, but the
+  exact number attributed to it is widely-repeated rather than verified word-for-word in the source.
+- ❌ **Not found** — could not be confirmed; **do not cite as fact.**
+
+Verified as of 2026-07-20.
+
+---
+
+## Durability / fatigue resistance
+
+**✅ Muriel et al. 2022** — fatigued-state power differentiates riders; fresh power does not.
+Muriel X, Mateo-March M, Valenzuela PL, Zabala M, Lucia A, Pallarés JG, Barranco-Gil D. *Durability
+and repeatability of professional cyclists during a Grand Tour.* Eur J Sport Sci. 2022;22(12):
+1797–1804. **PMID 34586952 · DOI 10.1080/17461391.2021.1987528.**
+
+**✅ Spragg, Leo & Swart 2023 (training characteristics)** — durability tracks accumulated
+volume/load; fatigued profile varies more than fresh across a season. *This is the primary "load
+dependency" cite.* Spragg J, Leo P, Swart J. *The relationship between training characteristics and
+durability in professional cyclists across a competitive season.* Eur J Sport Sci. 2023;23(4):
+489–498. **PMID 35239466 · DOI 10.1080/17461391.2022.2049886.**
+> The crisp "reduced load maintains fresh power; sustained load maintains durability" phrasing is
+> Spragg's applied *interpretation* of this data — attribute as commentary, not a quoted result.
+
+**✅ Spragg, Leo & Swart 2023 (physiological characteristics)** — physiological correlates of
+durability (higher VO2max, gross efficiency, fat oxidation). Spragg J, Leo P, Swart J. *The
+Relationship between Physiological Characteristics and Durability in Male Professional Cyclists.*
+Med Sci Sports Exerc. 2023;55(1):133–140. **PMID 35977108 · DOI 10.1249/MSS.0000000000003024.**
+
+**✅ Maunder et al. 2021** — canonical definition of durability as a distinct profiling quality.
+Maunder E, Seiler S, Mildenhall MJ, Kilding AE, Plews DJ. *The Importance of 'Durability' in the
+Physiological Profiling of Endurance Athletes.* Sports Med. 2021;51(8):1619–1628.
+**PMID 33886100 · DOI 10.1007/s40279-021-01459-0.**
+
+---
+
+## MTB / XCO demands
+
+**✅ Hays et al. 2018** — XCO demand profile (~25% time above MAP; hard start); HR/power/VO2
+dissociation (VO2 high on descents, %VO2max uncorrelated with %HRmax/%MAP). Hays A, Devys S, Bertin
+D, Marquet LA, Brisswalter J. *Understanding the Physiological Requirements of the Mountain Bike
+Cross-Country Olympic Race Format.* Front Physiol. 2018;9:1062.
+**PMID 30158873 · DOI 10.3389/fphys.2018.01062.**
+
+**✅ Prinz et al. 2021** — corroborating hard-number demand data (~30% top zone; 334 efforts ~4.3 s
+at ~135% MAP). Prinz B, et al. *(power-profile / demands of XCO)* Int J Sports Physiol Perform. 2021.
+**PMID 33848975 · DOI 10.1123/ijspp.2020-0758.**
+
+**✅ Protzen et al. 2026** — systematic review: contemporary XCO shifted toward greater anaerobic
+contribution while maintaining high aerobic demand; ~¼ race time above MAP. Protzen G, Inoue A,
+Buzzachera CF, Doma K, Devantier-Thomas B, Herrero-Molleda A, García-López J, Boullosa D. *The
+Physiology of Contemporary Olympic Cross-Country Mountain Biking: A Systematic Review.* Sports Med
+Open. 2026;12:16. **PMID 41739301 · DOI 10.1186/s40798-026-00976-4.**
+
+**✅ Impellizzeri et al. 2005** — aerobic predictors of XCO (mass-normalized threshold power/VO2).
+*Frame r ≈ 0.6–0.9 as "across studies"; the elite-cohort raw VO2max did not separate riders.*
+Impellizzeri FM, Marcora SM, Rampinini E, Mognoni P, Sassi A. *Correlations between physiological
+variables and performance in high level cross country off road cyclists.* Br J Sports Med.
+2005;39(10):747–751. **PMID 16183772 · DOI 10.1136/bjsm.2004.017236.**
+
+**✅ Inoue et al. 2012** — anaerobic power predicts XCO race time (r = −0.79, p = 0.006). Inoue A,
+Sá Filho AS, Mello FCM, Santos TM. *Relationship between anaerobic cycling tests and mountain bike
+cross-country performance.* J Strength Cond Res. 2012;26(6):1589–1593.
+**PMID 21912290 · DOI 10.1519/JSC.0b013e318234eb89.**
+
+**✅ Sánchez-Jiménez et al. 2025** — fatigue-decline magnitudes: Top-10 ~6–10% vs lower ~15–20%.
+Sánchez-Jiménez L, Javaloyes A, Peña-González I, Moya-Ramón M, Mateo-March M. *Record Power Profile
+in Elite Olympic Cross-Country Mountain Bike Cyclists: Normative Values and Fatigue Effects.* Scand
+J Med Sci Sports. 2025;35(11):e70170. **PMID 41285697 · DOI 10.1111/sms.70170.**
+
+**✅ Novak et al. 2018** — marathon (4-h) MTB predictors differ from lap XCO. Novak AR, Bennett KJM,
+Fransen J, Dascombe BJ. *Predictors of performance in a 4-h mountain-bike race.* J Sports Sci.
+2018;36(4):462–468. **PMID 28406361 · DOI 10.1080/02640414.2017.1313999.**
+
+---
+
+## Strength training (incl. masters)
+
+**✅ Llanos-Lagos et al. 2026 (epub 2025)** — meta-analysis, 17 studies / 262 cyclists: heavy
+strength improves efficiency, anaerobic power, TT performance; **no VO2max effect**. Llanos-Lagos C,
+Ramírez-Campillo R, Sáez de Villarreal E. *Heavy strength training effects on physiological
+determinants of endurance cyclist performance: a systematic review with meta-analysis.* Eur J Appl
+Physiol. 2026;126(1):193–222. **PMID 40632222 · DOI 10.1007/s00421-025-05883-2.** *(Certainty of
+evidence noted as low by the authors.)*
+
+**✅ Cadore et al. 2013 (epub 2012)** — strength-first sequencing yields greater strength gains in
+the elderly (~35% vs ~22%). Cadore EL, Izquierdo M, Pinto SS, et al. *Neuromuscular adaptations to
+concurrent training in the elderly: effects of intrasession exercise sequence.* Age (Dordr).
+2013;35(3):891–903. **PMID 22453934 · DOI 10.1007/s11357-012-9405-y.** *(This is the "Cadore 2012"
+sequencing cite.)*
+
+**✅ Cadore & Izquierdo 2013** — interference manageable/muted in older adults except at high
+volume/frequency. Cadore EL, Izquierdo M. *How to simultaneously optimize muscle strength, power,
+functional capacity, and cardiovascular gains in the elderly: an update.* Age (Dordr).
+2013;35(6):2329–2344. **PMID 23288690 · DOI 10.1007/s11357-012-9503-x.**
+
+**⚠️ English & Paddon-Jones 2010** — commonly cited origin of "~8% muscle loss/decade after 40."
+*Exact figure not verified in abstract; treat as commonly-cited/approximate.* English KL, Paddon-
+Jones D. *Protecting muscle mass and function in older adults during bed rest.* Curr Opin Clin Nutr
+Metab Care. 2010;13(1):34–39. **PMID 19898232 · DOI 10.1097/MCO.0b013e328333aa66.**
+
+**✅ Volpi, Nazemi & Fujita 2004** — sarcopenia mechanisms; resistance/aerobic training as
+countermeasure (fiber-type-fastest specifics not verbatim-confirmed). Volpi E, Nazemi R, Fujita S.
+*Muscle tissue changes with aging.* Curr Opin Clin Nutr Metab Care. 2004;7(4):405–410.
+**PMID 15192443 · DOI 10.1097/01.mco.0000134362.76653.b2.**
+
+**✅ Cruz-Jentoft et al. 2019 (EWGSOP2)** — consensus: sarcopenia centers on muscle strength;
+resistance training recommended. *Strongest confirmed cite for "loaded resistance is the primary
+countermeasure."* Cruz-Jentoft AJ, et al. *Sarcopenia: revised European consensus on definition and
+diagnosis.* Age Ageing. 2019;48(1):16–31. **PMID 30312372 · DOI 10.1093/ageing/afy169.**
+
+---
+
+## VO2max intervals
+
+**✅ Yang, Wang & Guan 2025** — network meta-analysis, 51 studies / 1,261 athletes: inverted-U
+dose-response; optimum ~140 s work, work:rest ~0.85. *Weighted toward running-based HIIT.* Yang Q,
+Wang J, Guan D. *Comparison of different interval training methods on athletes' oxygen uptake: a
+systematic review with pairwise and network meta-analysis.* BMC Sports Sci Med Rehabil.
+2025;17(1):156. **PMID 40605061 · DOI 10.1186/s13102-025-01191-6.**
+
+**✅ Fleckenstein, Braunstein & Walter 2025** — *running*: long (3-min) intervals accumulate more
+time >90% VO2max than intensified 30-s intervals. Fleckenstein D, Braunstein H, Walter N. *Faster
+intervals, faster recoveries — intensified short VO2max running intervals are inferior to
+traditional long intervals in terms of time spent above 90% VO2max.* Front Sports Act Living.
+2025;6:1507957. **PMID 39835194 · DOI 10.3389/fspor.2024.1507957.**
+
+**✅ Rønnestad & Hansen 2016** — *cycling, opposite result*: 30-s intervals induced more time ≥90%
+VO2peak than longer intervals. Rønnestad BR, Hansen J. *Optimizing Interval Training at Power Output
+Associated With Peak Oxygen Uptake in Well-Trained Cyclists.* J Strength Cond Res. 2016;30(4):
+999–1006. **PMID 23942167 · DOI 10.1519/JSC.0b013e3182a73e8a.** *(Often mis-cited as 2013 = epub.)*
+
+**✅ Rønnestad et al. 2020** — *cycling*: short (30/15 s) beat effort-matched long (5-min) intervals
+over 3 weeks (+4.7% 20-min power) in elite cyclists. Rønnestad BR, Hansen J, Nygaard H, Lundby C.
+*Superior performance improvements in elite cyclists following short-interval vs effort-matched
+long-interval training.* Scand J Med Sci Sports. 2020;30(5):849–857.
+**PMID 31977120 · DOI 10.1111/sms.13627.**
+
+**✅ Almquist et al. 2020** — effort-matched acute systemic/muscular responses favor short intervals.
+Almquist NW, Nygaard H, Vegge G, Hammarström D, Ellefsen S, Rønnestad BR. *Systemic and muscular
+responses to effort-matched short intervals and long intervals in elite cyclists.* Scand J Med Sci
+Sports. 2020;30(7):1140–1150. **PMID 32267032 · DOI 10.1111/sms.13672.**
+
+**✅ Rønnestad et al. 2021** — microcycle shock-block: short intervals → superior adaptations.
+Rønnestad BR, Øfsteng SJ, Zambolin F, Raastad T, Hammarström D. *Superior Physiological Adaptations
+After a Microcycle of Short Intervals Versus Long Intervals in Cyclists.* Int J Sports Physiol
+Perform. 2021;16(10):1432–1438. **PMID 33735833 · DOI 10.1123/ijspp.2020-0647.**
+
+> **Caveat on the cycling short-interval body of work (Rønnestad 2016/2020/2021 + Almquist 2020):**
+> the short-interval superiority comes chiefly from a **single research group**, and its adaptation
+> claims are challenged by effort-matched work: when **total work duration** is matched, the
+> advantage reportedly disappears (attributed to a Seiler-group study — **unpublished /
+> secondary-source, low evidence tier, not cited as fact**). Present short-interval superiority as a
+> *lab-consistent but not independently settled* finding, not a cycling consensus. See
+> `vo2max-intervals.md`.
+
+**❌ "Effort-matched cycling replication, no difference" (Seiler group)** — **NOT VERIFIABLE as a
+primary source.** Referenced only via secondary/coaching sources as an unpublished master's thesis
+(~30 cyclists, VO2max ~64, total-work-matched, no short-vs-long difference). Used only to *temper*
+overconfidence in the short-interval side; **do not cite as established evidence.**
+
+---
+
+## Distribution / periodization philosophy
+
+**✅ Seiler 2024** — "long game, not epic workouts"; HIIT is not an acute-maximization problem;
+polarized training as a context-dependent principle. Peer-reviewed Perspective (open access). Seiler
+S. *It's about the long game, not epic workouts: unpacking HIIT for endurance athletes.* Appl
+Physiol Nutr Metab. 2024;49(11):1585–1599. **PMID 39079169 · DOI 10.1139/apnm-2024-0012.**
+
+**✅ Sun, Yu et al. 2025** — review of training-intensity-distribution models: **no single model
+universally superior**; adapt to sport/phase/athlete. *(Use for the "distribution is context-
+dependent" point — it does NOT claim frequency > distribution.)* Sun Q, Yu Y, Cui J, Lin S, Wang X,
+Zhou T. *Recent advances in training intensity distribution theory for cyclic endurance sports.*
+Front Physiol. 2025;16:1657892. **PMID 41169886 · DOI 10.3389/fphys.2025.1657892.**
+
+**❌ "Yu et al. 2025" (frequency > distribution)** — **NOT FOUND.** No PubMed paper with Yu as first
+author making this specific claim could be located. **Do not cite.** The nearest real paper
+(Sun/Yu 2025, above) does not support "frequency outweighs distribution." Ground the frequency point
+in Seiler 2024 instead, and label it a heuristic, not a quantified finding.
+
+---
+
+## Notes on verification method
+
+All ✅ identifiers were read from PubMed record pages and cross-checked against DOI resolvers by
+independent verification agents on 2026-07-20. Where a claim's *number* is widely repeated but not
+verbatim in the source abstract, it is marked ⚠️ and the reference docs say so inline. No identifier
+in this list was fabricated; the one unlocatable citation is explicitly marked ❌.

references/data-confounds.md

@@ -0,0 +1,76 @@
+# Data confounds — when to trust HR, RHR, HRV, and decoupling
+
+**Load this doc when:** interpreting heart rate, resting HR, HRV, sleep, or aerobic decoupling —
+i.e. any time a number is about to drive a training decision.
+
+**Data/knowledge split:** MCP gives you the raw and computed signals (HR streams, RHR, HRV, sleep,
+readiness, decoupling). This doc governs **whether that signal is trustworthy today** and forbids
+naive single-number rules.
+
+---
+
+## Core stance: power governs; HR is conditional
+
+**Prescribe from power.** Heart rate is a *response* variable contaminated by many non-training
+factors. Use HR only where it is genuinely informative:
+- **Aerobic decoupling on steady rides** (Pw:HR drift) — valid only on steady efforts.
+- **Recovery trends** (RHR, HRV) — as *trends*, screened for the confounds below.
+
+Do **not** use HR to prescribe or judge intensity for **intermittent** efforts — see the MTB
+dissociation below.
+
+## The confounds (screen every HR-based signal against these)
+
+Any of these can move HR, RHR, HRV, or decoupling independent of fitness or fatigue:
+
+| Confound | Effect | Implication |
+|---|---|---|
+| **Heat / dehydration** | ↑ HR, ↑ cardiac drift, ↑ decoupling | High decoupling on a hot ride ≠ poor fitness |
+| **Alcohol** (prior evening) | ↑ RHR, ↓ HRV, disrupted sleep | A bad HRV morning after drinking is not overtraining |
+| **Travel** (jet lag, altitude, transit) | ↑ RHR, ↓ HRV, poor sleep | Expected; not a training signal |
+| **Poor / short sleep** | ↑ RHR, ↓ HRV, ↑ perceived effort | Fatigue signal, but from sleep — adjust the day, don't panic |
+| **Illness / stress / caffeine timing** | ↑ RHR, altered HRV | Interpret in context, not in isolation |
+| **Intermittent effort (MTB)** | HR lags surges; VO2 stays high on descents | HR mis-reads MTB intensity entirely (see below) |
+
+## ⚠️ The MTB / intermittent-effort dissociation
+
+In intermittent off-road riding, **HR, power, and VO2 dissociate**: VO2 stays elevated on descents
+where power drops, and HR lags the short bursts that define the effort. In XCO, %VO2max did **not**
+correlate with %HRmax or %MAP (Hays et al. 2018, *Front Physiol* 9:1062; PMID 30158873;
+DOI 10.3389/fphys.2018.01062). **For MTB, HR is unreliable for intensity — power governs.** See
+`mtb-xco-demands.md`.
+
+## Do NOT hardcode naive rules
+
+These single-number rules are **wrong as written** because they ignore the confounds above:
+
+- ❌ "**Decoupling < 5% = fresh / fit**." Decoupling is inflated by heat, dehydration, fueling, and
+  any non-steady effort. It is only interpretable on a **steady** ride in **controlled conditions**,
+  and even then as a **trend**, not a threshold. High decoupling on a hot, long, or surgey ride tells
+  you little about fitness.
+- ❌ "**RHR + 5 bpm = overtrained**." A single elevated RHR morning is far more often alcohol,
+  short sleep, travel, heat, or illness. Overtraining/non-functional overreaching is a **multi-signal,
+  multi-day** picture (RHR trend + HRV trend + performance + mood + sleep + training load), never one
+  morning's number.
+
+**The correct pattern:** look at **trends across days**, **corroborate across signals** (RHR + HRV +
+sleep + performance + subjective), and **explain-away confounds first** before attributing a change
+to training fatigue.
+
+## Using decoupling for durability (the one HR job that's valid)
+
+On a **steady** endurance ride, Pw:HR decoupling is a reasonable aerobic-durability signal: as
+aerobic fitness/durability improves, HR drifts less for the same power late in a long ride. Use it:
+- Only on **steady** rides (not intervals, not MTB).
+- Only when **conditions are controlled** (not a heat outlier, not dehydrated, not post-alcohol).
+- As a **trend** across comparable rides, alongside the power-based durability field test
+  (`../assets/field-test-durability.md`), which is the more direct measure.
+
+## Practical workflow
+
+1. Pull the signal from MCP (HR stream, RHR, HRV, sleep, decoupling, readiness).
+2. **Screen for confounds** (table above). If a confound is present, discount the signal.
+3. **Corroborate** across signals and across days before acting.
+4. **Prescribe from power**; use HR only for steady decoupling and recovery trends.
+5. When signals conflict and confounds are present, **default to caution** (easier day) rather than
+   trusting one number in either direction.

references/durability.md

@@ -0,0 +1,76 @@
+# Durability / fatigue resistance
+
+**Load this doc when:** the question is about fatigue resistance, why late-race power fades,
+training the ability to hold power deep into long efforts, or running the durability field test.
+
+**Data/knowledge split:** the MCP server gives you the kJ, power curves, and fatigued-vs-fresh
+efforts. This doc explains *why fatigued-state power matters* and *how to train it*.
+
+---
+
+## Durability is a distinct, trainable quality
+
+"Durability" is the time of onset and the magnitude of deterioration in physiological-profiling
+variables (thresholds, efficiency, power) over the course of prolonged exercise — a quality that
+should be profiled **separately** from fresh-state numbers, because two riders with identical fresh
+profiles can fall apart very differently after several hours (Maunder et al. 2021, *Sports Med*
+51(8):1619–1628; PMID 33886100; DOI 10.1007/s40279-021-01459-0).
+
+### Why it matters more than fresh power
+
+- In professional cyclists across a Grand Tour, **fresh** mean-maximal power did **not** separate
+  WorldTour from ProTeam riders — but as work accumulated (0 → 35 kJ·kg⁻¹), WorldTour riders held
+  higher power. **Fatigued-state power differentiated performance; fresh power did not**
+  (Muriel et al. 2022, *Eur J Sport Sci* 22(12):1797–1804; PMID 34586952;
+  DOI 10.1080/17461391.2021.1987528).
+- The **fatigued** power profile varies far more across a season than the fresh profile, and it
+  tracks with **training characteristics (accumulated volume/load)** — meaning durability is
+  something you build with training, not a fixed trait (Spragg, Leo & Swart 2023, *Eur J Sport Sci*
+  23(4):489–498; PMID 35239466; DOI 10.1080/17461391.2022.2049886).
+
+## The load dependency (the key training implication)
+
+**Durability depends on maintaining high overall training load, whereas fresh power can be held on
+reduced load.** You can taper volume and keep your 5-min power; you cannot taper volume for long
+and keep your *fatigued* 5-min power. This is the empirical thrust of the Spragg training-
+characteristics paper (PMID 35239466); the crisp "reduced load keeps fresh power, sustained load
+keeps durability" phrasing is Spragg's applied interpretation of that data — cite it as such.
+
+Physiological correlates of *who* is durable (higher VO2max, better gross efficiency, higher fat-
+oxidation) come from the companion paper (Spragg, Leo & Swart 2023, *Med Sci Sports Exerc*
+55(1):133–140; PMID 35977108; DOI 10.1249/MSS.0000000000003024) — useful for understanding
+mechanism, but the *trainable lever* is sustained load + the practices below.
+
+## How to train durability
+
+1. **Long-term consistency and high volume.** Durability is a load-dependent adaptation — it is
+   built over blocks and lost when load drops. Protect the long ride.
+2. **Prolonged sessions with hard efforts placed late (fatigued-state intervals).** Put the quality
+   work *after* accumulated kilojoules, not at the fresh start of the ride — you are specifically
+   training the fatigued state that discriminates performance.
+3. **Glycogen-sparing nutrition.** Fuel long sessions to spare glycogen; the goal is training the
+   durable state under realistic fueling, not chronic depletion. (Fatigued power is glycogen-
+   sensitive — see the fueling caveat in `data-confounds.md` for why HR is unreliable here.)
+
+> ⚠️ **Under-researched — track individual response.** The *mechanism* (load-dependent fatigue
+> resistance) is well supported, but the **optimal durability dose** — how much accumulated work,
+> how often, how late to place efforts — is not established. **Do not assume a fixed protocol.**
+> Track each athlete's fatigued-state response and titrate.
+
+## Measure it: the fatigued-state field test
+
+Use `../assets/field-test-durability.md`. In brief:
+- Establish a **fresh** 1-min max on a fixed hill.
+- On a separate day, accumulate **~1,500 kJ (~2.5 h)** of mostly-endurance riding, then repeat the
+  **same 1-min max on the same hill**.
+- `Durability % = fatigued ÷ fresh × 100`. Track the trend across a block.
+- Hold the hill, gearing, kJ pre-load, and fueling **constant** so the comparison is valid.
+- **Judge from power, not HR** — HR after 1,500 kJ is confounded by drift, heat, and fueling
+  (`data-confounds.md`).
+
+## Discipline note
+
+Durability matters for both road/TT and MTB, but **keep absolute numbers discipline-specific.** The
+1,500 kJ anchor is a sensible generic default, not a validated cross-discipline constant; a masters
+marathon-MTB rider and an elite road pro do not share a durability dose. See `mtb-xco-demands.md`
+for how fatigue resistance shows up specifically in off-road racing.

references/mtb-xco-demands.md

@@ -0,0 +1,73 @@
+# MTB / XCO demand profile (and why power governs off-road)
+
+**Load this doc when:** planning for mountain-bike racing, deciding MTB-specific workouts, or
+questioning whether HR is trustworthy off-road.
+
+**Data/knowledge split:** MCP gives you the power streams, HR, and interval stats from a ride. This
+doc explains what the *demand profile* is and why, for MTB, **you prescribe and judge from power,
+not HR.**
+
+---
+
+## The demand profile: intermittent, explosive, anaerobically shifted
+
+XCO (Olympic cross-country) racing is **intermittent and explosive**: a hard start followed by
+repeated high-intensity bursts, with roughly **25% of race time spent above maximal aerobic power
+(MAP)** in brief 5–10 s efforts, on top of a hard first-lap start (Hays et al. 2018, *Front Physiol*
+9:1062; PMID 30158873; DOI 10.3389/fphys.2018.01062). A corroborating dataset reports ~30% of time
+in the top zone across 334 efforts averaging ~4.3 s at ~135% MAP (Prinz et al. 2021, *IJSPP*;
+PMID 33848975).
+
+Contemporary XCO has **shifted toward greater anaerobic contribution while maintaining high aerobic
+demand** — you need both engines (Protzen et al. 2026, *Sports Med Open* 12:16; PMID 41739301;
+DOI 10.1186/s40798-026-00976-4).
+
+## Both aerobic and anaerobic power independently predict performance
+
+- **Aerobic:** body-mass–normalized aerobic/threshold indices correlate strongly with XCO race time.
+  Reported correlations across the literature sit in the **r ≈ 0.6–0.9** range, but note the classic
+  elite-cohort study found raw VO2max/peak power did **not** separate riders — the significant
+  correlations were for **mass-normalized threshold** power/VO2 (Impellizzeri et al. 2005,
+  *Br J Sports Med* 39(10):747–751; PMID 16183772; DOI 10.1136/bjsm.2004.017236). **Frame the
+  0.6–0.9 as "across studies," not one clean value.**
+- **Anaerobic:** maximal power in a 5×30 s Wingate protocol correlated **r = −0.79** (p = 0.006) with
+  XCO race time — anaerobic power independently predicts performance (Inoue et al. 2012, *J Strength
+  Cond Res* 26(6):1589–1593; PMID 21912290; DOI 10.1519/JSC.0b013e318234eb89). *(The correlation is
+  negative because higher power = lower/faster race time.)*
+
+**Training implication:** develop both. Aerobic base/VO2max (`vo2max-intervals.md`) *and* anaerobic/
+repeated-sprint power and strength (`strength-for-cyclists.md`). Neither alone covers the demand.
+
+## Fatigue resistance separates the field
+
+Higher-performing MTB riders decline **less** under fatigue. Across 693 elite male XCO race files,
+power under fatigue fell ~**6–10%** in Top-10 riders vs ~**15–20%** in lower-ranked riders (p from
+0.008 to <0.001) — durability is decisive off-road (Sánchez-Jiménez et al. 2025, *Scand J Med Sci
+Sports* 35(11):e70170; PMID 41285697; DOI 10.1111/sms.70170). Train it via `durability.md`.
+
+## ⚠️ The HR caveat (read this before prescribing MTB intensity by HR)
+
+In intermittent MTB racing, **HR, power, and VO2 dissociate**:
+- **VO2 stays high on descents where power drops** — you're still consuming oxygen while barely
+  pedaling, so power under-reads true metabolic cost on descents.
+- **HR lags short efforts** — a 5–10 s surge is over before HR responds, so HR under-reads the
+  intensity of the bursts that define the sport.
+- In XCO, %VO2max did **not** correlate with %HRmax or %MAP (Hays et al. 2018, PMID 30158873).
+
+**Therefore: power governs MTB intensity; HR is unreliable for it.** Prescribe intervals, pacing,
+and race targets from power. Use HR only where it is valid — steady-state durability decoupling and
+recovery trends — and always screen the confounds in `data-confounds.md`. Do **not** set MTB
+interval targets or judge burst efforts by heart rate.
+
+## Discipline nuance: marathon/point-to-point ≠ lap XCO
+
+A 4-hour marathon MTB has **different performance predictors and pacing** than lap-based XCO
+(Novak et al. 2018, *J Sports Sci* 36(4):462–468; PMID 28406361; DOI 10.1080/02640414.2017.1313999).
+Marathon/point-to-point events (e.g. Iceman) are steadier and more sustained; lap XCO is punchier
+and more repeatedly supra-MAP.
+
+> ⚠️ **Don't over-transfer.** The XCO numbers above come largely from **small-n elite** samples.
+> A masters marathon rider does **not** inherit an elite XCO rider's ~25%-above-MAP profile or their
+> exact fatigue-decline percentages. Keep absolute numbers **discipline- and level-specific**, use
+> the *principles* (both engines matter; power governs; durability decides), and **track the
+> individual's own race files** via the MCP data rather than importing elite constants.

references/periodization.md

@@ -0,0 +1,83 @@
+# Periodization, distribution & taper
+
+**Load this doc when:** structuring a season, choosing an intensity distribution, setting a CTL
+ramp, or planning an A-race taper.
+
+**Data/knowledge split:** MCP supplies CTL / ATL / TSB, the load ramp, and TSS. This doc supplies
+the logic for *how fast to ramp*, *how to distribute intensity*, and *what TSB to target*.
+
+---
+
+## Distribution is a principle, not a recipe
+
+Do not treat polarized (or pyramidal) training as a fixed formula. The right distribution is
+**context-dependent** — set by training age, weekly volume, life stress, and the current phase.
+
+The framing to internalize: effective endurance training is **"the long game, not epic workouts."**
+HIIT should not be prescribed as an acute-response "maximization problem"; what matters is the
+**long-term integration** of intensity, duration, and **frequency**, adapted to the athlete's
+context (Seiler 2024, *Appl Physiol Nutr Metab* 49(11):1585–1599; PMID 39079169;
+DOI 10.1139/apnm-2024-0012 — a peer-reviewed Perspective, open access).
+
+**On "frequency matters more than the exact distribution":** this is a reasonable working heuristic
+consistent with Seiler's long-game argument, but note the honest state of evidence — a 2025 review
+of training-intensity-distribution models concludes **no single model is universally superior** and
+that model choice must be adapted to sport, phase, and athlete (Sun, Yu et al. 2025, *Front Physiol*
+16:1657892; PMID 41169886; DOI 10.3389/fphys.2025.1657892). Treat "get enough quality hard sessions
+in, don't obsess over polarized-vs-pyramidal labels" as a defensible principle, **not** a
+quantified finding.
+
+> **Citation honesty note:** a specific "Yu et al. 2025" paper claiming *frequency of hard sessions
+> outweighs distribution* could **not** be located in PubMed. Do not cite one. Ground the point in
+> Seiler 2024 (the long-game argument) and the Sun/Yu 2025 review (no model universally superior).
+> See `citations.md`.
+
+## Standard periodization: base → build → peak
+
+Work **backward from the A-race** (backward mapping). Each phase sets up the next.
+
+| Phase | Primary job | Emphasis |
+|---|---|---|
+| **Base** | Raise sustainable CTL, aerobic base, **durability**, and strength capacity | High volume, mostly low intensity, small hard dose kept alive; build heavy strength |
+| **Build** | Sharpen threshold & VO2max; add race-specific top-end; preserve durability & strength | Fewer, sharper hard sessions; strength → maintenance |
+| **Peak/Taper** | Shed fatigue, keep fitness, arrive fresh | Reduce volume, keep some intensity, hit TSB target |
+
+Templates: `../assets/plan-template-base.md`, `../assets/plan-template-build.md`.
+
+## Mesocycle rhythm
+
+| Athlete | Rhythm | Note |
+|---|---|---|
+| Younger / high recoverability | **3:1** (3 load weeks : 1 recovery) | Standard |
+| **Masters / higher life stress** | **2:1** (2 load : 1 recovery) | Favor recovery — masters recover slower; the 2:1 protects adaptation |
+
+Recovery weeks ≈ 40–60% of the preceding load week's TSS. These are *adaptation* weeks, not lost
+time — the fitness is expressed during them.
+
+## CTL ramp guidance
+
+- Ramp **CTL gradually** — a common, conservative guide is **~3–7 CTL points per week** sustained,
+  lower for masters or when life stress is high. Faster ramps raise injury/illness/overtraining
+  risk without proportional benefit.
+- Read the actual CTL/ATL/TSB and ramp rate from MCP (`get_athlete_summary`); this doc only tells
+  you whether the ramp is sane. A runaway ramp with a deeply negative TSB trend is a flag — cross-
+  check wellness before pushing (`data-confounds.md`).
+
+> ⚠️ **The CTL ramp numbers are heuristics, not laws.** Individual tolerance varies widely —
+> **track response** (wellness, performance, durability) rather than forcing a fixed points/week.
+
+## A-race taper & TSB targets
+
+- **Goal:** arrive with fitness intact and fatigue gone — a **positive but not deeply detrained
+  TSB**. A common target window is **TSB ≈ +5 to +15** on race day (higher for shorter/punchier
+  events where freshness dominates; lower for long events where fitness retention matters more).
+- **How:** cut **volume** substantially over the final 1–2 weeks while **keeping some intensity**
+  (short race-specific efforts) so you sharpen rather than go flat. Don't cut intensity to zero.
+- **Durability caveat:** durability decays if load drops too far for too long (`durability.md`). For
+  long/marathon events, taper less aggressively than for short punchy events, or you arrive fresh
+  but unable to hold late-race power.
+- Read TSB from MCP and steer it into the target window; this doc sets the target, MCP measures it.
+
+> ⚠️ **Taper TSB targets are individual.** The +5 to +15 window is a starting point; some riders
+> peak flat at +5, others need +15–20. **Track how the athlete has raced at known TSB values** and
+> personalize.

references/strength-for-cyclists.md

@@ -0,0 +1,87 @@
+# Heavy strength training for cyclists (with a masters focus)
+
+**Load this doc when:** deciding whether/how to add strength work, designing a lifting protocol
+for a cyclist, addressing age-related muscle loss, or planning in-season maintenance.
+
+The MCP server does not model strength; this is prescription logic. Log lifts as activities/notes in
+Intervals.icu so the load is visible, but the *what and why* lives here.
+
+---
+
+## The evidence: heavy strength helps cycling, without a VO2max penalty
+
+A 2025/2026 systematic review with meta-analysis (**17 studies, 262 cyclists**) found that heavy
+strength training significantly improved **cycling efficiency, anaerobic power, and time-trial
+performance** versus endurance training alone, with **no significant effect on VO2max** — the gains
+come through efficiency and anaerobic power, not aerobic capacity, and crucially **without costing
+VO2max** (Llanos-Lagos et al. 2026, *Eur J Appl Physiol* 126(1):193–222, epub 2025;
+PMID 40632222; DOI 10.1007/s00421-025-05883-2). Authors note the certainty of evidence is low —
+the direction is consistent, the magnitude is uncertain.
+
+## The protocol (what the literature actually used)
+
+| Parameter | Prescription |
+|---|---|
+| **Type** | **Heavy** compound lifts — *not* explosive/plyometric as the primary driver |
+| **Lifts** | Squat, deadlift, leg press (bilateral lower-body compounds) |
+| **Reps** | **3–6 reps** per set (heavy end; high load, low rep) |
+| **Frequency** | **1–3 ×/week** |
+| **Duration** | Sustained block of **5–25 weeks** to express benefits |
+| **In-season** | **Preserve it** — do not drop strength once racing starts |
+
+The consistent thread across the 17 studies: **heavy, low-rep, compound, sustained, and
+maintained.** Short dabbling blocks that get abandoned in-season are not what produced the results.
+
+## Why this matters more for masters athletes
+
+- Adults lose roughly **~8% of muscle mass per decade after age 40** (accelerating later in life),
+  and **type II (fast-twitch) fibers atrophy fastest** with aging — the exact fibers that power
+  sprints, surges, and the explosive demands of MTB/XCO.
+  - The "~8%/decade" figure is widely attributed to English & Paddon-Jones 2010 (*Curr Opin Clin
+    Nutr Metab Care* 13(1):34–39; PMID 19898232) but that exact sentence is **not verified in the
+    abstract** — treat the specific number as commonly-cited-but-approximate, not gospel. Fiber-type
+    and countermeasure biology: Volpi, Nazemi & Fujita 2004 (PMID 15192443); consensus definition
+    and resistance-training recommendation: Cruz-Jentoft et al. 2019 EWGSOP2 (*Age Ageing*
+    48(1):16–31; PMID 30312372). See `citations.md`.
+- **Loaded resistance training is the primary proven countermeasure** to this loss. Endurance
+  riding alone does not defend type II mass.
+- **The interference effect is muted at older age**, and further reduced with **strength-first
+  sequencing.** In elderly men, doing strength *before* endurance within a session produced larger
+  strength gains (~35% vs ~22%) than the reverse order (Cadore et al. 2013, *Age (Dordr)*
+  35(3):891–903, epub 2012; PMID 22453934). Interference in older adults is manageable except at
+  high weekly volume/frequency (Cadore & Izquierdo 2013, *Age (Dordr)* 35(6):2329–44;
+  PMID 23288690).
+
+**Practical sequencing:** lift on separate days from key bike sessions where possible; if combined,
+**strength first**, or put strength on easy/recovery riding days — never before a key VO2 or
+threshold session you care about.
+
+## From-zero ramp progression
+
+For a rider new to heavy lifting, build the movement and connective-tissue base **before** loading
+to 3–6RM. Progress by phase, not by calendar — advance only when the current phase's form is clean
+and soreness settles within ~48 h.
+
+| Phase | Weeks (guide) | Focus | Sets × reps | Load |
+|---|---|---|---|---|
+| **0. Movement** | 1–2 | Learn squat/hinge/press patterns; bodyweight & goblet | 2–3 × 8–10 | Very light; groove form |
+| **1. Anatomical adaptation** | 2–4 | Tendons/connective tissue; higher reps | 3 × 10–12 | Moderate; ~2 RIR |
+| **2. Strength build** | 4–6 | Transition toward heavy | 3–4 × 6–8 | Heavy-ish; ~1–2 RIR |
+| **3. Heavy strength** | ongoing | The evidence-based target | 3–5 × 3–6 | Heavy; ~1 RIR, form-limited |
+| **4. In-season maintenance** | racing | Retain gains, minimize fatigue | 1–2 × /wk, 2–3 × 3–5 | Heavy, low volume |
+
+*RIR = reps in reserve.* Masters athletes especially should keep 1+ RIR (form-limited, not
+failure-limited) to protect joints and recovery.
+
+> ⚠️ **Individualize the ramp.** The *effect* of heavy strength is well established; the ideal
+> per-athlete ramp speed, weekly frequency (1 vs 2 vs 3×), and in-season dose are not precisely
+> resolved — **track response** (strength progression, riding quality, recovery) and adjust.
+
+## How this integrates with the rest of the plan
+
+- **Base** is the best time to build heavy-strength capacity (2×/week) — see
+  `../assets/plan-template-base.md`.
+- **Build/in-season**: drop to **1×/week heavy maintenance** — see
+  `../assets/plan-template-build.md`.
+- Strength supports the **anaerobic/explosive** side that predicts MTB/XCO performance
+  (`mtb-xco-demands.md`) and the efficiency that helps steady TT power.

references/vo2max-intervals.md

@@ -0,0 +1,91 @@
+# VO2max interval optimization
+
+**Load this doc when:** designing high-intensity interval sessions, choosing rep length or
+work:rest, or trying to rebuild sustained aerobic power.
+
+**Data/knowledge split:** MCP gives you the power/HR streams and interval stats to *check* whether a
+session did what you intended (was power sustained across reps?). This doc gives the *design logic*.
+
+---
+
+## The target: maximize time spent ≥90% VO2max
+
+The organizing principle of VO2max interval design is **accumulating time at or above 90% of
+VO2max** — that's the stimulus, not simply "going hard." Design sessions to spend the most quality
+minutes in that band that the athlete can repeat and recover from.
+
+## What a large meta-analysis found (dose-response)
+
+A systematic review with pairwise and network meta-analysis (**51 studies, 1,261 athletes**) found
+inverted-U dose-response relationships and identified an optimum around **~140 s work duration** and
+a **work-to-recovery ratio of ~0.85**, with ~3×/week over 3–6 weeks as an effective pattern (Yang,
+Wang & Guan 2025, *BMC Sports Sci Med Rehabil* 17(1):156; PMID 40605061;
+DOI 10.1186/s13102-025-01191-6).
+
+> **Caveat — modality.** Yang 2025 describes its *optimal protocol* as running-based; the abstract
+> does not give a cycling-vs-running breakdown across the 51 studies. Treat ~140 s / 0.85 as a
+> cross-modal anchor, not a cycling-specific verdict — and note that **~140 s is a *medium* rep
+> (~2.3 min): longer than 30s, shorter than the classic 5-min "long" interval.** The pooled optimum
+> sits *between* the two poles people usually argue about.
+
+## ⚠️ Rep length is unsettled and protocol-sensitive — not a solved short-vs-long question
+
+A common coaching claim is that **longer reps (3–5 min) accumulate more time ≥90% VO2max than short
+(30s) intervals.** The evidence does not settle this cleanly: it flips by modality, depends heavily
+on how the protocols are built, and can wash out when total work is matched. Do **not** present
+either "go long" or "go short" as established.
+
+**The direct time-at-VO2max studies disagree by modality:**
+
+| Modality | Finding | Source |
+|---|---|---|
+| **Running (acute)** | 3-min intervals accumulated **more** time >90% VO2max (~328 s) than intensified 30-s intervals (~201 s), even with 30-s intensity raised | Fleckenstein, Braunstein & Walter 2025, *Front Sports Act Living* 6:1507957; PMID 39835194; DOI 10.3389/fspor.2024.1507957 |
+| **Cycling (acute)** | **30-s** work intervals induced **more** time ≥90% VO2peak than longer intervals (50%/80% of Tmax) at matched 2:1 work:rest, in 13 well-trained cyclists — the opposite result | Rønnestad & Hansen 2016, *J Strength Cond Res* 30(4):999–1006; PMID 23942167; DOI 10.1519/JSC.0b013e3182a73e8a |
+| **Cycling (adaptation)** | Over 3 weeks, "effort-matched" **short** intervals (30/15 s) beat long (5-min) intervals — e.g. +4.7% 20-min power — in elite cyclists | Rønnestad, Hansen, Nygaard & Lundby 2020, *Scand J Med Sci Sports* 30(5):849–857; PMID 31977120; DOI 10.1111/sms.13627 |
+
+**The pooled meta-analysis puts the optimum in the *middle* (~140 s / ~2.3 min)** — see the caveat
+above. So the honest shape is an **inverted-U whose peak location shifts with modality and protocol**,
+not a binary short-vs-long contest.
+
+**Two reasons not to over-trust the "cycling favors short" side:**
+1. **It's largely one research group.** The cycling short-interval superiority comes chiefly from
+   Rønnestad and colleagues (2016 / 2020 / 2021; Almquist 2020, PMID 32267032; Rønnestad 2021,
+   PMID 33735833). Internally consistent, but independent replication is limited.
+2. **Effort-matching is the crux.** When independent cycling work matched **total work duration**
+   across formats, the short-interval *adaptation* advantage reportedly disappeared (attributed to a
+   Seiler-group study; **unpublished / secondary-source — low evidence tier, do not cite as fact**).
+   Much of the apparent edge may be that 30/15 sessions simply pack more total high-intensity work,
+   not rep length per se.
+
+**Bottom line:** acute time ≥90% VO2max favors short intervals *in the Rønnestad cycling protocols*
+and long intervals in the one running study; the pooled optimum is *medium* (~140 s); and
+effort-matched adaptation data are equivocal. Treat rep length as a lever to **individualize**, not
+a solved problem.
+
+> ⚠️ **Under-researched — track individual response.** Optimal rep length for a *given cyclist* is
+> not resolved. Use the MCP interval/stream data to verify what actually keeps power in the
+> ≥90%-effort band across reps for this athlete, and let that — not a rule — drive the choice.
+
+## Practical prescription
+
+- **Menu for cyclists** (no format is proven superior — pick by athlete and goal, then verify per
+  rider with the MCP data):
+  - **Medium intervals (~2–4 min, work:rest ~0.85):** closest to the pooled meta-analytic optimum
+    (~140 s; Yang 2025) and a sensible **default** for most riders — long enough to bank time
+    ≥90% VO2max, short enough to hold power across reps.
+  - **Short intervals:** 30/15 s (≈13 reps × 2–3 series) — banks time ≥90% VO2max well in the
+    Rønnestad protocols (2016/2020/2021); good for riders who fade on long reps or want more total
+    high-intensity work per session. Not proven superior once total work is matched.
+  - **Long intervals (~4–5 min):** favored by the running time-at-VO2max data (Fleckenstein 2025)
+    and useful for **sustained** aerobic power and race-specific steady demands; a reasoned choice,
+    not a cycling-proven one.
+- **Prescribe from power.** For MTB especially, HR lags and misleads (`mtb-xco-demands.md`,
+  `data-confounds.md`).
+- **Verify the session worked:** pull the interval stats/streams from MCP and check power held near
+  target across reps. Fading power = too much intensity or too little recovery; adjust work:rest.
+
+## Frequency vs distribution
+
+For *how often* to do hard sessions and how they fit the week/season, see `periodization.md` — the
+argument there (after Seiler 2024) is that the **long-term integration** of frequency, intensity,
+and duration matters more than chasing the acute maximum of any single session.

scripts/build-skill-zip.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+#
+# Package the cycling-training skill into a zip that installs as a Claude skill
+# (Claude Desktop / claude.ai "Skills", or Claude Code).
+#
+# The archive contains a single top-level `cycling-training/` directory holding
+# SKILL.md + supporting docs — the layout Claude expects when importing a skill.
+#
+# Usage:
+#   scripts/build-skill-zip.sh [version]
+# Example:
+#   scripts/build-skill-zip.sh v1.0.0   ->  dist/cycling-training-v1.0.0.zip
+#   scripts/build-skill-zip.sh          ->  dist/cycling-training-dev.zip
+#
+set -euo pipefail
+
+SKILL_NAME="cycling-training"
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+VERSION="${1:-dev}"
+OUT_DIR="${ROOT}/dist"
+STAGE="${OUT_DIR}/${SKILL_NAME}"
+ZIP_NAME="${SKILL_NAME}-${VERSION}.zip"
+
+# The files that make up the installable skill (repo/CI cruft is excluded).
+INCLUDE=(SKILL.md README.md references assets)
+
+rm -rf "${OUT_DIR}"
+mkdir -p "${STAGE}"
+
+for item in "${INCLUDE[@]}"; do
+  if [ ! -e "${ROOT}/${item}" ]; then
+    echo "ERROR: expected '${item}' not found at repo root" >&2
+    exit 1
+  fi
+  cp -R "${ROOT}/${item}" "${STAGE}/"
+done
+
+# Sanity checks: a skill is only valid with a SKILL.md that has name + description.
+test -f "${STAGE}/SKILL.md" || { echo "ERROR: SKILL.md missing from package" >&2; exit 1; }
+grep -q "^name:" "${STAGE}/SKILL.md" || { echo "ERROR: SKILL.md has no 'name:' frontmatter" >&2; exit 1; }
+grep -q "^description:" "${STAGE}/SKILL.md" || { echo "ERROR: SKILL.md has no 'description:' frontmatter" >&2; exit 1; }
+
+# Build the zip with the skill folder as the single top-level entry.
+( cd "${OUT_DIR}" && zip -r -q "${ZIP_NAME}" "${SKILL_NAME}" -x '*.DS_Store' )
+
+echo "Built ${OUT_DIR}/${ZIP_NAME}"
+echo "Contents:"
+( cd "${OUT_DIR}" && unzip -l "${ZIP_NAME}" )