docs(website): dedicated page per bundled + optional skill (#14929)

Generates a full dedicated Docusaurus page for every one of the 132 skills (73 bundled + 59 optional) under website/docs/user-guide/skills/{bundled,optional}/<category>/. Each page carries the skill's description, metadata (version, author, license, dependencies, platform gating, tags, related skills cross-linked to their own pages), and the complete SKILL.md body that Hermes loads at runtime. Previously the two catalog pages just listed skills with a one-line blurb and no way to see what the skill actually did — users had to go read the source repo. Now every skill has a browsable, searchable, cross-linked reference in the docs. - website/scripts/generate-skill-docs.py — generator that reads skills/ and optional-skills/, writes per-skill pages, regenerates both catalog indexes, and rewrites the Skills section of sidebars.ts. Handles MDX escaping (outside fenced code blocks: curly braces, unsafe HTML-ish tags) and rewrites relative references/*.md links to point at the GitHub source. - website/docs/reference/skills-catalog.md — regenerated; each row links to the new dedicated page. - website/docs/reference/optional-skills-catalog.md — same. - website/sidebars.ts — Skills section now has Bundled / Optional subtrees with one nested category per skill folder. - .github/workflows/{docs-site-checks,deploy-site}.yml — run the generator before docusaurus build so CI stays in sync with the source SKILL.md files. Build verified locally with `npx docusaurus build`. Only remaining warnings are pre-existing broken link/anchor issues in unrelated pages.
2026-04-26 01:01:40 +00:00 · 2026-04-23 22:22:11 -07:00 · 2026-04-23 22:22:11 -07:00 · 0f6eabb890
commit 0f6eabb890
parent eb93f88e1d
139 changed files with 43523 additions and 306 deletions
--- a/website/docs/user-guide/skills/optional/health/health-fitness-nutrition.md
+++ b/website/docs/user-guide/skills/optional/health/health-fitness-nutrition.md
@ -0,0 +1,257 @@
+---
+title: "Fitness Nutrition — Gym workout planner and nutrition tracker"
+sidebar_label: "Fitness Nutrition"
+description: "Gym workout planner and nutrition tracker"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Fitness Nutrition
+
+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.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/health/fitness-nutrition` |
+| Path | `optional-skills/health/fitness-nutrition` |
+| Version | `1.0.0` |
+| License | MIT |
+| Tags | `health`, `fitness`, `nutrition`, `gym`, `workout`, `diet`, `exercise` |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# 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` |
--- a/website/docs/user-guide/skills/optional/health/health-neuroskill-bci.md
+++ b/website/docs/user-guide/skills/optional/health/health-neuroskill-bci.md
@ -0,0 +1,469 @@
+---
+title: "Neuroskill Bci"
+sidebar_label: "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, drowsin..."
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Neuroskill Bci
+
+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.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/health/neuroskill-bci` |
+| Path | `optional-skills/health/neuroskill-bci` |
+| Version | `1.0.0` |
+| Author | Hermes Agent + Nous Research |
+| License | MIT |
+| Tags | `BCI`, `neurofeedback`, `health`, `focus`, `EEG`, `cognitive-state`, `biometrics`, `neuroskill` |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# 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 &lt; 0.40** → suggest a break or protocol
+- **Drowsiness > 0.60** → fatigue warning, micro-sleep risk
+- **Relaxation &lt; 0.30** → stress intervention needed
+- **Cognitive Load > 0.70 sustained** → mind dump or break
+- **TBR > 1.5** → theta-dominant, reduced executive control
+- **FAA &lt; 0** → withdrawal/negative affect — consider FAA rebalancing
+- **SNR &lt; 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 &lt;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)
+- **&lt; 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 &lt; 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 &lt; 0.40, TBR > 1.5** → Theta-Beta Neurofeedback Anchor or Box Breathing
+- **Relaxation &lt; 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 &lt; 0 (negative)** → FAA Rebalancing
+- **Flow State (focus > 0.75, engagement > 0.70)** → Do NOT interrupt
+- **High stillness + headache_index** → Neck Release Sequence
+- **Low RMSSD (&lt; 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 &lt; 0.7 | Loose electrodes | Adjust fit, clean electrode contacts |
+| SNR &lt; 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/)