Partner sharing: reading an athlete's fueling profile, profile_sharing and the two sharing webhooks

docs.json

@@ -88,6 +88,7 @@
               "guides/freemium-model",
               "guides/onboarding",
               "guides/athlete-onboarding-journey",
+              "guides/fueling-profile",
               "guides/safety"
             ]
           },

guides/athlete-onboarding-journey.mdx

@@ -48,14 +48,19 @@ On the last answer, the page asks: *"Can we show you fuel for one of your activi
 
 ## The app path, narrated
 
-Some athletes use, or will prefer, the Saturday app. When their app account email matches the email you sent on the athlete record, Saturday links them and their app onboarding feeds your calculations, resolved live rather than synced, with nothing for you to build. Their app answers are never exposed to you through the API. If they turn on "share my fueling profile with \{your platform\}" in app settings, the profile values become visible to you as well.
+Some athletes use, or will prefer, the Saturday app. When their app account email matches the email you sent on the athlete record, Saturday emails their Saturday address asking them to confirm the connection to your platform. Once they confirm, their app onboarding feeds your calculations, resolved live rather than synced, with nothing for you to build.
 
-*Tell your athletes:* "use the same email as your \{platform\} account". Matching is exact apart from case and whitespace, so a different address never links, and no error surfaces anywhere for you to catch.
+The answers themselves stay with Saturday until the athlete chooses to share them with you. In the app, Preferences shows a Partner Sharing card with one switch per connected partner platform: "Share my fueling profile with \{your platform\}". On the hosted page, the finish screen asks "Let \{your platform\} see your fueling answers?" and the athlete confirms from an email. Nothing is shared by default, under-18 athletes cannot share, and sharing stays on until they turn it off or disconnect. While it is on, you can read their sex, age, weight and fueling answers.
+
+*Tell your athletes:* "use the same email as your \{platform\} account, and confirm the email Saturday sends you". Matching is exact apart from case and whitespace, so a different address never links, and no error surfaces anywhere for you to catch.
+
+*Your code:* nothing for the numbers. To read the answers, follow [Reading an athlete's fueling profile](/guides/fueling-profile): check `profile_sharing`, handle `athlete.profile_sharing_changed` and `athlete.fueling_profile_updated`, and read `GET /v1/athletes/{athlete_id}/fueling-profile` while it is `on`.
 
 ## What to build, minimally
 
 1. Show `precision.message` and the invite button whenever `profile_complete` is false.
 2. Register `activity_link_template` and `fueling_path_copy` once.
 3. Handle `athlete.profile_completed`, if you want to mark the moment in your UI.
+4. Handle `athlete.profile_sharing_changed`, if you want the athlete's Saturday app answers.
 
 Saturday handles the questions, the hosted page, the linking, and the checkout.

guides/athletes.mdx

@@ -83,7 +83,7 @@ Every field is optional at create time. The athlete's fueling profile is what ma
 | `partner_plan` | string | Set to `annual` to assert bundle-offer eligibility |
 | `org_id` | string | Organization affiliation; must reference an org you created |
 
-Saturday sets `id`, `partner_id`, `created_at`, `updated_at`, `profile_complete`, and `subscription_status`. Writes to those are ignored.
+Saturday sets `id`, `partner_id`, `created_at`, `updated_at`, `profile_complete`, `subscription_status`, and `profile_sharing`. Writes to those are ignored. `subscription_status` (`full`, `trial`, or `teaser`) and `profile_sharing` (`on`, `off`, or `not_linked`) are computed when you read one athlete with `GET /v1/athletes/{id}`, and are not on lists. `profile_sharing` says whether the athlete shares their Saturday app answers with you; see [Reading an athlete's fueling profile](/guides/fueling-profile).
 
 ### Settings: the fueling profile
 

guides/coach-connector.mdx

@@ -34,7 +34,7 @@ The connector speaks the MCP Streamable HTTP transport (`POST /mcp`) and protoco
 
 ## Athlete tools
 
-When an athlete connects, Claude can read and write that athlete's Saturday data. Athlete tools operate strictly on the signed-in athlete; there is no athlete selector. The full catalog is in [MCP Integration](/guides/mcp-integration#tool-catalog). Highlights:
+When an athlete connects, Claude can read and write that athlete's Saturday data. Athlete tools operate strictly on the signed-in athlete; there is no athlete selector. The full catalog is in [MCP Integration](/guides/mcp-integration#tool-catalog), less `get_fueling_profile`, which is for partner platforms. Highlights:
 
 - `get_athlete`, `update_athlete` read and update the athlete's profile.
 - `list_activities`, `get_activity`, `create_activity` manage the athlete's activities.

guides/freemium-model.mdx

@@ -162,13 +162,13 @@ Give Saturday a `return_url` (https or deep link) at partner onboarding and the
 
 ### Automatic linking by email
 
-Some paying Saturday athletes never touch your subscribe CTA: they subscribed **inside the Saturday app** (Apple/Google in-app purchase) or on saturday.fit before joining your platform. Saturday links these automatically: when the `email` you set on an athlete exactly matches a Saturday account's email (case-insensitive; no fuzzy matching), the records are linked and the athlete's API responses unlock.
+Some paying Saturday athletes never touch your subscribe CTA: they subscribed **inside the Saturday app** (Apple/Google in-app purchase) or on saturday.fit before joining your platform. Saturday links these by email: when the `email` you set on an athlete exactly matches a Saturday account's email (case-insensitive; no fuzzy matching), Saturday emails that account's verified address asking the athlete to confirm the connection to your platform, and once they confirm, the records are linked and the athlete's API responses unlock.
 
 - **Opt in by supplying emails.** Set `email` on your athletes (`POST /v1/athletes` and `PATCH /v1/athletes/{athlete_id}`). Matching runs when you write an athlete email, when a Saturday subscription activates, and in a nightly sweep.
 - **You get the same webhook.** When a match links an actively paying account, `subscription.created` fires with `source: "email_match"`. Handle it like a checkout unlock.
 - **Ambiguity never auto-links.** Multiple athletes sharing an email, or a conflict with an existing link, goes to Saturday-side human review instead.
 - **No revenue share on matched links.** These subscriptions were not driven through your platform (many predate it), so they do not appear on your revenue statement.
-- **Only entitlement is released.** The match tells your platform the athlete's subscription tier, and an expiry when one applies, never payment details, purchase history, or Saturday profile data.
+- **Only entitlement is released.** The match tells your platform the athlete's subscription tier, and an expiry when one applies, never payment details, purchase history, or Saturday profile data. The athlete's Saturday app answers reach you only if they choose to share them; see [Reading an athlete's fueling profile](/guides/fueling-profile).
 
 If you have a partner-negotiated offer with Saturday (e.g. member pricing for your annual subscribers), assert eligibility by setting `partner_plan: "annual"` on the athlete (`PATCH /v1/athletes/{id}`). Eligible athletes' CTAs carry the offer claim and checkout prices accordingly. You may advertise the offer anywhere; only asserted athletes can redeem it.