Add doc

docs/kaya-transition.md

@@ -0,0 +1,190 @@
+# Feeding Transition Calculator — Implementation Guide (30 kg adult)
+
+## 1) Purpose & principle
+
+- The calculator **keeps energy intake continuous** while transitioning from kibble (current) to gently cooked (GC, target).
+    
+- Internally it uses the **kibble chart’s month-level precision**; externally it **communicates in GC phases** (<5 mo, 5–6 mo, 7–12 mo).
+    
+
+* * *
+
+## 2) Fixed scope
+
+- Dog profile: **30 kg adult** only.
+    
+- Supported ages: **2.0 to 12.0 months** inclusive.  
+    If the user enters a value outside this range, **clamp** to the nearest bound and show a subtle note.
+    
+- Required configuration at runtime: **kibble energy density (kcal per 100 g)**.  
+    If missing, show an error and do not compute.
+    
+
+* * *
+
+## 3) Data you must hard-code
+
+1.  **Kibble reference points (grams/day, 30 kg column):**  
+    (2→250), (3→330), (4→365), (6→400), (8→410), (10→410), (12→405).
+    
+2.  **Interpolated monthly kibble (round to whole grams):**
+    
+
+- 2 mo: 250
+    
+- 3 mo: 330
+    
+- 4 mo: 365
+    
+- 5 mo: 382
+    
+- 6 mo: 400
+    
+- 7 mo: 405
+    
+- 8 mo: 410
+    
+- 9 mo: 410
+    
+- 10 mo: 410
+    
+- 11 mo: 408
+    
+- 12 mo: 405
+    
+
+3.  **GC communication buckets and ranges (g/day):**
+
+- **< 5 months** (covers 2.0–4.999… mo): **950–1350**
+    
+- **5–6 months** (covers 5.0–6.999… mo): **1250–1550**
+    
+- **7–12 months** (covers 7.0–12.0 mo): **1300–1500**
+    
+
+**Boundary rule:** exact 5.0 and 7.0 belong to the **later** bucket (5.0 → “5–6”, 7.0 → “7–12”).
+
+* * *
+
+## 4) How to calculate results (conceptual, no code)
+
+### A) Kibble grams/day at any age (2.0–12.0)
+
+- Use **linear interpolation** between the nearest kibble reference points listed above.
+    
+- Round the resulting kibble grams/day to **whole grams** (or to the nearest **5 g** if the user enables a rounding toggle).
+    
+
+### B) GC bucket assignment
+
+- Based on the **age**, assign the corresponding GC bucket and attach that bucket’s **low/high range** (g/day).
+
+### C) Energy-matched GC grams/day (the backbone)
+
+- Convert kibble grams/day to **kcal/day** using the **user-provided** kibble energy density (kcal/100 g).
+    
+- Convert kcal/day to **GC grams/day** using GC’s energy density **115 kcal per 100 g**.  
+    (Equivalently, GC provides **1.15 kcal per gram**.)
+    
+- Round to **whole grams** (or to **nearest 5 g** if the user toggled it).
+    
+
+### D) Range status
+
+- Compare the **energy-matched GC grams/day** to the GC bucket’s **low/high**:
+    
+    - “within” if inside \[low, high\]
+        
+    - “below” if under the low
+        
+    - “above” if over the high  
+        (Do **not** alter the energy-matched amount; just flag it.)
+        
+
+### E) Transition schedule (blended days)
+
+- Default to **7 days** (configurable).
+    
+- Linearly ramp daily fractions from **100% kibble / 0% GC** on Day 1 to **0% kibble / 100% GC** on the last day, in equal steps.
+    
+- Each day’s grams = (kibble grams/day × kibble fraction) + (GC grams/day × GC fraction).  
+    Round after multiplying (whole grams or nearest 5 g per the user setting).
+    
+
+* * *
+
+## 5) What to display (UX rules)
+
+1.  **Primary number:** “Gently cooked (energy-matched): **X g/day**”.  
+    Directly below, show the GC bucket label and its range (e.g., “7–12 months: 1300–1500 g/day”) plus a small **status chip** (within/below/above).
+    
+2.  **Context line:** “Based on your kibble energy density: **Y kcal / 100 g**” with an edit control.
+    
+3.  **Age input:** accept decimals (e.g., 5.5 months).  
+    Add tick marks at 2, 3, 4, 6, 8, 10, 12 (the original kibble points).
+    
+4.  **Transition widget:** a simple 5–7 day table or bar chart that shows **kibble g** and **GC g** per day, plus the day total.  
+    (Totals will typically increase during the transition because GC is less energy-dense; this is expected.)
+    
+5.  **Rounding toggle:** whole grams vs nearest 5 g.
+    
+6.  **Download/export:** CSV with columns:  
+    age_months, kibble_g_per_day, kibble_kcal_per_100g, kcal_per_day, gc_energy_matched_g_per_day, gc_bucket_name, gc_low_g, gc_high_g, range_status, and per-day transition grams.
+    
+
+* * *
+
+## 6) Validation & edge cases
+
+- **Missing kibble kcal density:** block calculation and display a clear prompt to enter kcal/100 g.
+    
+- **Age outside 2–12 months:** clamp to the nearest bound; show a subtle informational note.
+    
+- **Energy-matched GC outside bucket range:** keep the energy-matched number; display the status chip and a short educational tooltip (growth varies; this tool prioritizes energy continuity).
+    
+- **Rounding:** perform all math in floating point; **round only for display** (and for the per-day plan after multiplying by fractions).
+    
+
+* * *
+
+## 7) Acceptance checks (use these to verify)
+
+- At **5.5 months** with **380 kcal/100 g** kibble:
+    
+    - Interpolated kibble ≈ **391 g/day**.
+        
+    - Kcal/day ≈ **1,486 kcal**.
+        
+    - Energy-matched GC ≈ **1,292 g/day**.
+        
+    - GC bucket “5–6 months” (1,250–1,550) → **within**.
+        
+- At **8.0 months** with **380 kcal/100 g** kibble:
+    
+    - Kibble ≈ **410 g/day** → ≈ **1,558 kcal/day** → GC ≈ **1,355 g/day**.
+        
+    - GC bucket “7–12 months” (1,300–1,500) → **within**.
+        
+- At **2.0 months** with **380 kcal/100 g** kibble:
+    
+    - Kibble **250 g/day** → **950 kcal/day** → GC **≈ 826 g/day**.
+        
+    - GC bucket “<5 months” (950–1,350) → **below** (expected for some formulas).
+        
+
+* * *
+
+## 8) Deliverables checklist
+
+- Precise monthly interpolation (ready values above).
+    
+- Age-aware GC bucket labelling and ranges.
+    
+- Energy-matched GC grams/day with status flag.
+    
+- Configurable transition length; per-day blend table.
+    
+- Rounding control.
+    
+
+