Hermes-agent

optional-skills/health/DESCRIPTION.md

@@ -0,0 +1 @@
+Health, wellness, and biometric integration skills — BCI wearables, neurofeedback, sleep tracking, and cognitive state monitoring.

optional-skills/health/fitness-nutrition/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: fitness-nutrition
+description: >
+  Gym workout planner and nutrition tracker. Search 690+ exercises by muscle,
+  equipment, or category via wger. Look up macros and calories for 380,000+
+  foods via USDA FoodData Central. Compute BMI, TDEE, one-rep max, macro
+  splits, and body fat — pure Python, no pip installs. Built for anyone
+  chasing gains, cutting weight, or just trying to eat better.
+platforms: [linux, macos, windows]
+version: 1.0.0
+authors:
+  - haileymarshall
+license: MIT
+metadata:
+  hermes:
+    tags: [health, fitness, nutrition, gym, workout, diet, exercise]
+    category: health
+    prerequisites:
+      commands: [curl, python3]
+required_environment_variables:
+  - name: USDA_API_KEY
+    prompt: "USDA FoodData Central API key (free)"
+    help: "Get one free at https://fdc.nal.usda.gov/api-key-signup/ — or skip to use DEMO_KEY with lower rate limits"
+    required_for: "higher rate limits on food/nutrition lookups (DEMO_KEY works without signup)"
+    optional: true
+---
+
+# Fitness & Nutrition
+
+Expert fitness coach and sports nutritionist skill. Two data sources
+plus offline calculators — everything a gym-goer needs in one place.
+
+**Data sources (all free, no pip dependencies):**
+
+- **wger** (https://wger.de/api/v2/) — open exercise database, 690+ exercises with muscles, equipment, images. Public endpoints need zero authentication.
+- **USDA FoodData Central** (https://api.nal.usda.gov/fdc/v1/) — US government nutrition database, 380,000+ foods. `DEMO_KEY` works instantly; free signup for higher limits.
+
+**Offline calculators (pure stdlib Python):**
+
+- BMI, TDEE (Mifflin-St Jeor), one-rep max (Epley/Brzycki/Lombardi), macro splits, body fat % (US Navy method)
+
+---
+
+## When to Use
+
+Trigger this skill when the user asks about:
+- Exercises, workouts, gym routines, muscle groups, workout splits
+- Food macros, calories, protein content, meal planning, calorie counting
+- Body composition: BMI, body fat, TDEE, caloric surplus/deficit
+- One-rep max estimates, training percentages, progressive overload
+- Macro ratios for cutting, bulking, or maintenance
+
+---
+
+## Procedure
+
+### Exercise Lookup (wger API)
+
+All wger public endpoints return JSON and require no auth. Always add
+`format=json` and `language=2` (English) to exercise queries.
+
+**Step 1 — Identify what the user wants:**
+
+- By muscle → use `/api/v2/exercise/?muscles={id}&language=2&status=2&format=json`
+- By category → use `/api/v2/exercise/?category={id}&language=2&status=2&format=json`
+- By equipment → use `/api/v2/exercise/?equipment={id}&language=2&status=2&format=json`
+- By name → use `/api/v2/exercise/search/?term={query}&language=english&format=json`
+- Full details → use `/api/v2/exerciseinfo/{exercise_id}/?format=json`
+
+**Step 2 — Reference IDs (so you don't need extra API calls):**
+
+Exercise categories:
+
+| ID | Category    |
+|----|-------------|
+| 8  | Arms        |
+| 9  | Legs        |
+| 10 | Abs         |
+| 11 | Chest       |
+| 12 | Back        |
+| 13 | Shoulders   |
+| 14 | Calves      |
+| 15 | Cardio      |
+
+Muscles:
+
+| ID | Muscle                    | ID | Muscle                  |
+|----|---------------------------|----|-------------------------|
+| 1  | Biceps brachii            | 2  | Anterior deltoid        |
+| 3  | Serratus anterior         | 4  | Pectoralis major        |
+| 5  | Obliquus externus         | 6  | Gastrocnemius           |
+| 7  | Rectus abdominis          | 8  | Gluteus maximus         |
+| 9  | Trapezius                 | 10 | Quadriceps femoris      |
+| 11 | Biceps femoris            | 12 | Latissimus dorsi        |
+| 13 | Brachialis                | 14 | Triceps brachii         |
+| 15 | Soleus                    |    |                         |
+
+Equipment:
+
+| ID | Equipment      |
+|----|----------------|
+| 1  | Barbell        |
+| 3  | Dumbbell       |
+| 4  | Gym mat        |
+| 5  | Swiss Ball     |
+| 6  | Pull-up bar    |
+| 7  | none (bodyweight) |
+| 8  | Bench          |
+| 9  | Incline bench  |
+| 10 | Kettlebell     |
+
+**Step 3 — Fetch and present results:**
+
+```bash
+# Search exercises by name
+QUERY="$1"
+ENCODED=$(python3 -c "import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))" "$QUERY")
+curl -s "https://wger.de/api/v2/exercise/search/?term=${ENCODED}&language=english&format=json" \
+  | python3 -c "
+import json,sys
+data=json.load(sys.stdin)
+for s in data.get('suggestions',[])[:10]:
+    d=s.get('data',{})
+    print(f\"  ID {d.get('id','?'):>4} | {d.get('name','N/A'):<35} | Category: {d.get('category','N/A')}\")
+"
+```
+
+```bash
+# Get full details for a specific exercise
+EXERCISE_ID="$1"
+curl -s "https://wger.de/api/v2/exerciseinfo/${EXERCISE_ID}/?format=json" \
+  | python3 -c "
+import json,sys,html,re
+data=json.load(sys.stdin)
+trans=[t for t in data.get('translations',[]) if t.get('language')==2]
+t=trans[0] if trans else data.get('translations',[{}])[0]
+desc=re.sub('<[^>]+>','',html.unescape(t.get('description','N/A')))
+print(f\"Exercise  : {t.get('name','N/A')}\")
+print(f\"Category  : {data.get('category',{}).get('name','N/A')}\")
+print(f\"Primary   : {', '.join(m.get('name_en','') for m in data.get('muscles',[])) or 'N/A'}\")
+print(f\"Secondary : {', '.join(m.get('name_en','') for m in data.get('muscles_secondary',[])) or 'none'}\")
+print(f\"Equipment : {', '.join(e.get('name','') for e in data.get('equipment',[])) or 'bodyweight'}\")
+print(f\"How to    : {desc[:500]}\")
+imgs=data.get('images',[])
+if imgs: print(f\"Image     : {imgs[0].get('image','')}\")
+"
+```
+
+```bash
+# List exercises filtering by muscle, category, or equipment
+# Combine filters as needed: ?muscles=4&equipment=1&language=2&status=2
+FILTER="$1"  # e.g. "muscles=4" or "category=11" or "equipment=3"
+curl -s "https://wger.de/api/v2/exercise/?${FILTER}&language=2&status=2&limit=20&format=json" \
+  | python3 -c "
+import json,sys
+data=json.load(sys.stdin)
+print(f'Found {data.get(\"count\",0)} exercises.')
+for ex in data.get('results',[]):
+    print(f\"  ID {ex['id']:>4} | muscles: {ex.get('muscles',[])} | equipment: {ex.get('equipment',[])}\")
+"
+```
+
+### Nutrition Lookup (USDA FoodData Central)
+
+Uses `USDA_API_KEY` env var if set, otherwise falls back to `DEMO_KEY`.
+DEMO_KEY = 30 requests/hour. Free signup key = 1,000 requests/hour.
+
+```bash
+# Search foods by name
+FOOD="$1"
+API_KEY="${USDA_API_KEY:-DEMO_KEY}"
+ENCODED=$(python3 -c "import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))" "$FOOD")
+curl -s "https://api.nal.usda.gov/fdc/v1/foods/search?api_key=${API_KEY}&query=${ENCODED}&pageSize=5&dataType=Foundation,SR%20Legacy" \
+  | python3 -c "
+import json,sys
+data=json.load(sys.stdin)
+foods=data.get('foods',[])
+if not foods: print('No foods found.'); sys.exit()
+for f in foods:
+    n={x['nutrientName']:x.get('value','?') for x in f.get('foodNutrients',[])}
+    cal=n.get('Energy','?'); prot=n.get('Protein','?')
+    fat=n.get('Total lipid (fat)','?'); carb=n.get('Carbohydrate, by difference','?')
+    print(f\"{f.get('description','N/A')}\")
+    print(f\"  Per 100g: {cal} kcal | {prot}g protein | {fat}g fat | {carb}g carbs\")
+    print(f\"  FDC ID: {f.get('fdcId','N/A')}\")
+    print()
+"
+```
+
+```bash
+# Detailed nutrient profile by FDC ID
+FDC_ID="$1"
+API_KEY="${USDA_API_KEY:-DEMO_KEY}"
+curl -s "https://api.nal.usda.gov/fdc/v1/food/${FDC_ID}?api_key=${API_KEY}" \
+  | python3 -c "
+import json,sys
+d=json.load(sys.stdin)
+print(f\"Food: {d.get('description','N/A')}\")
+print(f\"{'Nutrient':<40} {'Amount':>8} {'Unit'}\")
+print('-'*56)
+for x in sorted(d.get('foodNutrients',[]),key=lambda x:x.get('nutrient',{}).get('rank',9999)):
+    nut=x.get('nutrient',{}); amt=x.get('amount',0)
+    if amt and float(amt)>0:
+        print(f\"  {nut.get('name',''):<38} {amt:>8} {nut.get('unitName','')}\")
+"
+```
+
+### Offline Calculators
+
+Use the helper scripts in `scripts/` for batch operations,
+or run inline for single calculations:
+
+- `python3 scripts/body_calc.py bmi <weight_kg> <height_cm>`
+- `python3 scripts/body_calc.py tdee <weight_kg> <height_cm> <age> <M|F> <activity 1-5>`
+- `python3 scripts/body_calc.py 1rm <weight> <reps>`
+- `python3 scripts/body_calc.py macros <tdee_kcal> <cut|maintain|bulk>`
+- `python3 scripts/body_calc.py bodyfat <M|F> <neck_cm> <waist_cm> [hip_cm] <height_cm>`
+
+See `references/FORMULAS.md` for the science behind each formula.
+
+---
+
+## Pitfalls
+
+- wger exercise endpoint returns **all languages by default** — always add `language=2` for English
+- wger includes **unverified user submissions** — add `status=2` to only get approved exercises
+- USDA `DEMO_KEY` has **30 req/hour** — add `sleep 2` between batch requests or get a free key
+- USDA data is **per 100g** — remind users to scale to their actual portion size
+- BMI does not distinguish muscle from fat — high BMI in muscular people is not necessarily unhealthy
+- Body fat formulas are **estimates** (±3-5%) — recommend DEXA scans for precision
+- 1RM formulas lose accuracy above 10 reps — use sets of 3-5 for best estimates
+- wger's `exercise/search` endpoint uses `term` not `query` as the parameter name
+
+---
+
+## Verification
+
+After running exercise search: confirm results include exercise names, muscle groups, and equipment.
+After nutrition lookup: confirm per-100g macros are returned with kcal, protein, fat, carbs.
+After calculators: sanity-check outputs (e.g. TDEE should be 1500-3500 for most adults).
+
+---
+
+## Quick Reference
+
+| Task | Source | Endpoint |
+|------|--------|----------|
+| Search exercises by name | wger | `GET /api/v2/exercise/search/?term=&language=english` |
+| Exercise details | wger | `GET /api/v2/exerciseinfo/{id}/` |
+| Filter by muscle | wger | `GET /api/v2/exercise/?muscles={id}&language=2&status=2` |
+| Filter by equipment | wger | `GET /api/v2/exercise/?equipment={id}&language=2&status=2` |
+| List categories | wger | `GET /api/v2/exercisecategory/` |
+| List muscles | wger | `GET /api/v2/muscle/` |
+| Search foods | USDA | `GET /fdc/v1/foods/search?query=&dataType=Foundation,SR Legacy` |
+| Food details | USDA | `GET /fdc/v1/food/{fdcId}` |
+| BMI / TDEE / 1RM / macros | offline | `python3 scripts/body_calc.py` |

optional-skills/health/fitness-nutrition/references/FORMULAS.md

@@ -0,0 +1,100 @@
+# Formulas Reference
+
+Scientific references for all calculators used in the fitness-nutrition skill.
+
+## BMI (Body Mass Index)
+
+**Formula:** BMI = weight (kg) / height (m)²
+
+| Category     | BMI Range  |
+|-------------|------------|
+| Underweight | < 18.5     |
+| Normal      | 18.5 – 24.9 |
+| Overweight  | 25.0 – 29.9 |
+| Obese       | 30.0+      |
+
+**Limitation:** BMI does not distinguish muscle from fat. A muscular person
+can have a high BMI while being lean. Use body fat % for a better picture.
+
+Reference: Quetelet, A. (1832). Keys et al., Int J Obes (1972).
+
+## TDEE (Total Daily Energy Expenditure)
+
+Uses the **Mifflin-St Jeor equation** — the most accurate BMR predictor for
+the general population according to the ADA (2005).
+
+**BMR formulas:**
+
+- Male: BMR = 10 × weight(kg) + 6.25 × height(cm) − 5 × age + 5
+- Female: BMR = 10 × weight(kg) + 6.25 × height(cm) − 5 × age − 161
+
+**Activity multipliers:**
+
+| Level | Description                    | Multiplier |
+|-------|--------------------------------|------------|
+| 1     | Sedentary (desk job)           | 1.200      |
+| 2     | Lightly active (1-3 days/wk)   | 1.375      |
+| 3     | Moderately active (3-5 days)   | 1.550      |
+| 4     | Very active (6-7 days)         | 1.725      |
+| 5     | Extremely active (2x/day)      | 1.900      |
+
+Reference: Mifflin et al., Am J Clin Nutr 51, 241-247 (1990).
+
+## One-Rep Max (1RM)
+
+Three validated formulas. Average of all three is most reliable.
+
+- **Epley:** 1RM = w × (1 + r/30)
+- **Brzycki:** 1RM = w × 36 / (37 − r)
+- **Lombardi:** 1RM = w × r^0.1
+
+All formulas are most accurate for r ≤ 10. Above 10 reps, error increases.
+
+Reference: LeSuer et al., J Strength Cond Res 11(4), 211-213 (1997).
+
+## Macro Splits
+
+Recommended splits based on goal:
+
+| Goal         | Protein | Fat  | Carbs | Calorie Offset |
+|-------------|---------|------|-------|----------------|
+| Fat loss    | 40%     | 30%  | 30%   | −500 kcal      |
+| Maintenance | 30%     | 30%  | 40%   | 0              |
+| Lean bulk   | 30%     | 25%  | 45%   | +400 kcal      |
+
+Protein targets for muscle growth: 1.6–2.2 g/kg body weight per day.
+Minimum fat intake: 0.5 g/kg to support hormone production.
+
+Conversion: Protein = 4 kcal/g, Fat = 9 kcal/g, Carbs = 4 kcal/g.
+
+Reference: Morton et al., Br J Sports Med 52, 376–384 (2018).
+
+## Body Fat % (US Navy Method)
+
+**Male:**
+
+BF% = 86.010 × log₁₀(waist − neck) − 70.041 × log₁₀(height) + 36.76
+
+**Female:**
+
+BF% = 163.205 × log₁₀(waist + hip − neck) − 97.684 × log₁₀(height) − 78.387
+
+All measurements in centimeters.
+
+| Category      | Male   | Female |
+|--------------|--------|--------|
+| Essential    | 2-5%   | 10-13% |
+| Athletic     | 6-13%  | 14-20% |
+| Fitness      | 14-17% | 21-24% |
+| Average      | 18-24% | 25-31% |
+| Obese        | 25%+   | 32%+   |
+
+Accuracy: ±3-5% compared to DEXA. Measure at the navel (waist),
+at the Adam's apple (neck), and widest point (hip, females only).
+
+Reference: Hodgdon & Beckett, Naval Health Research Center (1984).
+
+## APIs
+
+- wger: https://wger.de/api/v2/ — AGPL-3.0, exercise data is CC-BY-SA 3.0
+- USDA FoodData Central: https://api.nal.usda.gov/fdc/v1/ — public domain (CC0 1.0)

optional-skills/health/fitness-nutrition/scripts/body_calc.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+"""
+body_calc.py — All-in-one fitness calculator.
+
+Subcommands:
+  bmi      <weight_kg> <height_cm>
+  tdee     <weight_kg> <height_cm> <age> <M|F> <activity 1-5>
+  1rm      <weight> <reps>
+  macros   <tdee_kcal> <cut|maintain|bulk>
+  bodyfat  <M|F> <neck_cm> <waist_cm> [hip_cm] <height_cm>
+
+No external dependencies — stdlib only.
+"""
+import sys
+import math
+
+
+def bmi(weight_kg, height_cm):
+    h = height_cm / 100
+    val = weight_kg / (h * h)
+    if val < 18.5:
+        cat = "Underweight"
+    elif val < 25:
+        cat = "Normal weight"
+    elif val < 30:
+        cat = "Overweight"
+    else:
+        cat = "Obese"
+    print(f"BMI: {val:.1f} — {cat}")
+    print()
+    print("Ranges:")
+    print(f"  Underweight : < 18.5")
+    print(f"  Normal      : 18.5 – 24.9")
+    print(f"  Overweight  : 25.0 – 29.9")
+    print(f"  Obese       : 30.0+")
+
+
+def tdee(weight_kg, height_cm, age, sex, activity):
+    if sex.upper() == "M":
+        bmr = 10 * weight_kg + 6.25 * height_cm - 5 * age + 5
+    else:
+        bmr = 10 * weight_kg + 6.25 * height_cm - 5 * age - 161
+
+    multipliers = {
+        1: ("Sedentary (desk job, no exercise)", 1.2),
+        2: ("Lightly active (1-3 days/week)", 1.375),
+        3: ("Moderately active (3-5 days/week)", 1.55),
+        4: ("Very active (6-7 days/week)", 1.725),
+        5: ("Extremely active (athlete + physical job)", 1.9),
+    }
+
+    label, mult = multipliers.get(activity, ("Moderate", 1.55))
+    total = bmr * mult
+
+    print(f"BMR (Mifflin-St Jeor): {bmr:.0f} kcal/day")
+    print(f"Activity: {label} (x{mult})")
+    print(f"TDEE: {total:.0f} kcal/day")
+    print()
+    print("Calorie targets:")
+    print(f"  Aggressive cut (-750): {total - 750:.0f} kcal/day")
+    print(f"  Fat loss       (-500): {total - 500:.0f} kcal/day")
+    print(f"  Mild cut       (-250): {total - 250:.0f} kcal/day")
+    print(f"  Maintenance          : {total:.0f} kcal/day")
+    print(f"  Lean bulk      (+250): {total + 250:.0f} kcal/day")
+    print(f"  Bulk           (+500): {total + 500:.0f} kcal/day")
+
+
+def one_rep_max(weight, reps):
+    if reps < 1:
+        print("Error: reps must be at least 1.")
+        sys.exit(1)
+    if reps == 1:
+        print(f"1RM = {weight:.1f} (actual single)")
+        return
+
+    epley = weight * (1 + reps / 30)
+    brzycki = weight * (36 / (37 - reps)) if reps < 37 else 0
+    lombardi = weight * (reps ** 0.1)
+    avg = (epley + brzycki + lombardi) / 3
+
+    print(f"Estimated 1RM ({weight} x {reps} reps):")
+    print(f"  Epley    : {epley:.1f}")
+    print(f"  Brzycki  : {brzycki:.1f}")
+    print(f"  Lombardi : {lombardi:.1f}")
+    print(f"  Average  : {avg:.1f}")
+    print()
+    print("Training percentages off average 1RM:")
+    for pct, rep_range in [
+        (100, "1"), (95, "1-2"), (90, "3-4"), (85, "4-6"),
+        (80, "6-8"), (75, "8-10"), (70, "10-12"),
+        (65, "12-15"), (60, "15-20"),
+    ]:
+        print(f"  {pct:>3}% = {avg * pct / 100:>7.1f}  (~{rep_range} reps)")
+
+
+def macros(tdee_kcal, goal):
+    goal = goal.lower()
+    if goal in {"cut", "lose", "deficit"}:
+        cals = tdee_kcal - 500
+        p, f, c = 0.40, 0.30, 0.30
+        label = "Fat Loss (-500 kcal)"
+    elif goal in {"bulk", "gain", "surplus"}:
+        cals = tdee_kcal + 400
+        p, f, c = 0.30, 0.25, 0.45
+        label = "Lean Bulk (+400 kcal)"
+    else:
+        cals = tdee_kcal
+        p, f, c = 0.30, 0.30, 0.40
+        label = "Maintenance"
+
+    prot_g = cals * p / 4
+    fat_g = cals * f / 9
+    carb_g = cals * c / 4
+
+    print(f"Goal: {label}")
+    print(f"Daily calories: {cals:.0f} kcal")
+    print()
+    print(f"  Protein : {prot_g:>6.0f}g ({p * 100:.0f}%)  = {prot_g * 4:.0f} kcal")
+    print(f"  Fat     : {fat_g:>6.0f}g ({f * 100:.0f}%)  = {fat_g * 9:.0f} kcal")
+    print(f"  Carbs   : {carb_g:>6.0f}g ({c * 100:.0f}%)  = {carb_g * 4:.0f} kcal")
+    print()
+    print(f"Per meal (3 meals): P {prot_g / 3:.0f}g | F {fat_g / 3:.0f}g | C {carb_g / 3:.0f}g")
+    print(f"Per meal (4 meals): P {prot_g / 4:.0f}g | F {fat_g / 4:.0f}g | C {carb_g / 4:.0f}g")
+
+
+def bodyfat(sex, neck_cm, waist_cm, hip_cm, height_cm):
+    sex = sex.upper()
+    if sex == "M":
+        if waist_cm <= neck_cm:
+            print("Error: waist must be larger than neck."); sys.exit(1)
+        bf = 86.010 * math.log10(waist_cm - neck_cm) - 70.041 * math.log10(height_cm) + 36.76
+    else:
+        if (waist_cm + hip_cm) <= neck_cm:
+            print("Error: waist + hip must be larger than neck."); sys.exit(1)
+        bf = 163.205 * math.log10(waist_cm + hip_cm - neck_cm) - 97.684 * math.log10(height_cm) - 78.387
+
+    print(f"Estimated body fat: {bf:.1f}%")
+
+    if sex == "M":
+        ranges = [
+            (6, "Essential fat (2-5%)"),
+            (14, "Athletic (6-13%)"),
+            (18, "Fitness (14-17%)"),
+            (25, "Average (18-24%)"),
+        ]
+        default = "Obese (25%+)"
+    else:
+        ranges = [
+            (14, "Essential fat (10-13%)"),
+            (21, "Athletic (14-20%)"),
+            (25, "Fitness (21-24%)"),
+            (32, "Average (25-31%)"),
+        ]
+        default = "Obese (32%+)"
+
+    cat = default
+    for threshold, label in ranges:
+        if bf < threshold:
+            cat = label
+            break
+
+    print(f"Category: {cat}")
+    print(f"Method: US Navy circumference formula")
+
+
+def usage():
+    print(__doc__)
+    sys.exit(1)
+
+
+def main():
+    if len(sys.argv) < 2:
+        usage()
+
+    cmd = sys.argv[1].lower()
+
+    try:
+        if cmd == "bmi":
+            bmi(float(sys.argv[2]), float(sys.argv[3]))
+
+        elif cmd == "tdee":
+            tdee(
+                float(sys.argv[2]), float(sys.argv[3]),
+                int(sys.argv[4]), sys.argv[5], int(sys.argv[6]),
+            )
+
+        elif cmd in {"1rm", "orm"}:
+            one_rep_max(float(sys.argv[2]), int(sys.argv[3]))
+
+        elif cmd == "macros":
+            macros(float(sys.argv[2]), sys.argv[3])
+
+        elif cmd == "bodyfat":
+            sex = sys.argv[2]
+            if sex.upper() == "M":
+                bodyfat(sex, float(sys.argv[3]), float(sys.argv[4]), 0, float(sys.argv[5]))
+            else:
+                bodyfat(sex, float(sys.argv[3]), float(sys.argv[4]), float(sys.argv[5]), float(sys.argv[6]))
+
+        else:
+            print(f"Unknown command: {cmd}")
+            usage()
+
+    except (IndexError, ValueError) as e:
+        print(f"Error: {e}")
+        usage()
+
+
+if __name__ == "__main__":
+    main()

optional-skills/health/fitness-nutrition/scripts/nutrition_search.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""
+nutrition_search.py — Search USDA FoodData Central for nutrition info.
+
+Usage:
+  python3 nutrition_search.py "chicken breast"
+  python3 nutrition_search.py "rice" "eggs" "broccoli"
+  echo -e "oats\\nbanana\\nwhey protein" | python3 nutrition_search.py -
+
+Reads USDA_API_KEY from environment, falls back to DEMO_KEY.
+No external dependencies.
+"""
+import sys
+import os
+import json
+import time
+import urllib.request
+import urllib.parse
+
+API_KEY = os.environ.get("USDA_API_KEY", "DEMO_KEY")
+BASE = "https://api.nal.usda.gov/fdc/v1"
+
+
+def search(query, max_results=3):
+    encoded = urllib.parse.quote(query)
+    url = (
+        f"{BASE}/foods/search?api_key={API_KEY}"
+        f"&query={encoded}&pageSize={max_results}"
+        f"&dataType=Foundation,SR%20Legacy"
+    )
+    try:
+        req = urllib.request.Request(url, headers={"Accept": "application/json"})
+        with urllib.request.urlopen(req, timeout=15) as r:
+            return json.loads(r.read())
+    except Exception as e:
+        print(f"  API error: {e}", file=sys.stderr)
+        return None
+
+
+def display(food):
+    nutrients = {n["nutrientName"]: n.get("value", "?") for n in food.get("foodNutrients", [])}
+    cal = nutrients.get("Energy", "?")
+    prot = nutrients.get("Protein", "?")
+    fat = nutrients.get("Total lipid (fat)", "?")
+    carb = nutrients.get("Carbohydrate, by difference", "?")
+    fib = nutrients.get("Fiber, total dietary", "?")
+    sug = nutrients.get("Sugars, total including NLEA", "?")
+
+    print(f"  {food.get('description', 'N/A')}")
+    print(f"    Calories : {cal} kcal")
+    print(f"    Protein  : {prot}g")
+    print(f"    Fat      : {fat}g")
+    print(f"    Carbs    : {carb}g (fiber: {fib}g, sugar: {sug}g)")
+    print(f"    FDC ID   : {food.get('fdcId', 'N/A')}")
+
+
+def main():
+    if len(sys.argv) < 2:
+        print(__doc__)
+        sys.exit(1)
+
+    if sys.argv[1] == "-":
+        queries = [line.strip() for line in sys.stdin if line.strip()]
+    else:
+        queries = sys.argv[1:]
+
+    for query in queries:
+        print(f"\n--- {query.upper()} (per 100g) ---")
+        data = search(query, max_results=2)
+        if not data or not data.get("foods"):
+            print("  No results found.")
+        else:
+            for food in data["foods"]:
+                display(food)
+                print()
+        if len(queries) > 1:
+            time.sleep(1)  # respect rate limits
+
+    if API_KEY == "DEMO_KEY":
+        print("\nTip: using DEMO_KEY (30 req/hr). Set USDA_API_KEY for 1000 req/hr.")
+        print("Free signup: https://fdc.nal.usda.gov/api-key-signup/")
+
+
+if __name__ == "__main__":
+    main()

optional-skills/health/neuroskill-bci/SKILL.md

@@ -0,0 +1,459 @@
+---
+name: neuroskill-bci
+description: >
+  Connect to a running NeuroSkill instance and incorporate the user's real-time
+  cognitive and emotional state (focus, relaxation, mood, cognitive load, drowsiness,
+  heart rate, HRV, sleep staging, and 40+ derived EXG scores) into responses.
+  Requires a BCI wearable (Muse 2/S or OpenBCI) and the NeuroSkill desktop app
+  running locally.
+platforms: [linux, macos, windows]
+version: 1.0.0
+author: Hermes Agent + Nous Research
+license: MIT
+metadata:
+  hermes:
+    tags: [BCI, neurofeedback, health, focus, EEG, cognitive-state, biometrics, neuroskill]
+    category: health
+    related_skills: []
+---
+
+# NeuroSkill BCI Integration
+
+Connect Hermes to a running [NeuroSkill](https://neuroskill.com/) instance to read
+real-time brain and body metrics from a BCI wearable. Use this to give
+cognitively-aware responses, suggest interventions, and track mental performance
+over time.
+
+> **⚠️ Research Use Only** — NeuroSkill is an open-source research tool. It is
+> NOT a medical device and has NOT been cleared by the FDA, CE, or any regulatory
+> body. Never use these metrics for clinical diagnosis or treatment.
+
+See `references/metrics.md` for the full metric reference, `references/protocols.md`
+for intervention protocols, and `references/api.md` for the WebSocket/HTTP API.
+
+---
+
+## Prerequisites
+
+- **Node.js 20+** installed (`node --version`)
+- **NeuroSkill desktop app** running with a connected BCI device
+- **BCI hardware**: Muse 2, Muse S, or OpenBCI (4-channel EEG + PPG + IMU via BLE)
+- `npx neuroskill status` returns data without errors
+
+### Verify Setup
+```bash
+node --version                    # Must be 20+
+npx neuroskill status             # Full system snapshot
+npx neuroskill status --json      # Machine-parseable JSON
+```
+
+If `npx neuroskill status` returns an error, tell the user:
+- Make sure the NeuroSkill desktop app is open
+- Ensure the BCI device is powered on and connected via Bluetooth
+- Check signal quality — green indicators in NeuroSkill (≥0.7 per electrode)
+- If `command not found`, install Node.js 20+
+
+---
+
+## CLI Reference: `npx neuroskill <command>`
+
+All commands support `--json` (raw JSON, pipe-safe) and `--full` (human summary + JSON).
+
+| Command | Description |
+|---------|-------------|
+| `status` | Full system snapshot: device, scores, bands, ratios, sleep, history |
+| `session [N]` | Single session breakdown with first/second half trends (0=most recent) |
+| `sessions` | List all recorded sessions across all days |
+| `search` | ANN similarity search for neurally similar historical moments |
+| `compare` | A/B session comparison with metric deltas and trend analysis |
+| `sleep [N]` | Sleep stage classification (Wake/N1/N2/N3/REM) with analysis |
+| `label "text"` | Create a timestamped annotation at the current moment |
+| `search-labels "query"` | Semantic vector search over past labels |
+| `interactive "query"` | Cross-modal 4-layer graph search (text → EXG → labels) |
+| `listen` | Real-time event streaming (default 5s, set `--seconds N`) |
+| `umap` | 3D UMAP projection of session embeddings |
+| `calibrate` | Open calibration window and start a profile |
+| `timer` | Launch focus timer (Pomodoro/Deep Work/Short Focus presets) |
+| `notify "title" "body"` | Send an OS notification via the NeuroSkill app |
+| `raw '{json}'` | Raw JSON passthrough to the server |
+
+### Global Flags
+| Flag | Description |
+|------|-------------|
+| `--json` | Raw JSON output (no ANSI, pipe-safe) |
+| `--full` | Human summary + colorized JSON |
+| `--port <N>` | Override server port (default: auto-discover, usually 8375) |
+| `--ws` | Force WebSocket transport |
+| `--http` | Force HTTP transport |
+| `--k <N>` | Nearest neighbors count (search, search-labels) |
+| `--seconds <N>` | Duration for listen (default: 5) |
+| `--trends` | Show per-session metric trends (sessions) |
+| `--dot` | Graphviz DOT output (interactive) |
+
+---
+
+## 1. Checking Current State
+
+### Get Live Metrics
+```bash
+npx neuroskill status --json
+```
+
+**Always use `--json`** for reliable parsing. The default output is colorized
+human-readable text.
+
+### Key Fields in the Response
+
+The `scores` object contains all live metrics (0–1 scale unless noted):
+
+```jsonc
+{
+  "scores": {
+    "focus": 0.70,           // β / (α + θ) — sustained attention
+    "relaxation": 0.40,      // α / (β + θ) — calm wakefulness
+    "engagement": 0.60,      // active mental investment
+    "meditation": 0.52,      // alpha + stillness + HRV coherence
+    "mood": 0.55,            // composite from FAA, TAR, BAR
+    "cognitive_load": 0.33,  // frontal θ / temporal α · f(FAA, TBR)
+    "drowsiness": 0.10,      // TAR + TBR + falling spectral centroid
+    "hr": 68.2,              // heart rate in bpm (from PPG)
+    "snr": 14.3,             // signal-to-noise ratio in dB
+    "stillness": 0.88,       // 0–1; 1 = perfectly still
+    "faa": 0.042,            // Frontal Alpha Asymmetry (+ = approach)
+    "tar": 0.56,             // Theta/Alpha Ratio
+    "bar": 0.53,             // Beta/Alpha Ratio
+    "tbr": 1.06,             // Theta/Beta Ratio (ADHD proxy)
+    "apf": 10.1,             // Alpha Peak Frequency in Hz
+    "coherence": 0.614,      // inter-hemispheric coherence
+    "bands": {
+      "rel_delta": 0.28, "rel_theta": 0.18,
+      "rel_alpha": 0.32, "rel_beta": 0.17, "rel_gamma": 0.05
+    }
+  }
+}
+```
+
+Also includes: `device` (state, battery, firmware), `signal_quality` (per-electrode 0–1),
+`session` (duration, epochs), `embeddings`, `labels`, `sleep` summary, and `history`.
+
+### Interpreting the Output
+
+Parse the JSON and translate metrics into natural language. Never report raw
+numbers alone — always give them meaning:
+
+**DO:**
+> "Your focus is solid right now at 0.70 — that's flow state territory. Heart
+> rate is steady at 68 bpm and your FAA is positive, which suggests good
+> approach motivation. Great time to tackle something complex."
+
+**DON'T:**
+> "Focus: 0.70, Relaxation: 0.40, HR: 68"
+
+Key interpretation thresholds (see `references/metrics.md` for the full guide):
+- **Focus > 0.70** → flow state territory, protect it
+- **Focus < 0.40** → suggest a break or protocol
+- **Drowsiness > 0.60** → fatigue warning, micro-sleep risk
+- **Relaxation < 0.30** → stress intervention needed
+- **Cognitive Load > 0.70 sustained** → mind dump or break
+- **TBR > 1.5** → theta-dominant, reduced executive control
+- **FAA < 0** → withdrawal/negative affect — consider FAA rebalancing
+- **SNR < 3 dB** → unreliable signal, suggest electrode repositioning
+
+---
+
+## 2. Session Analysis
+
+### Single Session Breakdown
+```bash
+npx neuroskill session --json         # most recent session
+npx neuroskill session 1 --json       # previous session
+npx neuroskill session 0 --json | jq '{focus: .metrics.focus, trend: .trends.focus}'
+```
+
+Returns full metrics with **first-half vs second-half trends** (`"up"`, `"down"`, `"flat"`).
+Use this to describe how a session evolved:
+
+> "Your focus started at 0.64 and climbed to 0.76 by the end — a clear upward trend.
+> Cognitive load dropped from 0.38 to 0.28, suggesting the task became more automatic
+> as you settled in."
+
+### List All Sessions
+```bash
+npx neuroskill sessions --json
+npx neuroskill sessions --trends      # show per-session metric trends
+```
+
+---
+
+## 3. Historical Search
+
+### Neural Similarity Search
+```bash
+npx neuroskill search --json                    # auto: last session, k=5
+npx neuroskill search --k 10 --json             # 10 nearest neighbors
+npx neuroskill search --start <UTC> --end <UTC> --json
+```
+
+Finds moments in history that are neurally similar using HNSW approximate
+nearest-neighbor search over 128-D ZUNA embeddings. Returns distance statistics,
+temporal distribution (hour of day), and top matching days.
+
+Use this when the user asks:
+- "When was I last in a state like this?"
+- "Find my best focus sessions"
+- "When do I usually crash in the afternoon?"
+
+### Semantic Label Search
+```bash
+npx neuroskill search-labels "deep focus" --k 10 --json
+npx neuroskill search-labels "stress" --json | jq '[.results[].EXG_metrics.tbr]'
+```
+
+Searches label text using vector embeddings (Xenova/bge-small-en-v1.5). Returns
+matching labels with their associated EXG metrics at the time of labeling.
+
+### Cross-Modal Graph Search
+```bash
+npx neuroskill interactive "deep focus" --json
+npx neuroskill interactive "deep focus" --dot | dot -Tsvg > graph.svg
+```
+
+4-layer graph: query → text labels → EXG points → nearby labels. Use `--k-text`,
+`--k-EXG`, `--reach <minutes>` to tune.
+
+---
+
+## 4. Session Comparison
+```bash
+npx neuroskill compare --json                   # auto: last 2 sessions
+npx neuroskill compare --a-start <UTC> --a-end <UTC> --b-start <UTC> --b-end <UTC> --json
+```
+
+Returns metric deltas with absolute change, percentage change, and direction for
+~50 metrics. Also includes `insights.improved[]` and `insights.declined[]` arrays,
+sleep staging for both sessions, and a UMAP job ID.
+
+Interpret comparisons with context — mention trends, not just deltas:
+> "Yesterday you had two strong focus blocks (10am and 2pm). Today you've had one
+> starting around 11am that's still going. Your overall engagement is higher today
+> but there have been more stress spikes — your stress index jumped 15% and
+> FAA dipped negative more often."
+
+```bash
+# Sort metrics by improvement percentage
+npx neuroskill compare --json | jq '.insights.deltas | to_entries | sort_by(.value.pct) | reverse'
+```
+
+---
+
+## 5. Sleep Data
+```bash
+npx neuroskill sleep --json                     # last 24 hours
+npx neuroskill sleep 0 --json                   # most recent sleep session
+npx neuroskill sleep --start <UTC> --end <UTC> --json
+```
+
+Returns epoch-by-epoch sleep staging (5-second windows) with analysis:
+- **Stage codes**: 0=Wake, 1=N1, 2=N2, 3=N3 (deep), 4=REM
+- **Analysis**: efficiency_pct, onset_latency_min, rem_latency_min, bout counts
+- **Healthy targets**: N3 15–25%, REM 20–25%, efficiency >85%, onset <20 min
+
+```bash
+npx neuroskill sleep --json | jq '.summary | {n3: .n3_epochs, rem: .rem_epochs}'
+npx neuroskill sleep --json | jq '.analysis.efficiency_pct'
+```
+
+Use this when the user mentions sleep, tiredness, or recovery.
+
+---
+
+## 6. Labeling Moments
+```bash
+npx neuroskill label "breakthrough"
+npx neuroskill label "studying algorithms"
+npx neuroskill label "post-meditation"
+npx neuroskill label --json "focus block start"   # returns label_id
+```
+
+Auto-label moments when:
+- User reports a breakthrough or insight
+- User starts a new task type (e.g., "switching to code review")
+- User completes a significant protocol
+- User asks you to mark the current moment
+- A notable state transition occurs (entering/leaving flow)
+
+Labels are stored in a database and indexed for later retrieval via `search-labels`
+and `interactive` commands.
+
+---
+
+## 7. Real-Time Streaming
+```bash
+npx neuroskill listen --seconds 30 --json
+npx neuroskill listen --seconds 5 --json | jq '[.[] | select(.event == "scores")]'
+```
+
+Streams live WebSocket events (EXG, PPG, IMU, scores, labels) for the specified
+duration. Requires WebSocket connection (not available with `--http`).
+
+Use this for continuous monitoring scenarios or to observe metric changes in real-time
+during a protocol.
+
+---
+
+## 8. UMAP Visualization
+```bash
+npx neuroskill umap --json                      # auto: last 2 sessions
+npx neuroskill umap --a-start <UTC> --a-end <UTC> --b-start <UTC> --b-end <UTC> --json
+```
+
+GPU-accelerated 3D UMAP projection of ZUNA embeddings. The `separation_score`
+indicates how neurally distinct two sessions are:
+- **> 1.5** → Sessions are neurally distinct (different brain states)
+- **< 0.5** → Similar brain states across both sessions
+
+---
+
+## 9. Proactive State Awareness
+
+### Session Start Check
+At the beginning of a session, optionally run a status check if the user mentions
+they're wearing their device or asks about their state:
+```bash
+npx neuroskill status --json
+```
+
+Inject a brief state summary:
+> "Quick check-in: focus is building at 0.62, relaxation is good at 0.55, and your
+> FAA is positive — approach motivation is engaged. Looks like a solid start."
+
+### When to Proactively Mention State
+
+Mention cognitive state **only** when:
+- User explicitly asks ("How am I doing?", "Check my focus")
+- User reports difficulty concentrating, stress, or fatigue
+- A critical threshold is crossed (drowsiness > 0.70, focus < 0.30 sustained)
+- User is about to do something cognitively demanding and asks for readiness
+
+**Do NOT** interrupt flow state to report metrics. If focus > 0.75, protect the
+session — silence is the correct response.
+
+---
+
+## 10. Suggesting Protocols
+
+When metrics indicate a need, suggest a protocol from `references/protocols.md`.
+Always ask before starting — never interrupt flow state:
+
+> "Your focus has been declining for the past 15 minutes and TBR is climbing past
+> 1.5 — signs of theta dominance and mental fatigue. Want me to walk you through
+> a Theta-Beta Neurofeedback Anchor? It's a 90-second exercise that uses rhythmic
+> counting and breath to suppress theta and lift beta."
+
+Key triggers:
+- **Focus < 0.40, TBR > 1.5** → Theta-Beta Neurofeedback Anchor or Box Breathing
+- **Relaxation < 0.30, stress_index high** → Cardiac Coherence or 4-7-8 Breathing
+- **Cognitive Load > 0.70 sustained** → Cognitive Load Offload (mind dump)
+- **Drowsiness > 0.60** → Ultradian Reset or Wake Reset
+- **FAA < 0 (negative)** → FAA Rebalancing
+- **Flow State (focus > 0.75, engagement > 0.70)** → Do NOT interrupt
+- **High stillness + headache_index** → Neck Release Sequence
+- **Low RMSSD (< 25ms)** → Vagal Toning
+
+---
+
+## 11. Additional Tools
+
+### Focus Timer
+```bash
+npx neuroskill timer --json
+```
+Launches the Focus Timer window with Pomodoro (25/5), Deep Work (50/10), or
+Short Focus (15/5) presets.
+
+### Calibration
+```bash
+npx neuroskill calibrate
+npx neuroskill calibrate --profile "Eyes Open"
+```
+Opens the calibration window. Useful when signal quality is poor or the user
+wants to establish a personalized baseline.
+
+### OS Notifications
+```bash
+npx neuroskill notify "Break Time" "Your focus has been declining for 20 minutes"
+```
+
+### Raw JSON Passthrough
+```bash
+npx neuroskill raw '{"command":"status"}' --json
+```
+For any server command not yet mapped to a CLI subcommand.
+
+---
+
+## Error Handling
+
+| Error | Likely Cause | Fix |
+|-------|-------------|-----|
+| `npx neuroskill status` hangs | NeuroSkill app not running | Open NeuroSkill desktop app |
+| `device.state: "disconnected"` | BCI device not connected | Check Bluetooth, device battery |
+| All scores return 0 | Poor electrode contact | Reposition headband, moisten electrodes |
+| `signal_quality` values < 0.7 | Loose electrodes | Adjust fit, clean electrode contacts |
+| SNR < 3 dB | Noisy signal | Minimize head movement, check environment |
+| `command not found: npx` | Node.js not installed | Install Node.js 20+ |
+
+---
+
+## Example Interactions
+
+**"How am I doing right now?"**
+```bash
+npx neuroskill status --json
+```
+→ Interpret scores naturally, mentioning focus, relaxation, mood, and any notable
+  ratios (FAA, TBR). Suggest an action only if metrics indicate a need.
+
+**"I can't concentrate"**
+```bash
+npx neuroskill status --json
+```
+→ Check if metrics confirm it (high theta, low beta, rising TBR, high drowsiness).
+→ If confirmed, suggest an appropriate protocol from `references/protocols.md`.
+→ If metrics look fine, the issue may be motivational rather than neurological.
+
+**"Compare my focus today vs yesterday"**
+```bash
+npx neuroskill compare --json
+```
+→ Interpret trends, not just numbers. Mention what improved, what declined, and
+  possible causes.
+
+**"When was I last in a flow state?"**
+```bash
+npx neuroskill search-labels "flow" --json
+npx neuroskill search --json
+```
+→ Report timestamps, associated metrics, and what the user was doing (from labels).
+
+**"How did I sleep?"**
+```bash
+npx neuroskill sleep --json
+```
+→ Report sleep architecture (N3%, REM%, efficiency), compare to healthy targets,
+  and note any issues (high wake epochs, low REM).
+
+**"Mark this moment — I just had a breakthrough"**
+```bash
+npx neuroskill label "breakthrough"
+```
+→ Confirm label saved. Optionally note the current metrics to remember the state.
+
+---
+
+## References
+
+- [NeuroSkill Paper — arXiv:2603.03212](https://arxiv.org/abs/2603.03212) (Kosmyna & Hauptmann, MIT Media Lab)
+- [NeuroSkill Desktop App](https://github.com/NeuroSkill-com/skill) (GPLv3)
+- [NeuroLoop CLI Companion](https://github.com/NeuroSkill-com/neuroloop) (GPLv3)
+- [MIT Media Lab Project](https://www.media.mit.edu/projects/neuroskill/overview/)

optional-skills/health/neuroskill-bci/references/api.md

@@ -0,0 +1,286 @@
+# NeuroSkill WebSocket & HTTP API Reference
+
+NeuroSkill runs a local server (default port **8375**) discoverable via mDNS
+(`_skill._tcp`). It exposes both WebSocket and HTTP endpoints.
+
+---
+
+## Server Discovery
+
+```bash
+# Auto-discovery (built into the CLI — usually just works)
+npx neuroskill status --json
+
+# Manual port discovery
+NEURO_PORT=$(lsof -i -n -P | grep neuroskill | grep LISTEN | awk '{print $9}' | cut -d: -f2 | head -1)
+echo "NeuroSkill on port: $NEURO_PORT"
+```
+
+The CLI auto-discovers the port. Use `--port <N>` to override.
+
+---
+
+## HTTP REST Endpoints
+
+### Universal Command Tunnel
+```bash
+# POST / — accepts any command as JSON
+curl -s -X POST http://127.0.0.1:8375/ \
+  -H "Content-Type: application/json" \
+  -d '{"command":"status"}'
+```
+
+### Convenience Endpoints
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/v1/status` | System status |
+| GET | `/v1/sessions` | List sessions |
+| POST | `/v1/label` | Create label |
+| POST | `/v1/search` | ANN search |
+| POST | `/v1/compare` | A/B comparison |
+| POST | `/v1/sleep` | Sleep staging |
+| POST | `/v1/notify` | OS notification |
+| POST | `/v1/say` | Text-to-speech |
+| POST | `/v1/calibrate` | Open calibration |
+| POST | `/v1/timer` | Open focus timer |
+| GET | `/v1/dnd` | Get DND status |
+| POST | `/v1/dnd` | Force DND on/off |
+| GET | `/v1/calibrations` | List calibration profiles |
+| POST | `/v1/calibrations` | Create profile |
+| GET | `/v1/calibrations/{id}` | Get profile |
+| PATCH | `/v1/calibrations/{id}` | Update profile |
+| DELETE | `/v1/calibrations/{id}` | Delete profile |
+
+---
+
+## WebSocket Events (Broadcast)
+
+Connect to `ws://127.0.0.1:8375/` to receive real-time events:
+
+### EXG (Raw EEG Samples)
+```json
+{"event": "EXG", "electrode": 0, "samples": [12.3, -4.1, ...], "timestamp": 1740412800.512}
+```
+
+### PPG (Photoplethysmography)
+```json
+{"event": "PPG", "channel": 0, "samples": [...], "timestamp": 1740412800.512}
+```
+
+### IMU (Inertial Measurement Unit)
+```json
+{"event": "IMU", "ax": 0.01, "ay": -0.02, "az": 9.81, "gx": 0.1, "gy": -0.05, "gz": 0.02}
+```
+
+### Scores (Computed Metrics)
+```json
+{
+  "event": "scores",
+  "focus": 0.70, "relaxation": 0.40, "engagement": 0.60,
+  "rel_delta": 0.28, "rel_theta": 0.18, "rel_alpha": 0.32,
+  "rel_beta": 0.17, "hr": 68.2, "snr": 14.3
+}
+```
+
+### EXG Bands (Spectral Analysis)
+```json
+{"event": "EXG-bands", "channels": [...], "faa": 0.12}
+```
+
+### Labels
+```json
+{"event": "label", "label_id": 42, "text": "meditation start", "created_at": 1740413100}
+```
+
+### Device Status
+```json
+{"event": "muse-status", "state": "connected"}
+```
+
+---
+
+## JSON Response Formats
+
+### `status`
+```jsonc
+{
+  "command": "status", "ok": true,
+  "device": {
+    "state": "connected",     // "connected" | "connecting" | "disconnected"
+    "name": "Muse-A1B2",
+    "battery": 73,
+    "firmware": "1.3.4",
+    "EXG_samples": 195840,
+    "ppg_samples": 30600,
+    "imu_samples": 122400
+  },
+  "session": {
+    "start_utc": 1740412800,
+    "duration_secs": 1847,
+    "n_epochs": 369
+  },
+  "signal_quality": {
+    "tp9": 0.95, "af7": 0.88, "af8": 0.91, "tp10": 0.97
+  },
+  "scores": {
+    "focus": 0.70, "relaxation": 0.40, "engagement": 0.60,
+    "meditation": 0.52, "mood": 0.55, "cognitive_load": 0.33,
+    "drowsiness": 0.10, "hr": 68.2, "snr": 14.3, "stillness": 0.88,
+    "bands": { "rel_delta": 0.28, "rel_theta": 0.18, "rel_alpha": 0.32, "rel_beta": 0.17, "rel_gamma": 0.05 },
+    "faa": 0.042, "tar": 0.56, "bar": 0.53, "tbr": 1.06,
+    "apf": 10.1, "coherence": 0.614, "mu_suppression": 0.031
+  },
+  "embeddings": { "today": 342, "total": 14820, "recording_days": 31 },
+  "labels": { "total": 58, "recent": [{"id": 42, "text": "meditation start", "created_at": 1740413100}] },
+  "sleep": { "total_epochs": 1054, "wake_epochs": 134, "n1_epochs": 89, "n2_epochs": 421, "n3_epochs": 298, "rem_epochs": 112, "epoch_secs": 5 },
+  "history": { "total_sessions": 63, "recording_days": 31, "current_streak_days": 7, "total_recording_hours": 94.2, "longest_session_min": 187, "avg_session_min": 89 }
+}
+```
+
+### `sessions`
+```jsonc
+{
+  "command": "sessions", "ok": true,
+  "sessions": [
+    { "day": "20260224", "start_utc": 1740412800, "end_utc": 1740415510, "n_epochs": 541 },
+    { "day": "20260223", "start_utc": 1740380100, "end_utc": 1740382665, "n_epochs": 513 }
+  ]
+}
+```
+
+### `session` (single session breakdown)
+```jsonc
+{
+  "ok": true,
+  "metrics": { "focus": 0.70, "relaxation": 0.40, "n_epochs": 541 /* ... ~50 metrics */ },
+  "first":   { "focus": 0.64 /* first-half averages */ },
+  "second":  { "focus": 0.76 /* second-half averages */ },
+  "trends":  { "focus": "up", "relaxation": "down" /* "up" | "down" | "flat" */ }
+}
+```
+
+### `compare` (A/B comparison)
+```jsonc
+{
+  "command": "compare", "ok": true,
+  "insights": {
+    "deltas": {
+      "focus": { "a": 0.62, "b": 0.71, "abs": 0.09, "pct": 14.5, "direction": "up" },
+      "relaxation": { "a": 0.45, "b": 0.38, "abs": -0.07, "pct": -15.6, "direction": "down" }
+    },
+    "improved": ["focus", "engagement"],
+    "declined": ["relaxation"]
+  },
+  "sleep_a": { /* sleep summary for session A */ },
+  "sleep_b": { /* sleep summary for session B */ },
+  "umap": { "job_id": "abc123" }
+}
+```
+
+### `search` (ANN similarity)
+```jsonc
+{
+  "command": "search", "ok": true,
+  "result": {
+    "results": [{
+      "neighbors": [{ "distance": 0.12, "metadata": {"device": "Muse-A1B2", "date": "20260223"} }]
+    }],
+    "analysis": {
+      "distance_stats": { "mean": 0.15, "min": 0.08, "max": 0.42 },
+      "temporal_distribution": { /* hour-of-day distribution */ },
+      "top_days": [["20260223", 5], ["20260222", 3]]
+    }
+  }
+}
+```
+
+### `sleep` (sleep staging)
+```jsonc
+{
+  "command": "sleep", "ok": true,
+  "summary": { "total_epochs": 1054, "wake_epochs": 134, "n1_epochs": 89, "n2_epochs": 421, "n3_epochs": 298, "rem_epochs": 112, "epoch_secs": 5 },
+  "analysis": { "efficiency_pct": 87.3, "onset_latency_min": 12.5, "rem_latency_min": 65.0, "bouts": { /* wake/n3/rem bout counts and durations */ } },
+  "epochs": [{ "utc": 1740380100, "stage": 0, "rel_delta": 0.15, "rel_theta": 0.22, "rel_alpha": 0.38, "rel_beta": 0.20 }]
+}
+```
+
+### `label`
+```json
+{"command": "label", "ok": true, "label_id": 42}
+```
+
+### `search-labels` (semantic search)
+```jsonc
+{
+  "command": "search-labels", "ok": true,
+  "results": [{
+    "text": "deep focus block",
+    "EXG_metrics": { "focus": 0.82, "relaxation": 0.35, "engagement": 0.75, "hr": 65.0, "mood": 0.60 },
+    "EXG_start": 1740412800, "EXG_end": 1740412805,
+    "created_at": 1740412802,
+    "similarity": 0.92
+  }]
+}
+```
+
+### `umap` (3D projection)
+```jsonc
+{
+  "command": "umap", "ok": true,
+  "result": {
+    "points": [{ "x": 1.23, "y": -0.45, "z": 2.01, "session": "a", "utc": 1740412800 }],
+    "analysis": {
+      "separation_score": 1.84,
+      "inter_cluster_distance": 2.31,
+      "intra_spread_a": 0.82, "intra_spread_b": 0.94,
+      "centroid_a": [1.23, -0.45, 2.01],
+      "centroid_b": [-0.87, 1.34, -1.22]
+    }
+  }
+}
+```
+
+---
+
+## Useful `jq` Snippets
+
+```bash
+# Get just focus score
+npx neuroskill status --json | jq '.scores.focus'
+
+# Get all band powers
+npx neuroskill status --json | jq '.scores.bands'
+
+# Check device battery
+npx neuroskill status --json | jq '.device.battery'
+
+# Get signal quality
+npx neuroskill status --json | jq '.signal_quality'
+
+# Find improving metrics after a session
+npx neuroskill session 0 --json | jq '[.trends | to_entries[] | select(.value == "up") | .key]'
+
+# Sort comparison deltas by improvement
+npx neuroskill compare --json | jq '.insights.deltas | to_entries | sort_by(.value.pct) | reverse'
+
+# Get sleep efficiency
+npx neuroskill sleep --json | jq '.analysis.efficiency_pct'
+
+# Find closest neural match
+npx neuroskill search --json | jq '[.result.results[].neighbors[]] | sort_by(.distance) | .[0]'
+
+# Extract TBR from labeled stress moments
+npx neuroskill search-labels "stress" --json | jq '[.results[].EXG_metrics.tbr]'
+
+# Get session timestamps for manual compare
+npx neuroskill sessions --json | jq '{start: .sessions[0].start_utc, end: .sessions[0].end_utc}'
+```
+
+---
+
+## Data Storage
+
+- **Local database**: `~/.skill/YYYYMMDD/` (SQLite + HNSW index)
+- **ZUNA embeddings**: 128-D vectors, 5-second epochs
+- **Labels**: Stored in SQLite, indexed with bge-small-en-v1.5 embeddings
+- **All data is local** — nothing is sent to external servers

optional-skills/health/neuroskill-bci/references/metrics.md

@@ -0,0 +1,220 @@
+# NeuroSkill Metric Definitions & Interpretation Guide
+
+> **⚠️ Research Use Only:** All metrics are experimental and derived from
+> consumer-grade hardware (Muse 2/S). They are not FDA/CE-cleared and must not
+> be used for medical diagnosis or treatment.
+
+---
+
+## Hardware & Signal Acquisition
+
+NeuroSkill is validated for **Muse 2** and **Muse S** headbands (with OpenBCI
+support in the desktop app), streaming at **256 Hz** (EEG) and **64 Hz** (PPG).
+
+### Electrode Positions (International 10-20 System)
+| Channel | Electrode | Position | Primary Signals |
+|---------|-----------|----------|-----------------|
+| CH1 | TP9 | Left Mastoid | Auditory cortex, verbal memory, jaw-clench artifact |
+| CH2 | AF7 | Left Prefrontal | Executive function, approach motivation, eye blinks |
+| CH3 | AF8 | Right Prefrontal | Emotional regulation, vigilance, eye blinks |
+| CH4 | TP10 | Right Mastoid | Prosody, spatial hearing, non-verbal cognition |
+
+### Preprocessing Pipeline
+1. **Filtering**: High-pass (0.5 Hz), Low-pass (50/60 Hz), Notch filter
+2. **Spectral Analysis**: Hann-windowed FFT (512-sample window), Welch periodogram
+3. **GPU acceleration**: ~125ms latency via `gpu_fft`
+
+---
+
+## EEG Frequency Bands
+
+Relative power values (sum ≈ 1.0 across all bands):
+
+| Band | Range (Hz) | High Means | Low Means |
+|------|-----------|------------|-----------|
+| **Delta (δ)** | 1–4 | Deep sleep (N3), high-amplitude artifacts | Awake, alert |
+| **Theta (θ)** | 4–8 | Drowsiness, REM onset, creative ideation, cognitive load | Alert, focused |
+| **Alpha (α)** | 8–13 | Relaxed wakefulness, "alpha blocking" during effort | Active thinking, anxiety |
+| **Beta (β)** | 13–30 | Active concentration, problem-solving, alertness | Relaxed, unfocused |
+| **Gamma (γ)** | 30–50 | Higher-order processing, perceptual binding, memory | Baseline |
+
+### JSON Field Names
+```json
+"bands": {
+  "rel_delta": 0.28, "rel_theta": 0.18, "rel_alpha": 0.32,
+  "rel_beta": 0.17, "rel_gamma": 0.05
+}
+```
+
+---
+
+## Core Composite Scores (0–1 Scale)
+
+### Focus
+- **Formula**: σ(β / (α + θ)) — beta dominance over slow waves, sigmoid-mapped
+- **> 0.70**: Deep concentration, flow state, task absorption
+- **0.40–0.69**: Moderate attention, some mind-wandering
+- **< 0.40**: Distracted, fatigued, difficulty concentrating
+
+### Relaxation
+- **Formula**: σ(α / (β + θ)) — alpha dominance, sigmoid-mapped
+- **> 0.70**: Calm, stress-free, parasympathetic dominant
+- **0.40–0.69**: Mild tension present
+- **< 0.30**: Stressed, anxious, sympathetic dominant
+
+### Engagement
+- **0–1 scale**: Active mental investment and motivation
+- **> 0.70**: Mentally invested, motivated, active processing
+- **0.40–0.69**: Passive participation
+- **< 0.30**: Bored, disengaged, autopilot mode
+
+### Meditation
+- **Composite**: Combines alpha elevation, physical stillness (IMU), and HRV coherence
+- **> 0.70**: Deep meditative state
+- **< 0.30**: Active, non-meditative
+
+### Mood
+- **Composite**: Derived from FAA, TAR, and BAR
+- **> 0.60**: Positive affect, approach motivation
+- **< 0.40**: Low mood, withdrawal tendency
+
+### Cognitive Load
+- **Formula**: (P_θ_frontal / P_α_temporal) · f(FAA, TBR) — working memory usage
+- **> 0.70**: Working memory near capacity, complex processing
+- **0.40–0.69**: Moderate mental effort
+- **< 0.40**: Task is easy or automatic
+- **Interpretation**: High load + high focus = productive struggle. High load + low focus = overwhelmed.
+
+### Drowsiness
+- **Composite**: Weighted TAR + TBR + falling Spectral Centroid
+- **> 0.60**: Sleep pressure building, micro-sleep risk
+- **0.30–0.59**: Mild fatigue
+- **< 0.30**: Alert
+
+---
+
+## EEG Ratios & Spectral Indices
+
+| Metric | Formula | Interpretation |
+|--------|---------|----------------|
+| **FAA** | ln(P_α_AF8) − ln(P_α_AF7) | Frontal Alpha Asymmetry. Positive = approach/positive affect. Negative = withdrawal/depression. |
+| **TAR** | P_θ / P_α | Theta/Alpha Ratio. > 1.5 = drowsiness or mind-wandering. |
+| **BAR** | P_β / P_α | Beta/Alpha Ratio. > 1.5 = alert, engaged cognition. Can also indicate anxiety. |
+| **TBR** | P_θ / P_β | Theta/Beta Ratio. ADHD biomarker. Healthy ≈ 1.0, elevated > 1.5, clinical > 3.0. |
+| **APF** | argmax_f PSD(f) in [7.5, 12.5] Hz | Alpha Peak Frequency. Typical 8–12 Hz. Higher = faster cognitive processing. Slows with age/fatigue. |
+| **SNR** | 10 · log₁₀(P_signal / P_noise) | Signal-to-Noise Ratio. > 10 dB = clean, 3–10 dB = usable, < 3 dB = unreliable. |
+| **Coherence** | Inter-hemispheric coherence (0–1) | Cortical connectivity between hemispheres. |
+| **Mu Suppression** | Motor cortex suppression index | Low values during movement or motor imagery. |
+
+---
+
+## Complexity & Nonlinear Metrics
+
+| Metric | Description | Healthy Range |
+|--------|-------------|---------------|
+| **Permutation Entropy (PE)** | Temporal complexity. Near 1 = maximally irregular. | Consciousness marker |
+| **Higuchi Fractal Dimension (HFD)** | Waveform self-similarity. | Waking: 1.3–1.8; higher = complex |
+| **DFA Exponent** | Long-range correlations. | Healthy: 0.6–0.9 |
+| **PSE** | Power Spectral Entropy. Near 1.0 = white noise. | Lower = organized brain state |
+| **PAC θ-γ** | Phase-Amplitude Coupling, theta-gamma. | Working memory mechanism |
+| **BPS** | Band-Power Slope (1/f spectral exponent). | Steeper = inhibition-dominated |
+
+---
+
+## Consciousness Metrics
+
+Derived from the nonlinear metrics above:
+
+| Metric | Scale | Interpretation |
+|--------|-------|----------------|
+| **LZC** | 0–100 | Lempel-Ziv Complexity proxy (PE + HFD). > 60 = wakefulness. |
+| **Wakefulness** | 0–100 | Inverse drowsiness composite. |
+| **Integration** | 0–100 | Cortical integration (Coherence × PAC × Spectral Entropy). |
+
+Status thresholds: ≥ 50 Green, 25–50 Yellow, < 25 Red.
+
+---
+
+## Cardiac & Autonomic Metrics (from PPG)
+
+| Metric | Description | Normal / Green Range |
+|--------|-------------|---------------------|
+| **HR** | Heart rate (bpm) | 55–90 (green), 45–110 (yellow), else red |
+| **RMSSD** | Primary vagal tone marker (ms) | > 50 ms healthy, < 20 ms stress |
+| **SDNN** | HRV time-domain variability (ms) | Higher = better |
+| **pNN50** | Parasympathetic indicator (%) | Higher = more parasympathetic activity |
+| **LF/HF Ratio** | Sympatho-vagal balance | > 2.0 = stress, < 0.5 = relaxation |
+| **Stress Index** | Baevsky SI: AMo / (2 × MxDMn × Mo) | 0–100 composite. > 200 raw = strong stress |
+| **SpO₂ Estimate** | Blood oxygen saturation (uncalibrated) | 95–100% normal (research only) |
+| **Respiratory Rate** | Breaths per minute | 12–20 normal |
+
+---
+
+## Motion & Artifact Detection
+
+| Metric | Description |
+|--------|-------------|
+| **Stillness** | 0–1 (1 = perfectly still). From IMU accelerometer/gyroscope. |
+| **Blink Count** | Eye blinks detected (large spikes in AF7/AF8). Normal: 15–20/min. |
+| **Jaw Clench Count** | High-frequency EMG bursts (> 30 Hz) at TP9/TP10. |
+| **Nod Count** | Head nods detected via IMU. |
+| **Shake Count** | Head shakes detected via IMU. |
+| **Head Pitch/Roll** | Head orientation from IMU. |
+
+---
+
+## Signal Quality (Per Electrode)
+
+| Electrode | Range | Interpretation |
+|-----------|-------|----------------|
+| **TP9** | 0–1 | ≥ 0.9 = good, ≥ 0.7 = acceptable, < 0.7 = poor |
+| **AF7** | 0–1 | Same thresholds |
+| **AF8** | 0–1 | Same thresholds |
+| **TP10** | 0–1 | Same thresholds |
+
+If any electrode is below 0.7, recommend the user adjust the headband fit or
+moisten the electrode contacts.
+
+---
+
+## Sleep Staging
+
+Based on 5-second epochs using relative band-power ratios and AASM heuristics:
+
+| Stage | Code | EEG Signature | Function |
+|-------|------|---------------|----------|
+| Wake | 0 | Alpha-dominant, BAR > 0.8 | Conscious awareness |
+| N1 | 1 | Alpha → Theta transition | Light sleep onset |
+| N2 | 2 | Sleep spindles, K-complexes | Memory consolidation |
+| N3 (Deep) | 3 | Delta > 20% of epoch, DTR > 2 | Deep restorative sleep |
+| REM | 4 | Active EEG, high Theta, low Delta | Emotional processing, dreaming |
+
+### Healthy Adult Targets (~8h Sleep)
+- **N3 (Deep)**: 15–25% of total sleep
+- **REM**: 20–25%
+- **Sleep Efficiency**: > 85%
+- **Sleep Onset Latency**: < 20 min
+
+---
+
+## Composite State Patterns
+
+| Pattern | Key Metrics | Interpretation |
+|---------|-------------|----------------|
+| **Flow State** | Focus > 0.75, Engagement > 0.70, Cognitive Load 0.50–0.70, HR steady | Optimal performance zone — protect it |
+| **Mental Fatigue** | Focus < 0.40, Drowsiness > 0.60, TBR > 1.5, Theta elevated | Rest or break needed |
+| **Anxiety** | Relaxation < 0.30, HR elevated, high Beta, high BAR, stress_index high | Calming intervention helpful |
+| **Peak Alert** | Focus > 0.80, Engagement > 0.70, Drowsiness < 0.20 | Best time for hard tasks |
+| **Recovery** | Relaxation > 0.70, HRV (RMSSD) rising, Alpha dominant | Integration, light tasks only |
+| **Creative Mode** | High Theta, high Alpha, low Beta, moderate focus | Ideation — don't force structure |
+| **Withdrawal** | FAA < 0, low Mood, low Engagement | Approach motivation needed |
+
+---
+
+## ZUNA Embeddings
+
+NeuroSkill uses the **ZUNA Neural Encoder** to convert 5-second EEG epochs into
+**128-dimensional vectors** stored in an HNSW index:
+- **Search**: Sub-millisecond approximate nearest-neighbor queries
+- **UMAP**: GPU-accelerated 3D projection for visual comparison
+- **Storage**: Local SQLite + HNSW index in `~/.skill/YYYYMMDD/`

optional-skills/health/neuroskill-bci/references/protocols.md

@@ -0,0 +1,452 @@
+# NeuroSkill Guided Protocols
+
+Over 70 mind-body practices triggered by specific biometric (EXG) signals. These
+are sourced from NeuroLoop's protocol repertoire and are designed to be suggested
+when the system detects specific cognitive or physiological states.
+
+> **⚠️ Contraindication**: Wim Hof and hyperventilation-style breathwork are
+> unsuitable for epilepsy_risk > 30, known cardiac conditions, or pregnancy.
+
+---
+
+## When to Suggest Protocols
+
+**Always ask before starting.** Match ONE protocol to the single most salient
+metric signal. Explain the metric connection to the user.
+
+| User State | Recommended Protocol |
+|------------|---------------------|
+| Focus < 0.40, TBR > 1.5 | Theta-Beta Neurofeedback Anchor or Box Breathing |
+| Low engagement, session start | WOOP or Pre-Task Priming |
+| Relaxation < 0.30, stress_index high | Cardiac Coherence or 4-7-8 Breathing |
+| Cognitive Load > 0.70 sustained | Cognitive Load Offload (Mind Dump) |
+| Engagement < 0.30 for > 20 min | Novel Stimulation Burst or Environment Change |
+| Flow State (focus > 0.75, engagement > 0.70) | **Do NOT interrupt — protect the session** |
+| Drowsiness > 0.60, post-lunch | Ultradian Reset or Power Nap |
+| FAA < 0, depression_index elevated | FAA Rebalancing |
+| Low RMSSD (< 25ms) | Vagal Toning |
+| High stillness + headache signals | Neck Release Sequence |
+| Pre-sleep, HRV low | Sleep Wind-Down |
+| Post-social-media, low mood | Envy & Comparison Alchemy |
+
+---
+
+## Attention & Focus Protocols
+
+### Theta-Beta Neurofeedback Anchor
+**Duration**: ~90 seconds
+**Trigger**: High TBR (> 1.5) and low focus
+**Instructions**:
+1. Close your eyes
+2. Breathe slowly — 4s inhale, 6s exhale
+3. Count rhythmically from 1 to 10, matching your breath
+4. Focus on the counting — if you lose count, restart from 1
+5. Open your eyes after 4–5 full cycles
+**Effect**: Suppresses theta dominance and lifts beta activity
+
+### Focus Reset
+**Duration**: 90 seconds
+**Trigger**: Scattered engagement, difficulty settling into task
+**Instructions**:
+1. Close your eyes completely
+2. Take 5 slow, deep breaths
+3. Mentally state your intention for the next work block
+4. Open your eyes and begin immediately
+**Effect**: Resets attentional baseline
+
+### Working Memory Primer
+**Duration**: 3 minutes
+**Trigger**: Low PAC θ-γ (theta-gamma coupling), low sample entropy
+**Instructions**:
+1. Breathe at theta pace: 4s inhale, 6s exhale, 2s hold
+2. While breathing, do a verbal 3-back task: listen to or read a sequence
+   of numbers, say which number appeared 3 positions back
+3. Continue for 3 minutes
+**Effect**: Lifts theta-gamma coupling and working memory engagement
+
+### Creativity Unlock
+**Duration**: 5 minutes
+**Trigger**: High beta, low rel_alpha — system is too analytically locked
+**Instructions**:
+1. Stop all structured work
+2. Let your mind wander without a goal
+3. Doodle, look out the window, or listen to ambient sound
+4. Don't force any outcome — just observe what arises
+5. After 5 minutes, jot down any ideas that surfaced
+**Effect**: Promotes alpha and theta activity for creative ideation
+
+### Dual-N-Back Warm-Up
+**Duration**: 3 minutes
+**Trigger**: Low PAC θ-γ, low sample entropy
+**Instructions**:
+1. Read or listen to a sequence of spoken numbers
+2. Track which number appeared 2 positions back (2-back)
+3. If comfortable, increase to 3-back
+**Effect**: Activates prefrontal cortex, lifts executive function
+
+### Novel Stimulation Burst
+**Duration**: 2–3 minutes
+**Trigger**: Low APF (< 9 Hz), dementia_index > 30
+**Instructions**:
+1. Pick up an unusual object nearby and describe it in detail
+2. Name 5 things you can see, 4 you can touch, 3 you can hear
+3. Try a quick riddle or lateral thinking puzzle
+**Effect**: Counters cortical slowing, raises alpha peak frequency
+
+---
+
+## Autonomic & Stress Regulation Protocols
+
+### Box Breathing (4-4-4-4)
+**Duration**: 2–4 minutes
+**Trigger**: High BAR, high anxiety_index, acute stress
+**Instructions**:
+1. Inhale for 4 counts
+2. Hold for 4 counts
+3. Exhale for 4 counts
+4. Hold for 4 counts
+5. Repeat 4–8 cycles
+**Effect**: Engages parasympathetic nervous system, reduces beta activity
+
+### Extended Exhale (4-7-8)
+**Duration**: 3–5 minutes
+**Trigger**: Acute stress spikes, racing thoughts, high sympathetic activation
+**Instructions**:
+1. Exhale completely through mouth
+2. Inhale through nose for 4 counts
+3. Hold for 7 counts
+4. Exhale through mouth for 8 counts
+5. Repeat 4 cycles
+**Effect**: Fastest parasympathetic trigger for acute stress
+
+### Cardiac Coherence
+**Duration**: 5 minutes
+**Trigger**: Low RMSSD (< 30 ms), high stress_index
+**Instructions**:
+1. Breathe evenly: 5-second inhale, 5-second exhale
+2. Focus on the area around your heart
+3. Recall a positive memory or feeling of appreciation
+4. Maintain for 5 minutes
+**Effect**: Maximizes HRV, creates coherent heart rhythm pattern
+
+### Physiological Sigh
+**Duration**: 30 seconds (1–3 cycles)
+**Trigger**: Rapid overwhelm, acute panic
+**Instructions**:
+1. Take a quick double inhale through the nose (sniff-sniff)
+2. Follow with a long, slow exhale through the mouth
+3. Repeat 1–3 times
+**Effect**: Rapid parasympathetic activation, immediate calming
+
+### Alpha Induction (Open Focus)
+**Duration**: 5 minutes
+**Trigger**: High beta, low relaxation — cannot relax
+**Instructions**:
+1. Soften your gaze — don't focus on any single object
+2. Notice the space between and around objects
+3. Expand your awareness to peripheral vision
+4. Maintain this "open focus" for 5 minutes
+**Effect**: Promotes alpha wave production, reduces beta dominance
+
+### Open Monitoring
+**Duration**: 5–10 minutes
+**Trigger**: Low LZC (< 40 on 0-100 scale) — neural complexity too low
+**Instructions**:
+1. Sit comfortably with eyes closed or softly focused
+2. Don't direct attention to anything specific
+3. Simply notice whatever arises — thoughts, sounds, sensations
+4. Let each observation pass without engagement
+**Effect**: Raises neural complexity and consciousness metrics
+
+### Vagal Toning
+**Duration**: 3 minutes
+**Trigger**: Low RMSSD (< 25 ms) — weak vagal tone
+**Instructions**:
+1. Hum a long, steady note on each exhale for 30 seconds
+2. Alternatively: gargle cold water for 30 seconds
+3. Repeat 3–5 times
+**Effect**: Directly stimulates the vagus nerve, increases parasympathetic tone
+
+---
+
+## Emotional Regulation Protocols
+
+### FAA Rebalancing
+**Duration**: 5 minutes
+**Trigger**: Negative FAA (right-hemisphere dominant), high depression_index
+**Instructions**:
+1. Think of something you're genuinely looking forward to (approach motivation)
+2. Visualize yourself successfully completing a meaningful goal
+3. Squeeze your left hand into a fist for 10 seconds, release
+4. Repeat the visualization + left-hand squeeze 3–4 times
+**Effect**: Activates left prefrontal cortex, shifts FAA positive
+
+### Loving-Kindness (Metta)
+**Duration**: 5–10 minutes
+**Trigger**: Loneliness signals, shame, low mood
+**Instructions**:
+1. Close your eyes and think of someone you care about
+2. Silently repeat: "May you be happy. May you be healthy. May you be safe."
+3. Extend the same wishes to yourself
+4. Extend to a neutral person, then gradually to someone difficult
+**Effect**: Reduces withdrawal motivation, increases positive affect
+
+### Emotional Discharge
+**Duration**: 2 minutes
+**Trigger**: High bipolar_index or extreme FAA swings
+**Instructions**:
+1. Take 30 seconds of vigorous, fast breathing (safely)
+2. Stop and take 3 slow, deep breaths
+3. Do a 60-second body scan — notice where tension is held
+4. Shake out your hands and arms for 15 seconds
+**Effect**: Releases trapped sympathetic energy, recalibrates
+
+### Havening Touch
+**Duration**: 3–5 minutes
+**Trigger**: Acute distress, trauma activation, overwhelming anxiety
+**Instructions**:
+1. Gently stroke your arms from shoulder to elbow, palms down
+2. Rub your palms together slowly
+3. Gently touch your forehead, temples
+4. Continue for 3–5 minutes while breathing slowly
+**Effect**: Disrupts amygdala-cortex encoding loop, reduces distress
+
+### Anxiety Surfing
+**Duration**: ~8 minutes
+**Trigger**: Rising anxiety without clear cause
+**Instructions**:
+1. Notice where anxiety lives in your body — chest? stomach? throat?
+2. Describe the sensation without judging it (tight? hot? buzzing?)
+3. Breathe into that area for 3 breaths
+4. Notice: is it getting bigger, smaller, or changing shape?
+5. Continue observing for 5–8 minutes — anxiety typically peaks then subsides
+
+### Anger: Palm-Press Discharge
+**Duration**: 2 minutes
+**Trigger**: Anger signals, high BAR + elevated HR
+**Instructions**:
+1. Press your palms together firmly for 10 seconds
+2. Release and take 3 extended exhales (4s in, 8s out)
+3. Repeat 3–4 times
+
+### Envy & Comparison Alchemy
+**Duration**: 3 minutes
+**Trigger**: Post-social-media, envy signals
+**Instructions**:
+1. Name the envy: "I feel envious of ___"
+2. Ask: "What does this envy tell me I actually want?"
+3. Convert: "My next step toward that is ___"
+**Effect**: Converts envy into a desire-signal that identifies personal values
+
+### Awe Induction
+**Duration**: 3–5 minutes
+**Trigger**: Existential flatness, low engagement, loss of meaning
+**Instructions**:
+1. Imagine standing at the edge of the Grand Canyon, or beneath a starry sky
+2. Let yourself feel the scale — you are small, and that's beautiful
+3. Recall a moment of genuine wonder from your past
+4. Notice what changes in your body
+**Effect**: Counters hedonic adaptation, restores sense of meaning
+
+---
+
+## Sleep & Recovery Protocols
+
+### Ultradian Reset
+**Duration**: 20 minutes
+**Trigger**: End of a 90-minute focus block, drowsiness rising
+**Instructions**:
+1. Set a timer for 20 minutes
+2. No agenda — just rest (don't force sleep)
+3. Dim lights if possible, close eyes
+4. Let mind wander without structure
+**Effect**: Aligns with 90-minute ultradian rhythm, restores cognitive resources
+
+### Wake Reset
+**Duration**: 5 minutes
+**Trigger**: narcolepsy_index > 40, severe drowsiness
+**Instructions**:
+1. Splash cold water on your face and wrists
+2. Do 20 seconds of Kapalabhati breath (sharp nasal exhales)
+3. Expose yourself to bright light for 2–3 minutes
+**Effect**: Acute arousal response, suppresses drowsiness
+
+### NSDR (Non-Sleep Deep Rest / Yoga Nidra)
+**Duration**: 20–30 minutes
+**Trigger**: Accumulated fatigue, need deep recovery without sleeping
+**Instructions**:
+1. Lie on your back, palms up
+2. Close your eyes and do a slow body scan from toes to crown
+3. At each body part, notice sensation without changing anything
+4. If you fall asleep, that's fine — set an alarm
+**Effect**: Restores dopamine and cognitive resources without sleep inertia
+
+### Power Nap
+**Duration**: 10–20 minutes (set alarm!)
+**Trigger**: Drowsiness > 0.70, post-lunch slump, Theta dominant
+**Instructions**:
+1. Set alarm for 20 minutes maximum (avoids N3 sleep inertia)
+2. Lie down or recline
+3. Even if you don't fully sleep, rest with eyes closed
+4. On waking: 30 seconds of stretching before resuming work
+**Effect**: Restores focus and alertness for 2–3 hours
+
+### Sleep Wind-Down
+**Duration**: 60 minutes before bed
+**Trigger**: Evening session, rising drowsiness, pre-sleep
+**Instructions**:
+1. Dim all screens to night mode
+2. Stop new learning or complex tasks
+3. Do a mind dump of tomorrow's tasks
+4. 10 minutes of progressive relaxation or 4-7-8 breathing
+5. Keep room cool (65–68°F / 18–20°C)
+
+---
+
+## Somatic & Physical Protocols
+
+### Progressive Muscle Relaxation (PMR)
+**Duration**: 10 minutes
+**Trigger**: Relaxation < 0.25, HRV declining over session
+**Instructions**:
+1. Start with feet — tense for 5 seconds, release for 8–10 seconds
+2. Move upward: calves → thighs → abdomen → hands → arms → shoulders → face
+3. Hold each tension 5 seconds, release 8–10 seconds
+4. End with 3 deep breaths
+
+### Grounding (5-4-3-2-1)
+**Duration**: 3 minutes
+**Trigger**: Panic, dissociation, acute anxiety spike
+**Instructions**:
+1. Name 5 things you can see
+2. Name 4 things you can touch
+3. Name 3 things you can hear
+4. Name 2 things you can smell
+5. Name 1 thing you can taste
+
+### 20-20-20 Vision Reset
+**Duration**: 20 seconds
+**Trigger**: Extended screen time, eye strain
+**Instructions**:
+1. Every 20 minutes of screen time
+2. Look at something 20 feet away
+3. For 20 seconds
+
+### Neck Release Sequence
+**Duration**: 3 minutes
+**Trigger**: High stillness (> 0.85) + headache_index elevated
+**Instructions**:
+1. Ear-to-shoulder tilt — hold 15 seconds each side
+2. Chin tucks — 10 reps (pull chin straight back)
+3. Gentle neck circles — 5 each direction
+4. Shoulder shrugs — 10 reps (squeeze up, release)
+
+### Motor Cortex Activation
+**Duration**: 2 minutes
+**Trigger**: Very high stillness, prolonged static sitting
+**Instructions**:
+1. Cross-body movements: touch right hand to left knee, alternate 10 times
+2. Shake out hands and feet for 15 seconds
+3. Roll ankles and wrists 5 times each direction
+**Effect**: Resets proprioception, activates motor cortex
+
+### Cognitive Load Offload (Mind Dump)
+**Duration**: 5 minutes
+**Trigger**: Cognitive load > 0.70 sustained, racing thoughts, high beta
+**Instructions**:
+1. Open a blank document or grab paper
+2. Write everything on your mind without filtering or organizing
+3. Brain-dump worries, tasks, ideas — anything occupying working memory
+4. Close the document (review later if needed)
+**Effect**: Externalizing working memory can reduce cognitive load by 20–40%
+
+---
+
+## Digital & Lifestyle Protocols
+
+### Craving Surf
+**Duration**: 90 seconds
+**Trigger**: Phone addiction signals, urge to check social media
+**Instructions**:
+1. Notice the urge to check your phone
+2. Don't act on it — just observe for 90 seconds
+3. Notice: does the urge peak and then fade?
+4. Resume what you were doing
+**Effect**: Breaks automatic dopamine-seeking loop
+
+### Dopamine Palette Reset
+**Duration**: Ongoing
+**Trigger**: Flatness from short-form content spikes
+**Instructions**:
+1. Identify activities that provide sustained reward (reading, cooking, walking)
+2. Replace 15 minutes of scrolling with one sustained-reward activity
+3. Track mood before/after for 3 days
+
+### Digital Sunset
+**Duration**: 60–90 minutes before bed
+**Trigger**: Evening, pre-sleep routine
+**Instructions**:
+1. Hard stop on all screens 60–90 minutes before bed
+2. Switch to non-screen activities: reading, conversation, stretching
+3. If screens are necessary, use night mode at minimum brightness
+
+---
+
+## Dietary Protocols
+
+### Caffeine Timing
+**Trigger**: Morning routine, anxiety_index
+**Guidelines**:
+- Consume caffeine 90–120 minutes after waking (cortisol has already peaked)
+- None after 2 PM (half-life ~6 hours)
+- If anxiety_index > 50, stack with L-theanine (200mg) to smooth the curve
+
+### Post-Meal Energy Crash
+**Trigger**: Post-lunch drowsiness spike
+**Instructions**:
+1. 5-minute brisk walk immediately after eating
+2. 10 minutes of sunlight exposure
+**Effect**: Counters post-prandial drowsiness
+
+---
+
+## Motivation & Planning Protocols
+
+### WOOP (Wish, Outcome, Obstacle, Plan)
+**Duration**: 5 minutes
+**Trigger**: Low engagement before a task
+**Instructions**:
+1. **Wish**: What do you want to accomplish in this session?
+2. **Outcome**: What's the best possible result? Visualize it.
+3. **Obstacle**: What internal obstacle might get in the way?
+4. **Plan**: "If [obstacle], then I will [action]."
+**Effect**: Mental contrasting improves follow-through by 2–3x
+
+### Pre-Task Priming
+**Duration**: 3 minutes
+**Trigger**: Low engagement at session start, drowsiness < 0.50
+**Instructions**:
+1. Set a clear intention for the next work block
+2. Write down the single most important task
+3. Do 10 jumping jacks or 20 deep breaths
+4. Start with the easiest sub-task to build momentum
+
+---
+
+## Protocol Execution Guidelines
+
+When guiding the user through a protocol:
+1. **Match one protocol** to the single most salient metric signal
+2. **Explain the metric connection** — why this protocol for this state
+3. **Ask permission** — never start without the user's consent
+4. **Announce each step** clearly with timing
+5. **Check in after** — run `npx neuroskill status --json` to see if metrics improved
+6. **Label the moment** — `npx neuroskill label "post-protocol: [name]"` for tracking
+
+### Timing Guidelines for Step-by-Step Guidance
+- Breath inhale: 3–5 seconds
+- Breath hold: 2–4 seconds
+- Breath exhale: 4–8 seconds
+- Muscle tense: 5 seconds
+- Muscle release: 8–10 seconds
+- Body-scan region: 10–15 seconds