@murphai/murph 1.3.0 → 1.3.2

package/node_modules/@murphai/assistant-engine/skills/body-composition/SKILL.md

@@ -1,56 +1,166 @@
 ---
 name: body-composition
-description: Use for fat loss muscle gain recomposition waist weight trend plateaus body composition measurement and sustainable change questions.
+description: |
+  Plan, review, or troubleshoot intentional fat loss, weight loss, lean-mass gain,
+  weight gain, cutting, bulking, recomposition, maintenance, plateaus, and
+  body-composition tracking without treating one diet, calorie estimate, BMI,
+  scale reading, or consumer body-fat estimate as ground truth.
 ---
 
 # Body Composition
 
-Use this as Murph operating guidance, not as a consumer article. Ground the answer in the current conversation, vault context, and wearable data before recommending. Ask at most one missing question when the answer would materially change the next step.
+Use this as Murph operating guidance, not as a consumer article. Ground the answer in the current conversation, vault context, connected measurements, training history, food context, medications, and relevant health constraints before recommending. Ask at most one compact missing question in ordinary cases; ask more only when safety requires it.
+
+This is one owner with several paths. Do not create parallel weight-loss, weight-gain, cut, or bulk plans that can disagree about the same goal, measurements, safety state, or adjustment policy.
+
+## Load Only What the Task Needs
+
+- Read `references/fat-loss.md` for an intentional fat-loss or weight-loss plan, maintenance transition, stalled loss, or regain.
+- Read `references/muscle-gain.md` for intentional weight gain, lean-mass gain, bulking, or deciding whether a surplus is useful.
+- Read `references/tracking-and-adjustment.md` before creating a measurement plan, interpreting a plateau, changing calories, or reviewing progress.
+- Read `references/safety.md` whenever the goal may involve underweight, unintentional change, eating-disorder risk, low energy availability, minors, pregnancy, breastfeeding, major illness, surgery, or medication decisions.
+- Read `references/evidence.md` when explaining the basis for a numerical default, comparing approaches, or maintaining this skill.
+- Use `nutrition-strategy` for meal structure, grocery or restaurant execution, protein targets and distribution, training fuel, hydration, and food adequacy.
+- Use `strength-training` for exercise selection, lifting progression, volume, intensity, and hypertrophy programming.
+- Use `behavior-followthrough` when consistency, reminders, friction, shame, lapses, or support style is the main bottleneck.
+- Use `food-journal` when the user wants low-burden meal capture or pattern discovery rather than a prescriptive calorie or macro plan.
+- Use `experiment-onboarding` only when the user explicitly wants a bounded experiment with a hypothesis and review window.
 
 ## Owns
 
-- Fat loss, muscle gain, recomposition, waist/weight trends, plateaus, body composition measurement noise, and sustainable change strategy.
-- Choosing between deficit, maintenance/recomp, surplus, protein, resistance training, steps, sleep, and adherence levers.
-- Explaining scale noise and realistic time horizons.
+- Clarifying whether the real target is fat loss, muscle gain, intentional weight restoration, recomposition, maintenance, performance, health-risk reduction, or simply understanding a trend.
+- Choosing the smallest useful energy-direction decision: deficit, maintenance, maintenance-to-small-surplus, or qualified-care-led restoration.
+- Coordinating weight, waist, strength or training performance, food intake, steps or activity, appetite, energy, recovery, and symptoms without making every signal mandatory.
+- Setting a review cadence and deciding whether evidence supports holding, adjusting, transitioning to maintenance, or escalating.
+- Explaining scale noise, body-composition measurement limits, realistic uncertainty, and why weight change is not identical to fat or muscle change.
+- Keeping the plan neutral, private, reversible, and sustainable.
 
 ## Hand Off
 
-- Use nutrition-strategy for meal structure and food-system execution.
-- Use strength-training for lifting progression and hypertrophy programming.
-- Use cardiometabolic-health when labs/BP/glucose are the primary driver.
-- Route eating-disorder risk, rapid/aggressive cuts, underweight, pregnancy, adolescents, medication/GLP-1 decisions, or body dysmorphia concerns to clinician support.
+- Use `nutrition-strategy` for protein targets, distribution, and the concrete food system after this skill chooses the body-composition direction.
+- Use `strength-training` for the resistance-training program. This skill may require a training stimulus but should not duplicate programming.
+- Use `daily-activity` for a factual activity or step read and `sleep-recovery-readiness` for an acute train-versus-rest decision.
+- Use `cardiometabolic-health` when glucose, blood pressure, lipids, or another marker is the primary outcome rather than body composition.
+- Use `gut-digestion` when digestive symptoms determine the food plan.
+- Route suspected eating disorders, rapid or unexplained weight change, underweight, growth or puberty concerns, pregnancy, post-bariatric care, major organ disease, diabetes-medication risk, prescription weight-loss medication, and surgery decisions to qualified care.
+- For postpartum or breastfeeding users, read `references/safety.md`; do not automatically refuse a goal, and involve qualified care when intentional change, lactation, recovery, infant growth, symptoms, or rapid loss makes it material. Murph can still help organize questions, records, measurements, food adequacy, and follow-through around professional care.
 
 ## Data First
 
