Revision #764

'''What support needs to know about medication protocols.'''

The Medication Support Engine records what a member reports about a therapy they are already on, shows it back to them, and organizes it into a summary for their own prescriber. '''It gives no medication advice, and neither does support.'''

This is a separate feature from the free medication list and the FDA interaction check, which are unchanged. See ''What support needs to know about Trends, Medications and clinician reports''.

== The four kinds ==

| Kind | Who it is for | Compounds |
|---|---|---|
| '''GLP-1''' | People on a GLP-1 medication, injected or oral | Exactly one |
| '''Testosterone therapy''' | Men on TRT, and transgender and nonbinary people on testosterone therapy | Several |
| '''Hormone therapy''' | People going through menopause or perimenopause, and transgender and nonbinary people on feminizing therapy | Several |
| '''Peptide protocols''' | Multi-compound and peptide protocols a member defines themselves | Several |

A member can run more than one at a time. Each is its own profile with its own screen.

'''There is no compound catalog.''' Every name is free text the member typed, and it is encrypted with their own key. Support cannot look one up, cannot see one, and must never ask a member to describe what they take in order to answer a question.

== What is free and what is Premium ==

'''Free:''' nothing but the catalog vocabulary the pickers draw from, which carries no member data. Since 2026-09-02 the '''whole''' protocol feature is Premium. That includes switching one on, naming its compounds and setting the schedule. A Basic member who opens Protocols meets the purchase sheet on the profile read.

'''Premium (feature key `protocols`):''' the profile and its compound line items, the coach-sharing screen and its disclosure copy, the dashboard and its goal targets, the dose log, the body map and site heat map, reminders, nudges, supply tracking, both calculators, the estimated level chart, symptoms and the pattern view, the wellbeing check-in, labs and lab trends, body-composition and strength trends, the prescriber summary, the Off-Ramp, and the whole intelligence layer below (your pattern, your week, the short sessions, the lean-mass protection score, the protein-gap options, the symptom-food patterns, Progress, appointment questions, the refill runway and the coach cycle calendar).

'''"It says I need Premium"''' is the tier working as designed on every protocol screen, setup included. A Basic member cannot switch a protocol on.

The 52 founding accounts hold Loopa Premium Family for life and are not blocked by any of it.

== The intelligence layer (2026-09-02) ==

