Namespaces: `water` | `body` | `analytics`

---

## Data Format 

### CSV Format

| Column | Description |
|--------|-------------|
| logged_at | When user told you (NOW) |
| drank_at | When user actually drank (user can specify past time) |
| date | Derived from drank_at |
| slot | morning/lunch/afternoon/evening/manual |
| ml_drank | Amount in ml |
| goal_at_time | Goal at that moment |
| message_id | Audit trail - link to conversation |

**Key Rules:**
- **drank_at is MANDATORY** - always required
- If user doesn't specify drank_at → assume drank_at = logged_at
- **Cumulative is calculated at query time** (not stored)
- Use drank_at to determine which day counts

Details at  [references/log_format.md](references/log_format.md)

### Audit Trail

Every water log entry captures:
- **message_id**: Links to the conversation message where user requested the log
- **Auto-capture**: CLI automatically gets message_id from session transcript
- **Proof**: Use `water audit <message_id>` to get entry + conversation context

> ⚠️ **Privacy Notice**: The audit feature can read your conversation transcripts, but **only when you explicitly run `water audit <message_id>`**. This is off by default (`audit_auto_capture: false`).
>
>

---

## Rules (MUST FOLLOW)

1. **ALWAYS use CLI** - never calculate manually
2. **LLM interprets first** - "eu tomei 2 copos" → 500ml → water log 500
3. **Threshold from CLI** - run `water threshold`, don't hardcode
4. **GOAL is USER'S CHOICE** - weight × 35 is just a DEFAULT suggestion:
   - At setup: Ask weight → suggest goal → **CONFIRM with user**
   - On weight update: Ask "Want to update your goal to the new suggested amount?"
   - User can set any goal (doctor's orders, preference, etc.)

---

## Config Tree

### ⚠️ IMPORTANT: Data Location
**User data is stored in the AGENT WORKSPACE, NOT in the skill folder!**

| Data | Location |
|------|----------|
| water_log.csv | `<agent-workspace>/memory/data/water_log.csv` |
| water_config.json | `<agent-workspace>/memory/data/water_config.json` |
| body_metrics.csv | `<agent-workspace>/memory/data/body_metrics.csv |

Example path: `/home/oriel/.openclaw/workspace/memory/data/`

**Why?** Keeps user data separate from skill code — makes backups, migrations, and skill updates easier.

---

## Notifications Schedule

| Type | When | Command |
|------|------|---------|
| User Configured | Per user's schedule | water status |
| Default Suggestion | 9am, 12pm, 3pm, 6pm, 9pm | water status |
| Dynamic | Every ~30 min (heartbeat) | water dynamic |
| Weekly | Sunday 8pm | analytics week |
| Monthly | 2nd day 8pm | analytics month |

### Notification Rules (MUST FOLLOW)
- **USER CONFIGURES THEIR SCHEDULE** — Agent should ask user: "What times do you want water reminders?" and respect that
- **NO "no log" skip logic** — Always send notifications when scheduled, don't skip because user hasn't logged water
- **Notifications STIMULATE logging** — That's the point! Don't assume user will log on their own

---

## Quick Reference

| Task | Command |
|------|---------|
| Check progress | `water_coach.py water status` |
| Log water | `water_coach.py water log 500` |
| Need extra? | `water_coach.py water dynamic` |
| Body metrics | `water_coach.py body log --weight=80` |
| Weekly report | `water_coach.py analytics week` |
| Monthly report | `water_coach.py analytics month` |

## Dynamic Scheduling details
→ [references/dynamic.md](references/dynamic.md)

### ⚠️ Bug Fix (Feb 2026)
The `water dynamic` command had a bug where the hourly notification counter wouldn't reset when the hour changed. This is now fixed:
- The script now checks if the current hour differs from `last_extra_hour` and resets the counter accordingly
- This ensures notifications work correctly after hour boundaries (e.g., 4PM)

### ⚠️ Bug Fix (Feb 2026) - Analytics
The `analyticsPM → 5 week` and `analytics month` commands had a bug:
- Was looking for non-existent `cumulative_ml` column in CSV
- Fixed to sum `ml_drank` per day instead

### ✅ How to Build Good Weekly/Monthly Reports

**Use these functions (don't reinvent):**

| Report | Script | Function |
|--------|--------|----------|
| Weekly | `water_coach.py analytics week` | `analytics_week()` in `water_coach.py` |
| Monthly | `water_coach.py analytics month` | `analytics_month()` in `water_coach.py` |

These call `get_week_stats()` and `get_month_stats()` in `water.py`.

**When updating analytics functions, follow these rules:**

**1. Include ALL days, even with 0ml**

This gives users an accurate picture of their habits!



## Tests

# Check proof of a water entry
water audit msg_123
# Returns: entry data + surrounding messages for context

> # Edit water_config.json and set:
> "audit_auto_capture": true
>

# Water
water status                                      # Current progress (calculated from drank_at)
water log 500                                    # Log intake (drank_at = now)
water log 500 --drank-at=2026-02-18T18:00:00Z  # Log with past time
water log 500 --drank-at=2026-02-18T18:00:00Z --message-id=msg_123
water dynamic                                    # Check if extra notification needed
water threshold                                  # Get expected % for current hour
water set_body_weight 80                        # Update weight + logs to body_metrics
water set_body_weight 80 --update-goal          # + update goal
water audit <message_id>                        # Get entry + conversation context

# Body
body log --weight=80 --height=1.75 --body-fat=18
body latest          # Get latest metrics
body history 30     # Get history

# Analytics
analytics week       # Weekly briefing (Sunday 8pm)
analytics month     # Monthly briefing (2nd day 8pm)

water-coach/
├── SKILL.md              ← You are here
├── scripts/
│   ├── water_coach.py   ← Unified CLI
│   └── water.py         ← Core functions
├── data/                 ← DO NOT USE - keep skill code separate from user data
└── references/
    ├── setup.md
    ├── dynamic.md
    └── log_format.md