-- Check weight trend, waist, photos if voluntarily provided, strength trend, protein, steps, training, sleep, menstrual cycle if relevant, and recent diet changes.
-- Use weekly averages and waist trends instead of one scale day.
-- Ask about history of disordered eating before recommending tracking-heavy tactics when risk is plausible.
+Use what already exists before asking the user to repeat it. Distinguish measured facts, estimates, and user-reported context.
+
+Check, when relevant:
+
+- goal, reason, urgency, desired outcome, and whether the target is voluntary
+- age and life stage; pregnancy, breastfeeding, growth, or older-adult context
+- current weight and same-condition trend, not only the latest value
+- waist trend or clothing fit if useful and acceptable
+- when connected measurements matter, use the lossless global observation read
+  `vault-cli measurement entry list --metric <metric> --from <date> --to <date> --limit 50 --format json`
+  with `body_mass_index`, `fat`, `lean_body_mass`, or `waist_circumference`.
+  Use a short bounded window, take the newest entry for a latest-value question,
+  and compare repeated readings for a trend. Keep sources and measurement
+  conditions consistent, using the returned source and event ID as provenance;
+  imported device observations may be query-only and unavailable through
+  `vault-cli show`. No returned entries means missing coverage rather than no
+  change
+- strength, repetitions, training quality, and resistance-training consistency
+- meal or food pattern, estimated protein, alcohol, liquid calories, appetite, and food access
+- steps, cardio, sedentary time, sleep, recovery, illness, pain, and recent training changes
+- medications, surgery history, medical conditions, menstrual or endocrine changes, and relevant labs
+- prior attempts, methods that helped or harmed, tracking tolerance, and eating-disorder or compulsive-exercise risk
+- scale, unit, source, timestamp, and whether device values are direct measurements or estimates
+
+Do not request progress photos, exact calorie logging, body-fat percentage, or daily weighing by default. Offer only the minimum measurement burden that can change a decision.
+
+For a daily nutrition-card calorie target, read
+`$MURPH_ASSISTANT_SKILLS_ROOT/nutrition-strategy/references/daily-nutrition-card-goals.md`.
+This skill owns whether the direction is maintenance/recomp, muscle gain, or fat
+loss; the reference owns the researched estimate, conservative adjustment, and
+explanation-before-card sequence.
 
 ## If Context Is Thin
 
-Ask: "Are you trying to lose fat, gain muscle, recomp slowly, or understand whether the current trend is a real plateau?"
+Ask one high-yield question:
+
+> Are you mainly trying to lose fat, gain muscle or body weight, maintain or recomp, or understand an unexpected trend?
+
+If the answer is “lose weight” or “gain weight,” clarify the intended outcome only when it changes the plan. Do not assume weight loss is medically indicated or that weight gain means a bodybuilding bulk.
+
+## Decide the Lane
+
+1. **Intentional fat loss** — use a sustainable energy deficit plus resistance training when appropriate; include a maintenance plan from the beginning.
+2. **Lean-mass gain or bulk** — make progressive resistance training the gate; start at maintenance or a small surplus rather than treating rapid scale gain as success.
+3. **Recomposition or maintenance** — use when scale change is unnecessary, preference favors lower burden, or the user can plausibly improve strength and waist or body composition without a large energy change.
+4. **Qualified-care-supported restoration** — use for underweight, malnutrition risk, significant unintentional loss, eating-disorder recovery, post-surgical needs, or illness-driven weight loss. Do not turn this into a self-directed bulk.
+5. **Understand the trend** — investigate measurement conditions, fluid and glycogen shifts, medications, illness, intake, activity, and time window before creating a goal.
+6. **Short-term scale manipulation** — do not help with dehydration, purging, laxatives, diuretics, starvation, or an aggressive competition cut. Route to safer performance and clinician support.
 
-## Practical Levers
+## Build the Smallest Complete Plan
 
-- Fat loss: modest calorie deficit, adequate protein, resistance training, steps, sleep, and a plan the user can repeat.
-- Muscle gain: progressive resistance training, enough calories, enough protein, and patience over months.
-- Recomp: best for beginners, detrained users, higher body-fat starting points, or people returning to training; expect slower scale change.
-- Plateau: verify 2-4 weeks of trend, adherence, weekends, liquid calories/alcohol, step reduction, menstrual water shifts, and constipation before cutting more.
-- A common safe loss pace is roughly 0.5-1 percent body weight per week; slower is often better for lean or performance-focused users.
+A complete plan can be short, but it must include:
+
+1. **Outcome and reason** — what change matters and why.
+2. **Baseline** — enough same-condition data to distinguish trend from noise.
+3. **Primary lever** — one repeatable food, energy, or environment change; not a pile of rules.
+4. **Muscle-preservation or gain signal** — resistance training and adequate protein when appropriate.
+5. **Minimum tracking** — one primary outcome plus one or two context signals.
+6. **Review window** — long enough to observe a trend and short enough to correct course.
+7. **Adjustment rule** — what evidence would cause hold, small change, pause, maintenance, or escalation.
+8. **Exit or maintenance phase** — what happens after the initial target or if costs exceed benefits.
+
+Planning is not activation. Do not create goals, recurring check-ins, calorie targets, automations, experiments, tables, or reminders until the user clearly asks Murph to do so. After activation, use canonical vault and CLI surfaces; do not maintain a second body-composition record inside the conversation.
 
 ## Interpretation Rules
 