Everything here is computed from the member's own logs and '''describes them without interpreting them'''. Every surface has a minimum-data threshold and says '''"still learning"''' below it. A ticket that reads "it says still learning" is the feature working; the table says what has to exist before it stops.

| Surface | Ready when | What support can say |
|---|---|---|
| '''Your pattern''' (per protocol) | Three complete dose cycles (a cycle is two consecutive days with a logged dose) and three check-ins in a bucket before that bucket scores. A protocol dosed every day has no cycle and says so | The card names the days their logs put among their strongest and roughest. It never says why. Log doses and daily check-ins and it fills in |
| '''Your week''' | Follows the pattern once it is ready; before that, today's check-in and last night's sleep | Dose days are calendar markers and are never moved. A program's days stay put and are only labeled. Heavy days cap at 3, or 2 when a protocol gives recovery more room |
| '''Short session offer''' | Today's energy at 2 or under, or a symptom today at 4 or over | It is an ordinary session started from a platform routine; it keeps the streak and counts toward the score |
| '''Lean-mass protection score''' | Two weeks of BOTH food logs and completed sessions; the body input needs two body-fat, measurement-estimate or DEXA points and is labeled "not yet counted" before that | 0–100 from protein-goal days (45%), resistance sessions against three a week (35%) and the lean-mass estimate's direction (20%). A week with nothing logged is a gap, not a zero |
| '''Protein-gap options''' | Protein goal unmet; three options from recent foods first, then the catalog | Budget 250 kcal, or 150 when a symptom today is 3 or above. A food above the member's own symptom-food threshold is left out and named |
| '''Symptom-food patterns''' | A symptom with five entries; a food shown at five co-occurrences AND half the entries | "Logged within 3 hours of X, 6 of 8 times." Counts, never a cause |
| '''Progress''' | Always; `plateau` needs 21 days of weight and a weight inside the last week | Plateau = the 7-day average moved less than 1% of body weight over 21 days. The copy has no failure language and support uses none either |
| '''Appointment questions''' | Any entry with a `question` | The member's own words. Support never suggests a question, and the app never does |
| '''Refill runway''' | A refill date or run-out date plus a pharmacy lead time | reorder-by = run-out (or refill date) minus the lead time. '''The reorder-by reminder is ON by default'''. Absent from the settings means on; only an explicit off stops it |
| '''Prep-day nudge''' | The pattern is ready | Off by default. Switching it on before the pattern is ready answers `422 pattern_required` with the cycle count; that is the gate, not a fault |
| '''Food noise''' | A GLP-1 profile on, or an active Off-Ramp enrollment | A sixth check-in slider; `food_noise_not_applicable` otherwise |
| '''DEXA''' | Four lab markers: `dexa_lean_mass`, `dexa_fat_mass`, `bmd`, `bmd_t_score` | Kept as entered. A T-score may be negative and is accepted as written |

'''The protein target range is 1.2–6.0 g/kg''' on GLP-1, testosterone therapy and hormone therapy profiles since 2026-09-02; the defaults (1.6 / 1.8 / 1.4) and their sources are unchanged. Support does not suggest a value inside it.

'''Pattern language, for support as much as for the app.''' The pattern, the week, the score and the food patterns describe what a member recorded. Support never says "because of your medication", "your dose is causing", or "you should". If a member asks what a pattern means, the answer is that Loopa counted what they logged and the person to interpret it is their prescriber.

== What a 402 means ==

A `402` with `"feature":"protocols"` is '''the paywall, not a fault'''. Both apps turn it into the purchase sheet. It means the member is on Loopa Basic and opened a Premium protocol surface.

'''A 402 is an answer, not an error.''' If a member describes a screen that says "couldn't load, try again" where a 402 was returned, that is a client bug. Escalate it with the screen name and the build number.

== "No estimate available" on the level chart ==

The estimated level chart draws from two things: the doses the member logged, and a '''published elimination half-life for the name they entered'''. When either is missing the chart is absent and the app says which.

| Reason on the wire | What to tell the member |
|---|---|
| `no_constant` | Loopa holds no published half-life for the name they entered. The reference table is small and every row of it comes from an approved product's own labeling or a published human study, with the sentence that states the figure quoted on the row. A name with no such source draws no chart. Gels and patches draw no chart either, because the model behind the curve cannot represent that kind of delivery |
| `no_doses` | Nothing has been logged for that compound yet. Log a dose and the chart appears |

'''Never guess a constant, and never offer one.''' Not from memory, not from a search, not "roughly a week". If Loopa has no cited source for a name, the correct answer is that Loopa has no published figure for it and the chart stays empty. Do not suggest the member rename their compound to something that will draw a chart.

The chart is in '''percent of peak''', is labeled as an estimate, and carries no annotations. It is information about what the member logged, and it is not a schedule.

== What support must never say ==

This is the shortest list on this page and the one that matters most.

* '''No dose advice.''' Never a number, never a range, never "most people take", never a comparison to another member.
* '''No timing advice.''' Not when to take something, not what time of day, not how far apart, not how it should line up with anything else.
* '''No lab advice.''' Not which markers to test, not when to test them, and never an opinion on a value a member quotes. Loopa publishes no reference ranges and support has none either.
* '''Nothing about starting, stopping, changing or missing a medication.''' Including "you should probably ask about" phrased as a hint.
* '''No opinion on what a symptom means.''' The pattern view describes; it does not interpret. Neither do we.
* '''No opinion on a compound.''' Not what it is, not what it does, not whether it is a good idea, and not where to get one. Loopa does not source anything and does not discuss sourcing.

'''Every medication question goes to the prescriber.''' The app's own line is the line to use: ''Questions about your medication belong with your prescriber. Loopa records what you report and reflects it back.''

What support ''can'' help with: where a screen is, why a number will not save, what a validation message means, what a coach category discloses, how to export, and how to turn something off.

== The two calculators ==

Both are arithmetic on numbers the member typed. '''Volume''' takes an amount in mg and a concentration in mg/mL and returns mL and syringe units. '''Reconstitution''' takes a vial amount and a diluent volume and returns the resulting concentration, plus a volume and a doses-in-vial count if an amount is also given.

'''Neither carries a default.''' If a member says a field was blank, that is correct behavior. The app supplies no starting value for any input, deliberately. A refused input comes back as `missing_<field>` or `invalid_<field>` naming the field.

Support does not supply a number for either calculator. If a member does not know their concentration, that is a question for the prescriber or the pharmacy.

== The export ==

'''`POST /health/protocols/export`''' takes one protocol and a date range of at most 400 days, as PDF or CSV. It streams as a download.

* '''Nothing is stored.''' There is no file on our side, no link, and nothing to expire or revoke. A member who wants it again generates it again.
* '''The read is audited.''' Making one is written into the member's own access record, which they can read at You &rarr; Preferences &rarr; Your Data.
* This is not the clinician share link. That is a different feature with a stored file and a revocable link. Do not conflate them on a ticket.

== Coach categories ==

Three consent fields, and they appear on the member's coach screen only if they run that protocol:

| Category | Consent field |
|---|---|
| GLP-1 support | `protocol_glp1` |
| Testosterone therapy support | `protocol_trt` |
| Hormone therapy support | `protocol_hrt` |

Each shows the coach exactly five things: the symptom pattern as counts and mean severity by days since a dose, which days of the week doses fall on, 14-day wellbeing averages for energy, mood, sleep quality and motivation, and, since 2026-09-02, dose days as markers on the coach's programming calendar and the strongest/roughest labels from the member's pattern, as two words only.

'''Consent scope.''' A grant carries `scope_version`: 1 = the three-item template consented to before 2026-09-02, 2 = the five-item one. '''A grant at scope 1 receives no calendar''' and is never raised on the member's behalf; the app asks the member to confirm the updated list once per launch and on the sharing screen, and confirming writes a fresh grant at scope 2. A coach asking why a client's calendar is empty when the category is on: the client has not re-confirmed, and only the client can.

'''Never visible to a coach:''' compound names, any dose amount, lab results, notes on any entry, the check-in scores behind a label, appointment questions, food-noise entries, supply and calculator figures. Libido is never visible either, even where the member records it.

'''There is no peptide template.''' Peptide protocols are never shared with a coach and there is no toggle for them, by design. A member asking how to share one should be told plainly that it cannot be shared, not that we will look into adding it.

Every coach read is logged and the member can read the log themselves.

== Reason codes a member may quote ==

A member reading a message off their screen may quote one of these. They are validation, not faults.

| Code | What it means |
|---|---|
| `premium_required` (402) | Loopa Basic on a Premium protocol surface. Feature key `protocols` |
| `protocol_off` | The profile exists but is not switched on. Turn it on to open the dashboard |
| `unknown_protocol` | Not one of the four kinds |
| `single_compound` (409) | A GLP-1 profile takes exactly one compound. Edit the existing one instead of adding a second |
| `focus_not_applicable` | Training focus is a peptide-profile setting only |
| `unknown_focus` | Focus must be strength, recovery, body composition or general |
| `unknown_form` | The form is not one this protocol offers |
| `unknown_route` | The route is not one this protocol offers |
| `unknown_day` | The dose day is not a day of the week |
| `invalid_start_date` | The start date could not be read |
| `invalid_protein` / `protein_out_of_range` | The protein figure is outside the range for that protocol. The range is on the screen |
| `libido_not_applicable` | The libido slider is offered on a testosterone therapy profile only |
| `site_not_applicable` | That route has no body map, so no site can be recorded |
| `unknown_site` | The site code is not in the body map for that route |
| `missing_<field>` / `invalid_<field>` | A calculator input. The field name is in the code |
| `week_locked` | An Off-Ramp week the member has not reached yet |
| `pattern_required` (422) | The prep-day nudge was switched on before the pattern is ready. The payload carries `cycles_complete` and `cycles_required` |
| `food_noise_not_applicable` | The food-noise slider needs a GLP-1 profile or an active Off-Ramp enrollment |
| `invalid_question` / `question_too_long` | A question must be text of at most 300 characters |
| `unknown_preference` | A protein-gap preference outside vegetarian, vegan, dairy_free, gluten_free, no_shellfish, no_pork |
| `no_constant` / `no_doses` | Why the level chart is absent. See above |

== Where the detail lives ==

The API contract is documented internally; the member-facing article is ''Medication protocols'' in the Loopa knowledge base. Route integration and diligence questions to platform support, and point members at the article.