-- BIA scales and wearable body-fat estimates are noisy; use the same conditions and track trend only.
-- Strength up plus waist down can be progress even if weight is stable.
-- Water, glycogen, sodium, soreness, travel, and cycle phase can mask fat loss for days to weeks.
+- Weight is a mixed signal: fat, lean tissue, glycogen, water, gastrointestinal contents, and measurement error all contribute.
+- Compare rolling or weekly summaries under similar conditions. One reading should almost never trigger an energy adjustment.
+- Water, sodium, carbohydrate intake, alcohol, travel, illness, constipation, menstrual-cycle phase, creatine, and new or hard training can obscure the underlying direction for days or weeks.
+- BMI can be useful population or screening context but is not a direct body-fat measure, a diagnosis, or a moral score.
+- Consumer BIA body-fat and lean-mass estimates are not interchangeable with criterion methods at the individual level. Treat them as noisy estimates, keep device and conditions consistent, and do not derive precise tissue changes from small movements.
+- Waist down with maintained or improved strength can be meaningful fat-loss progress even when weight is flat.
+- Weight up with better performance is not proof of muscle gain; check time, waist, training progression, and the size of the surplus.
+- Calorie expenditure and intake calculations are starting hypotheses. Calibrate from observed trend and context rather than claiming exact energy balance.
+- Recomposition is possible but slow and variable. Do not promise it or use an unchanged scale to prove it.
+
+## Adjustment Discipline
+
+- Hold when the data window is too short, measurements are inconsistent, a major confounder is active, or the current plan is working.
+- Change one primary lever at a time unless safety requires stopping.
+- Prefer a small reversible adjustment over a large correction.
+- Never reduce intake or increase exercise automatically from one weigh-in, one body-fat estimate, one missed target, or an incomplete food log.
+- When repeated data and adherence disagree, investigate measurement, hidden friction, food-access reality, activity adaptation, and reporting uncertainty without accusing the user.
+- Pause or move toward maintenance when recovery, performance, mood, menstrual function, food preoccupation, or physical symptoms meaningfully worsen.
+- Celebrate process and capability without praising thinness, rapid gain, restriction, or a particular body shape.
 
 ## Safety Boundaries
 
-- Escalate binge/purge behaviors, fear of eating, amenorrhea, dizziness, rapid unexplained weight loss, underweight, or obsessive tracking distress.
-- Do not recommend extreme deficits, dehydration, laxatives, or aggressive weight cuts.
+Read `references/safety.md` before giving a plan when risk is plausible.
+
+Do not recommend:
+
+- purging, vomiting, laxatives, diuretics, dehydration, sweat suits, or deliberate fluid restriction for scale change
+- starvation, unsupervised very-low-calorie diets, prolonged fasting as a default fat-loss method, or “earning” food with exercise
+- aggressive competition weight cuts, rapid catch-up bulks, “dirty bulks,” or compensatory exercise after eating
+- changing prescription medications, GLP-1 or other anti-obesity drugs, insulin, or post-bariatric supplementation without the treating team
+- a tracking method that is worsening obsession, fear, shame, bingeing, restriction, or compulsive exercise
+
+Escalate urgent symptoms such as fainting, confusion, chest pain, severe weakness, repeated vomiting, signs of dehydration, or suicidal or self-harm risk through the appropriate urgent-care pathway.
+
+## Product Actions and Privacy
+
+- Keep body measurements, food logs, photos, and goals private unless the user explicitly shares them.
+- Do not ask for photos when weight, waist, clothing fit, performance, or symptoms can answer the question.
+- Explain what Murph will record before enabling a recurring check-in.
+- Store direct measurements with source, unit, and timestamp. Keep estimates labeled as estimates.
+- Preserve raw device provenance and avoid duplicate manual writes when a connected scale already supplies the same measurement.
+- If the user asks for a table or visual tracker, use `tracked-table`; the canonical measurements and goal remain the source of truth.
 
 ## Answer Shape
 
-- Name the goal and the one bottleneck to change first.
-- Give a measurement plan with scale trend plus at least one non-scale marker.
-- Keep the first intervention small and sustainable.
+- State the lane and the decision that matters now.
+- Name the evidence already available and the largest uncertainty.
+- Give one primary action, one measurement plan, and the review timing.
+- Include the hold or adjustment rule and the maintenance or exit path.
+- Surface a safety boundary only when relevant; do not bury the useful answer in generic disclaimers.
+- Keep estimates and heuristics labeled. Be direct about where evidence is weak.

package/node_modules/@murphai/assistant-engine/skills/body-composition/references/evidence.md

@@ -0,0 +1,150 @@
+# Evidence Map
+
+Last reviewed: **2026-08-09**
+
+This evidence map supports operational defaults. It is not a literature dump and does not replace current clinical guidance for a particular user.
+
+## How to Use the Evidence
+
+Separate:
+
+1. **High-confidence direction** — broad findings suitable for most generally healthy adults.
+2. **Conditional optimization** — useful for a named outcome or population.
+3. **Practical heuristic** — a reversible starting point selected for clarity, not a proven biological optimum.
+4. **Product choice** — Murph’s privacy, consent, simplicity, and anti-shame defaults.
+
+Do not present a heuristic as a safety threshold. Do not generalize an athlete or bodybuilding study to pregnancy, adolescents, eating-disorder recovery, frail older adults, or people with major disease.
+
+## Operational Conclusions
+
+### High-confidence direction
+
+- Sustainable fat-loss programs combine a reduced-energy eating pattern, activity appropriate to the person, behavior support, monitoring, and a maintenance plan.
+- Different high-quality dietary patterns can produce weight loss; long-term fit, food quality, preferences, health constraints, and adherence matter more than declaring one macronutrient ideology universally best.
+- Resistance exercise during dietary weight loss helps preserve fat-free mass, can increase fat-mass loss, and improves strength compared with diet alone in adults with overweight or obesity.
+- Progressive resistance training is the main stimulus for hypertrophy. Extra calories without that stimulus are not a muscle-gain program.
+- Protein supplementation can modestly augment resistance-training gains when total intake would otherwise be insufficient; average benefit plateaued around a total intake near 1.6 g/kg/day in a major meta-regression. This is source-level context, not a second protein prescription: `nutrition-strategy` owns applying any target.
+- Body weight and consumer body-composition estimates contain substantial noise. Individual BIA percentage-fat and fat-free-mass values are not equivalent to a four-compartment criterion model.
+- Eating-disorder assessment must not rely on BMI or illness duration alone; rapid change, restrictive or compensatory behavior, physical symptoms, endocrine disturbance, and psychological context matter.
+
+### Conditional optimization
+
+- Lean, trained, performance-focused people may preserve lean mass and performance better with a slower loss than an aggressive cut, but the evidence is population-specific.
+- A small energy surplus may be more efficient than a large surplus for trained lifters because faster gain can increase skinfolds without clearly improving most hypertrophy or strength outcomes. Direct evidence is sparse.
+- Daily weighing can improve trend resolution for users who tolerate it, but it is not required and can be inappropriate when it increases distress.
+- Waist, performance, symptoms, and health markers can be more decision-relevant than a scale target.
+- Medication and metabolic or bariatric surgery can be evidence-based obesity treatments; selecting or managing them is clinician-led, not a failure of lifestyle.
+- Postpartum weight reduction can be appropriate, but breastfeeding changes energy needs; generic adult calorie targets should not be reused without lactation, recovery, milk-supply, infant-growth, and medical context.
+
+### Practical heuristics used by this skill
+
+These are intentionally labeled as heuristics:
+
+- roughly 0.25% to 1% body-weight loss per week as a broad adult planning range when a numerical rate is wanted and the safety screen is clear, usually slower for lean or performance-focused users
+- at least two to four weeks of comparable weight or waist data before calling a plateau
+- maintenance-to-small-surplus before a large surplus
+- a small, individualized gain rate reviewed over two to four weeks rather than a fixed universal bulk rate
+- one primary outcome plus one or two context signals
+- one main adjustment at a time
+- a maintenance or exit plan from the start
+
+### Product choices
+
+- One `body-composition` owner rather than separate cut and bulk skills.
+- `nutrition-strategy` remains the single owner for protein targets, distribution, and concrete food execution; this file retains source-level protein evidence only.
+- No automatic calorie or exercise adjustment from one measurement.
+- No required calorie counting, weighing, photos, or BIA.
+- Planning is not activation; recurring tracking and automations require a clear user request.
+- Body measurements and photos are private by default.
+- No group ranking by weight loss, body fat, calories, or appearance.
+- Direct measurements and vendor estimates retain provenance and are not silently merged.
+
+## Sources
+
+### Weight-management programs and maintenance
+
+1. **National Institute of Diabetes and Digestive and Kidney Diseases.** [Choosing a Safe & Successful Weight-loss Program](https://www.niddk.nih.gov/health-information/weight-management/choosing-a-safe-successful-weight-loss-program). Last reviewed February 2024.
+   - Supports a reduced-calorie eating plan, activity, behavior support, monitoring, realistic goals, and maintenance; emphasizes fit to health, culture, preferences, and values.
+
+2. **National Institute of Diabetes and Digestive and Kidney Diseases.** [Eating & Physical Activity to Lose or Maintain Weight](https://www.niddk.nih.gov/health-information/weight-management/adult-overweight-obesity/eating-physical-activity).
+   - Supports a maintainable healthy eating pattern and activity for health and maintenance rather than one branded diet.
+
+3. **National Institute of Diabetes and Digestive and Kidney Diseases.** [Body Weight Planner](https://www.niddk.nih.gov/health-information/weight-management/body-weight-planner).
+   - Provides dynamic adult weight-planning context and explicitly excludes people under 18 and pregnant or breastfeeding users. Murph should not copy a static “3,500 kcal per pound” rule.
+
+4. **Gardner CD, et al.** Effect of Low-Fat vs Low-Carbohydrate Diet on 12-Month Weight Loss in Overweight Adults and the Association With Genotype Pattern or Insulin Secretion: The DIETFITS Randomized Clinical Trial. *JAMA*. 2018;319(7):667-679. DOI: [10.1001/jama.2018.0245](https://doi.org/10.1001/jama.2018.0245). PMID: [29466592](https://pubmed.ncbi.nlm.nih.gov/29466592/).
+   - In 609 adults, healthy low-fat and healthy low-carbohydrate approaches did not differ significantly in 12-month weight change.
+
+### Resistance training and lean tissue
+
+5. **Binmahfoz A, et al.** Effect of resistance exercise on body composition, muscle strength and cardiometabolic health during dietary weight loss in people living with overweight or obesity: a systematic review and meta-analysis. *BMJ Open Sport & Exercise Medicine*. 2025;11:e002363. DOI: [10.1136/bmjsem-2024-002363](https://doi.org/10.1136/bmjsem-2024-002363). PMID: [40909191](https://pubmed.ncbi.nlm.nih.gov/40909191/).
+   - Across 25 randomized trials, resistance exercise during dietary weight loss protected fat-free mass, increased fat-mass loss, and improved strength versus diet alone.
+
+6. **Currier BS, et al.** American College of Sports Medicine Position Stand. Resistance Training Prescription for Muscle Function, Hypertrophy, and Physical Performance in Healthy Adults: An Overview of Reviews. *Medicine & Science in Sports & Exercise*. 2026;58(4):851-872. DOI: [10.1249/MSS.0000000000003897](https://doi.org/10.1249/MSS.0000000000003897). PMID: [41843416](https://pubmed.ncbi.nlm.nih.gov/41843416/).
+   - Overview of 137 systematic reviews spanning more than 30,000 adults; supports consistency, progressive resistance, specificity, heavier loads for maximal strength, and recoverable volume for hypertrophy without requiring unnecessary complexity.
+
+7. **Morton RW, et al.** A systematic review, meta-analysis and meta-regression of the effect of protein supplementation on resistance training-induced gains in muscle mass and strength in healthy adults. *British Journal of Sports Medicine*. 2018;52(6):376-384. DOI: [10.1136/bjsports-2017-097608](https://doi.org/10.1136/bjsports-2017-097608). PMID: [28698222](https://pubmed.ncbi.nlm.nih.gov/28698222/).
+   - Forty-nine studies and 1,863 participants; supplementation modestly improved training outcomes, with no further average fat-free-mass gain beyond about 1.62 g/kg/day in the breakpoint analysis.
+
+### Rate and surplus uncertainty
+
+8. **Garthe I, et al.** Effect of two different weight-loss rates on body composition and strength and power-related performance in elite athletes. *International Journal of Sport Nutrition and Exercise Metabolism*. 2011;21(2):97-104. PMID: [21558571](https://pubmed.ncbi.nlm.nih.gov/21558571/).
+   - In a small elite-athlete trial, the slower target of about 0.7% per week produced more favorable lean-mass and performance changes than about 1.4% per week. This is a conditional signal, not a universal adult rule.
+
+9. **Fogarasi A, et al.** The Impact of the Rate of Weight Loss on Body Composition and Metabolism. *Current Obesity Reports*. 2022;11(2):33-44. DOI: [10.1007/s13679-022-00470-4](https://doi.org/10.1007/s13679-022-00470-4). PMID: [35133628](https://pubmed.ncbi.nlm.nih.gov/35133628/).
+   - Across matched-weight-loss comparisons, faster loss could produce more fat-free-mass loss and a larger resting-energy-expenditure decline during the active loss phase, but those differences attenuated after weight stabilization and did not clearly change later regain.
+
+10. **Helms ER, et al.** Effect of Small and Large Energy Surpluses on Strength, Muscle, and Skinfold Thickness in Resistance-Trained Individuals: A Parallel Groups Design. *Sports Medicine - Open*. 2023;9:102. DOI: [10.1186/s40798-023-00651-y](https://doi.org/10.1186/s40798-023-00651-y). PMID: [37914977](https://pubmed.ncbi.nlm.nih.gov/37914977/).
+    - Small eight-week trial with 17 completers; larger intended surplus increased skinfolds more without clear superiority for most strength and muscle outcomes. It did not establish a universal optimal surplus or gain rate.
+
+### Measurement limits
+
+11. **Oliver CJ, et al.** The Validity of Bioelectrical Impedance Analysis Compared to a Four-Compartment Model in Healthy Adults: A Systematic Review. *Journal of Functional Morphology and Kinesiology*. 2026;11(1):65. DOI: [10.3390/jfmk11010065](https://doi.org/10.3390/jfmk11010065). PMID: [41718193](https://pubmed.ncbi.nlm.nih.gov/41718193/).
+    - BIA estimates were generally not equivalent to four-compartment estimates at the individual level; percentage-fat limits of agreement often spanned roughly 15 to 20 percentage points.
+
+12. **National Institute of Diabetes and Digestive and Kidney Diseases.** [Am I at a Healthy Weight?](https://www.niddk.nih.gov/health-information/weight-management/adult-overweight-obesity/am-i-healthy-weight).
+    - BMI and waist are screening context; BMI does not directly measure body fat and requires individual interpretation.
+
+### Eating disorders and low energy availability
+
+13. **National Institute for Health and Care Excellence.** [Eating disorders: recognition and treatment, NG69](https://www.nice.org.uk/guidance/ng69/chapter/recommendations). Published 2017; last updated 2020, with minor reference changes through December 2025.
+    - Supports referral based on the full pattern of rapid change, restrictive or compensatory behavior, physical and endocrine signs, and psychological context; says not to use BMI or illness duration alone.
+
+14. **Mountjoy M, et al.** 2023 International Olympic Committee’s consensus statement on Relative Energy Deficiency in Sport (REDs). *British Journal of Sports Medicine*. 2023;57:1073-1097. DOI: [10.1136/bjsports-2023-106994](https://doi.org/10.1136/bjsports-2023-106994).
+    - Low energy availability can impair health and performance across sexes and body sizes; diagnosis and risk stratification are clinician-led.
+
+### Postpartum and breastfeeding
+
+15. **American College of Obstetricians and Gynecologists.** [Interpregnancy Care](https://www.acog.org/clinical/clinical-guidance/obstetric-care-consensus/articles/2019/01/interpregnancy-care). Obstetric Care Consensus No. 8.
+    - Encourages postpartum weight optimization over roughly 6 to 12 months while treating interpregnancy health as broader than a rapid scale target.
+
+16. **American College of Obstetricians and Gynecologists.** [Breastfeeding Your Baby](https://www.acog.org/womens-health/faqs/breastfeeding-your-baby).
+    - Notes that milk production changes energy needs and that breastfeeding nutrition should preserve maternal and infant adequacy rather than reuse a generic adult calorie target.
+
+### Behavior and follow-through
+
+17. **Spring B, et al.** Self-regulatory behaviour change techniques in interventions to promote healthy eating, physical activity, or weight loss: a meta-review. *Health Psychology Review*. 2021;15(4):508-539. DOI: [10.1080/17437199.2020.1721310](https://doi.org/10.1080/17437199.2020.1721310).
+    - No individual self-regulatory technique was consistently associated with outcomes across the included reviews; this supports not assuming that more techniques or more tracking are automatically better.
+
+## Known Limits
+
+- Long-term trials rarely isolate one lever cleanly.
+- Weight-loss studies often enroll adults with overweight or obesity and may not generalize to lean athletes or people seeking small aesthetic changes.
+- Hypertrophy surplus research is sparse, short, and often male-dominated.
+- Fat-free mass includes water and other non-muscle tissue; DXA “lean mass” is not identical to skeletal muscle.
+- Protein breakpoint estimates describe group averages and do not define a hard personal threshold.
+- BIA validity varies by device, equation, population, hydration, and protocol.
+- Postpartum and lactation needs vary with recovery, milk production, infant growth, baseline status, and medical context; broad guidance should not become a fixed deficit.
+- Maintenance, adherence, and quality-of-life outcomes matter but are inconsistently reported.
+- Medication and surgery evidence changes quickly and should be researched from current official and primary sources when asked.
+
+## Maintenance Triggers
+
+Review this file when:
+
+- a major obesity, sports-nutrition, eating-disorder, pregnancy, postpartum, breastfeeding, or pediatric guideline changes
+- new high-quality evidence materially changes protein, loss-rate, or surplus defaults
+- Murph adds prescription weight-management workflows
+- the canonical goal or measurement schema changes
+- a new body-composition device type is treated as a first-class source
+- user feedback shows that the skill promotes overtracking, shame, unsafe restriction, or unnecessary gain

package/node_modules/@murphai/assistant-engine/skills/body-composition/references/fat-loss.md

@@ -0,0 +1,132 @@
+# Intentional Fat Loss
+
+Last reviewed: **2026-08-09**
+
+Use this file for an adult who voluntarily wants to reduce fat or body weight, for maintenance after loss, or for a suspected plateau. Read `safety.md` first when underweight, unintentional loss, eating-disorder risk, pregnancy, breastfeeding, adolescence, major illness, medication changes, or post-bariatric care may apply.
+
+## Start With the Actual Outcome
+
+“Lose weight” can mean several different things:
+
+- reduce cardiometabolic risk
+- reduce waist or fat mass
+- improve comfort, mobility, or pain tolerance
+- improve sport or occupational performance
+- meet an appearance preference
+- reverse a recent unwanted trend
+- change a scale number regardless of tissue
+
+Name the intended outcome before choosing tactics. Do not tell a user to lose weight solely because BMI is above a cutoff, and do not imply that weight loss is required for dignity, attractiveness, or health participation.
+
+If the primary outcome is glucose, blood pressure, lipids, mobility, sleep apnea risk, or another condition, coordinate with the owner skill and accept improvement without insisting on a specific scale target.
+
+## Choose the Lowest-Burden Effective Path
+
+Several paths can create a sustained energy deficit. There is no universally superior macronutrient split.
+
+### Path A: no calorie counting
+
+Use when the user prefers low burden, has a history that makes tracking risky, or has obvious repeatable levers.
+
+Examples:
+
+- replace one recurrent high-energy drink or reduce one recurrent alcohol occasion
+- add a protein- and fiber-containing first meal
+- change the default restaurant or delivery order
+- pre-portion one recurrent snack
+- increase vegetables, fruit, legumes, or other low-energy-density foods
+- create a consistent meal boundary that reduces grazing
+- keep a repeatable step or walking floor without treating exercise as punishment
+
+Measure the trend before adding more rules.
+
+### Path B: light structure
+
+Use a repeatable plate, meal template, portion guide, planned snacks, or a small number of meal anchors. This often creates enough consistency to learn without full logging.
+
+### Path C: temporary calorie or macro estimation
+
+Use when the user asks for it, already tracks comfortably, or the trend cannot be understood otherwise.
+
+- Treat calculated maintenance and deficit values as hypotheses, not measurements.
+- Prefer a range over false precision.
+- Explain likely food-estimation error and device expenditure error.
+- Use the observed multiweek trend to calibrate.
+- Stop or simplify tracking if it increases obsession, shame, restriction, bingeing, or avoidance.
+
+### Path D: clinician-supported obesity treatment
+
+Lifestyle, prescription medication, and metabolic or bariatric surgery are not competing moral categories. When the user asks about medication or surgery, route the decision to qualified care while helping prepare questions, organize history, preserve muscle-supporting behaviors, and monitor agreed outcomes. Do not recommend starting, stopping, or changing a prescription.
+
+After choosing the direction and tracking burden, use `nutrition-strategy` for any protein target, meal structure, grocery or restaurant execution, and concrete food changes. Do not maintain a second nutrition prescription here.
+
+## Rate and Deficit
+
+Do not promise a linear rate. Early changes can be dominated by glycogen, water, sodium, and gastrointestinal contents; later energy needs and appetite can change.
+
+For generally healthy adults, a **provisional planning range** of roughly **0.25% to 1% of body weight per week** can be useful when a numerical rate is wanted and the safety screen is clear. It is not a universal safety rule or a requirement.
+
+Use the lower end, maintenance, or clinician input when the person is lean, highly trained, older, symptom-prone, protecting performance, has a long dieting history, or has any low-energy-availability concern. NIDDK’s example initial target for adults with overweight or obesity is 5% to 10% over six months; that is a health-program framing, not a command for every user.
+
+Never accelerate merely because the last week was slow. Reduce the deficit or pause when performance, recovery, mood, concentration, menstrual function, libido, sleep, food preoccupation, or physical symptoms materially worsen.
+
+## Preserve Capability, Not Only Scale Loss
+
+- Resistance training is the main exercise owner for preserving or gaining strength and lean tissue. Use `strength-training`.
+- Protein adequacy can matter, but `nutrition-strategy` owns any numerical target, distribution, and food implementation. Load it when the user wants amounts or meal changes rather than copying a second prescription here.
+- Use `nutrition-strategy` to preserve training fuel, satisfaction, food quality, and cultural fit instead of forcing one macro ideology.
+- Keep activity useful for health and maintenance. Do not respond to a plateau by adding large exercise volumes before checking recovery and spontaneous activity.
+- Sleep, stress, pain, food access, schedule, medication effects, and social eating can determine whether the plan is executable.
+
+A plan that produces a smaller scale change while preserving strength, energy, and adherence may be better than a faster loss.
+
+## Plateau Decision Order
+
+A plateau is not one flat day or week.
+
+Before changing intake or activity:
+
+1. Confirm at least two to four weeks of comparable weight data, or a longer window when cycle phase, travel, illness, creatine, or new training creates noise.
+2. Check whether the intended plan was actually executable, including weekends, restaurant meals, alcohol, liquid calories, snacks, and portion drift.
+3. Check whether steps, standing, training volume, or other activity fell.
+4. Check sodium, carbohydrate, constipation, inflammation, soreness, sleep, menstrual cycle, and medication changes.
+5. Check whether waist, clothing fit, strength, mobility, or another primary outcome is still improving.
+6. Decide whether the user is already near a reasonable stopping point or needs a maintenance phase.
+7. Only then choose one small adjustment and set a new review window.
+
+Do not accuse the user of nonadherence. Self-report and food estimates are uncertain for everyone. Diagnose friction and measurement before blame.
+
+## Adjustment Options
+
+Choose one:
+
+- **Hold** when the trend is on course or the evidence is insufficient.
+- **Simplify** when burden or inconsistency is the bottleneck.
+- **Reduce one recurrent energy source** rather than rewriting the whole diet.
+- **Add a small activity dose** when recovery and schedule support it.
+- **Increase food or move to maintenance** when loss is faster than intended or costs are rising.
+- **Pause and escalate** when safety signals appear.
+- **End the loss phase** when the health or personal objective is met, even if an arbitrary “ideal” scale number is not.
+
+Do not automatically cut a fixed number of calories. Food-label, portion, and expenditure errors can exceed small numerical adjustments; prefer a concrete behavior whose effect can be observed.
+
+## Maintenance Is Part of the Plan
+
+A fat-loss plan without a maintenance transition is incomplete.
+
+Before the target date or stopping point:
+
+- identify the behaviors worth keeping
+- loosen or remove tracking that is no longer decision-relevant
+- increase intake gradually or directly to an estimated maintenance range according to preference and symptoms
+- keep resistance training and an activity pattern the user values
+- decide how often to review weight or waist without creating vigilance
+- define a broad maintenance range and a neutral response to drift
+- plan for travel, illness, holidays, medication changes, and lapses
+- review whether the original benefit occurred
+
+Regain is not a moral failure. Treat it as a systems and physiology problem: identify the changed environment, appetite, activity, support, or medical context and redesign the smallest useful part.
+
+## Example Answer Skeleton
+
+> Your goal is fat loss while keeping gym performance. The current two-week scale change is too noisy to justify another cut, especially after travel and higher-sodium meals. Keep the current food structure for two more weeks, use the same-condition weekly weight summary plus one waist measurement, and keep the lifting plan stable. Adjust only if both weight and waist remain flat across that window and the plan was actually repeatable. If recovery or food preoccupation worsens, move toward maintenance rather than pushing harder.

package/node_modules/@murphai/assistant-engine/skills/body-composition/references/muscle-gain.md

@@ -0,0 +1,135 @@
+# Lean-Mass Gain and Intentional Weight Gain
+
+Last reviewed: **2026-08-09**
+
+Use this file for a user who wants to gain muscle, gain body weight, bulk, improve strength with more mass, or decide whether a calorie surplus is warranted. Read `safety.md` first for underweight, unintentional loss, eating-disorder recovery, pregnancy, adolescence, major illness, post-surgical needs, or rapid restoration.
+
+## Separate Three Different Problems
+
+1. **Hypertrophy or lean-mass gain** — resistance training is the required signal; more scale weight is not the primary outcome.
+2. **Intentional general weight gain** — the user may value size, energy availability, sport position, comfort, or appearance even if some fat gain occurs.
+3. **Weight restoration** — underweight, malnutrition, illness, eating-disorder recovery, or unexplained loss requires clinician- or dietitian-led care rather than a bodybuilding bulk.
+
+Do not assume a thin user needs to gain, and do not assume every person asking to gain weight wants maximal muscle.
+
+## Progressive Resistance Training Is the Gate
+
+A surplus cannot substitute for a training stimulus.
+
+Before increasing food specifically for muscle gain, check:
+
+- whether resistance training is happening consistently
+- whether the program can progress load, repetitions, sets, range, technique, or exercise difficulty
+- whether target muscles receive enough recoverable work
+- whether sleep, pain, illness, schedule, and equipment allow progression
+- whether performance is already improving at maintenance
+
+Use `strength-training` for the program. If the user is new, detrained, returning after a break, or improving rapidly at maintenance, start there before forcing a surplus. Recomposition or maintenance may deliver most of the desired value with less unnecessary gain.
+
+## Energy Strategy
+
+Start with the smallest energy increase that solves the bottleneck.
+
+### Maintenance first
+
+Use when:
+
+- training has just started or resumed
+- current intake is poorly understood
+- strength and body measurements are already improving
+- the user wants minimal fat gain
+- appetite or digestion makes a bulk difficult
+- body-composition estimates are too noisy to justify a surplus
+
+### Small surplus
+
+Use when progressive training is established but body weight, performance, recovery, and circumferences show inadequate support over a meaningful window.
+
+- Use `nutrition-strategy` to implement one small, repeatable increase in the user’s real food system rather than a “dirty bulk.”
+- Keep food quality, fiber, training fuel, and medical or digestive constraints in that implementation.
+- Do not back-calculate a precise surplus from one week of scale change.
+
+Evidence for the ideal surplus and gain rate is limited. One small 2023 trial in trained lifters compared maintenance with intended surpluses near 5% and 15%. Faster gain mainly increased skinfolds and did not clearly improve most muscle or strength outcomes. It did not establish a universal optimal rate. Use a small, individualized rate and review it against performance, waist, recovery, and the user’s willingness to accept fat gain; experienced lifters and people prioritizing minimal fat gain should usually accept slower scale change.
+
+### Faster gain
+
+Do not recommend rapid catch-up gain for ordinary hypertrophy. Faster restoration may be appropriate in clinical care, but the treating team owns the rate and monitoring.
+
+## Protein and Food Adequacy
+
+Body composition owns deciding whether energy intake appears to limit the goal. `nutrition-strategy` owns protein targets, distribution, training fuel, and the concrete food plan.
+
+- Make total energy and protein adequacy part of the review without assuming exact intake from an incomplete log.
+- Do not treat a narrow “anabolic window” as the main bottleneck.
+- Do not solve probable total-energy or carbohydrate under-fueling with protein alone.
+- When the user wants a numerical target, load `nutrition-strategy` and use its current evidence-backed range instead of copying a second target into this skill.
+- Coordinate kidney disease, liver disease, pregnancy, eating-disorder recovery, and other medical nutrition needs with qualified care.
+
+The protein evidence remains in `evidence.md` for traceability; applying it belongs to the nutrition owner.
+
+## Appetite and Expenditure Bottlenecks
+
+Use this section to identify the next owner, not to build a second meal plan.
+
+When appetite is the bottleneck:
+
+- use `nutrition-strategy` for lower-volume, energy-dense, liquid, soft, timed, or prepared options that fit the user
+- use `gut-digestion` when recurring digestive symptoms determine the plan
+- investigate nausea, early satiety, reflux, swallowing difficulty, dental issues, medication effects, or gastrointestinal symptoms instead of coaching around them indefinitely
+
+When expenditure is high:
+
+- identify sport, steps, manual work, fidgeting, or long cardio volume
+- preserve valued activity rather than reflexively removing it
+- use `nutrition-strategy` for food around the highest-demand periods
+- coordinate concurrent endurance and strength work through the training owner
+- check low energy availability and RED-S signals
+
+## What to Track
+
+Use the minimum set that answers whether the plan is working:
+
+- same-condition weight trend
+- strength, repetitions, load, or training quality
+- one optional circumference relevant to the goal; use both waist and a target-muscle measure only when each can change a decision
+- appetite, digestion, energy, sleep, soreness, and recovery
+- optional food or protein estimate when it will change a decision
+
+Consumer “muscle mass” or “lean mass” from a BIA scale is not precise enough to validate small gains. Do not announce that a user gained a specific amount of muscle from a short-term device change.
+
+Progress photos are optional, private, and never required.
+
+## Adjustment Decision Order
+
+Before adding more food:
+
+1. Confirm at least two to four weeks of comparable data; trained lifters may need longer because true muscle gain is slow.
+2. Confirm the training stimulus progressed or was at least completed consistently.
+3. Check whether weight, waist, performance, and recovery tell a coherent story.
+4. Check appetite, digestion, illness, travel, sleep, and unplanned activity changes.
+5. Check whether the user actually wants faster gain enough to accept more fat gain.
+6. Add one small repeatable energy lever through `nutrition-strategy` and set a new review window.
+
+Before reducing food:
+
+1. Confirm the gain is faster than intended across a real trend, not a glycogen or sodium jump.
+2. Check whether creatine, carbohydrate increase, constipation, or inflammation explains part of it.
+3. Use waist and performance rather than body-fat percentage alone.
+4. Remove or shrink one surplus lever rather than imposing a cut.
+
+## When to End the Gain Phase
+
+End, pause, or move to maintenance when:
+
+- the performance, size, health, or personal objective is met
+- waist or other costs are rising faster than benefits
+- appetite, digestion, sleep, cardiometabolic markers, or quality of life worsen
+- training cannot currently provide a productive stimulus
+- the user no longer wants the tradeoff
+- a clinical issue or unexplained change appears
+
+Do not automatically prescribe a “cut” after every bulk. Maintenance may be the correct next phase.
+
+## Example Answer Skeleton
+
+> You want more muscle, but the main missing input is progressive training rather than calories: your weight is stable and you have not yet had a consistent program long enough to know whether maintenance is insufficient. Run the strength plan for four weeks, track the same-condition weekly weight summary plus two performance markers, and keep protein roughly adequate. Use the nutrition strategy only if performance and weight remain flat despite consistent training and recovery, then add one small repeatable food lever. That avoids turning an untested calorie estimate into unnecessary fat gain.