# Image Attachments Implementation

## Status: ✅ COMPLETE

Image attachments are now fully implemented in the proactive coaching system! Users receive coaching messages with Canvas dashboard visualizations automatically.

## How It Works

### 1. JSON Output Format

The proactive coaching script now supports `--format json`:

```bash
npx tsx scripts/proactive_coaching.ts --weekly-checkin --format json
```

**Output:**
```json
{
  "success": true,
  "messageCount": 1,
  "messages": [
    {
      "subject": "📊 Weekly Progress: Morning meditation",
      "body": "This week: 6/7 days (86%)...",
      "type": "weekly",
      "priority": "medium",
      "habitId": "h_abc123",
      "attachments": [
        "/tmp/trends-h_abc123-1234567890.png",
        "/tmp/heatmap-h_abc123-1234567890.png"
      ]
    }
  ]
}
```

### 2. Agent-Based Image Delivery

Cron jobs use detailed prompts that instruct the agent to:

```
Execute the HabitFlow weekly check-in and deliver with visualizations.

IMPORTANT: This is an automated coaching message. Run this command and display the results with images:

cd ~/clawd/skills/habit-flow && npx tsx scripts/proactive_coaching.ts --weekly-checkin --format json

Parse the JSON output. For each message:
1. Display the subject and body text
2. If attachments exist, use the Read tool to display each image file
3. Format as a complete coaching message with visualizations

Send the complete message to the user.
```

### 3. Image Generation

Canvas dashboard charts are generated by the coaching engine:

| Message Type | Images Generated |
|--------------|-----------------|
| Milestone | Streak chart (bar graph of progress) |
| Risk Warning | Heatmap (completion patterns) |
| Weekly Check-in | Trends chart + Heatmap |
| Pattern Insight | Heatmap or Trends (context-dependent) |

**Example files:**
- `/tmp/streak-h_abc123-1769699500.png` - 28KB PNG
- `/tmp/trends-h_abc123-1769699500.png` - 28KB PNG
- `/tmp/heatmap-h_abc123-1769699500.png` - 12KB PNG

### 4. Complete Flow

```
Cron Trigger (8am)
      ↓
Isolated Agent Session Starts
      ↓
Agent executes: cd ~/clawd/skills/habit-flow && npx tsx scripts/proactive_coaching.ts --check-milestones --check-risks --format json
      ↓
Script generates:
  - Analyzes habits
  - Detects milestones/risks
  - Creates Canvas PNG charts
  - Outputs JSON with message + attachment paths
      ↓
Agent parses JSON output
      ↓
Agent uses Read tool to display each image file
      ↓
Agent formats complete message:
  📊 Weekly Progress: Morning meditation

  This week: 6/7 days (86%)...

  [Trends Chart Image]
  [Heatmap Image]
      ↓
Clawdbot's --deliver flag sends to user's last active channel
      ↓
User receives message with visualizations on WhatsApp/Telegram/Discord
```

## Technical Implementation

### Changes Made

**1. Updated `scripts/proactive_coaching.ts`:**
- Added `--format json` option
- JSON output includes message content and attachment paths
- Structured data for agent parsing

**2. Updated `scripts/sync_reminders.ts`:**
- Cron messages use `--format json`
- Detailed agent instructions for image handling
- Explicit steps: parse JSON → read images → format → deliver

**3. Created `examples/test-image-attachments.sh`:**
- Validates JSON output format
- Verifies PNG files are created
- Confirms attachment paths are correct
- Tests image file integrity

### Key Design Decisions

**Why JSON format?**
- Structured data is easier for agents to parse
- Clear separation of message content vs attachments
- Enables programmatic processing

**Why agent-based delivery?**
- Agent can use Read tool to display images
- No need for specialized sendAttachment API
- Works within existing clawdbot framework
- Images are embedded directly in agent response

**Why --message instead of --command?**
- Allows agent to use tools (Bash, Read, etc.)
- Agent can process script output intelligently
- Flexible for future enhancements
- Proper isolated session context

## Testing

### Test Script

```bash
bash examples/test-image-attachments.sh
```

**Expected Output:**
```
Testing Image Attachments for Proactive Coaching
=================================================

Using habit ID: h_abc123

1. Testing JSON output format...
-----------------------------------
✅ Valid JSON output
   Messages: 1
   Attachments found:
     ✅ /tmp/trends-h_abc123-123456.png ( 28K)
     ✅ /tmp/heatmap-h_abc123-123456.png ( 12K)

2. Simulating agent reading images...
-----------------------------------
   Reading image: /tmp/trends-h_abc123-123456.png
   ✅ Valid PNG image
   Reading image: /tmp/heatmap-h_abc123-123456.png
   ✅ Valid PNG image

3. Testing complete message format...
-----------------------------------
Subject: 📊 Weekly Progress: Morning meditation

Body:
📊 Weekly Progress Report: Morning meditation

This week: 6/7 days (86%)
Current streak: 9 days
Trend: -14% vs last week

Data-driven observation: Declining trend—intervention may help

See attached visualizations for detailed analysis.

Attachments:
  - /tmp/trends-h_abc123-123456.png
  - /tmp/heatmap-h_abc123-123456.png

=================================================
✅ Image attachment tests complete!
```

### Manual Testing

```bash
# Test JSON output
npx tsx scripts/proactive_coaching.ts --habit-id h_abc123 --weekly-checkin --format json

# Test image generation
npx tsx scripts/proactive_coaching.ts --habit-id h_abc123 --check-milestones --format json

# Verify image files exist and are valid PNGs
file /tmp/trends-h_abc123-*.png
```

## Real-World Usage

### Setup

```bash
# Initialize with image support
npx tsx scripts/init_skill.ts

# Verify cron jobs include image instructions
clawdbot cron list | grep HabitFlow
```

### Example Message (Weekly Check-in)

**What the user receives:**

```
📊 Weekly Progress: Morning meditation

This week: 6/7 days (86%)
Current streak: 9 days
Trend: -14% vs last week

Data-driven observation: Declining trend—intervention may help

See attached visualizations for detailed analysis.

[Trends Chart Image showing 4 weeks of progress]
[Heatmap Image showing 30-day completion pattern]
```

### Example Message (Milestone Celebration)

**What the user receives:**

```
🎉 Milestone Alert: 7-Day Streak

You've maintained meditation for 7 consecutive days—your longest streak yet.

Data shows perfect quality (forgiveness not used). The compound effect is beginning.

📊 Your Progress:
- Current streak: 7 days
- Quality: PERFECT
- New personal record

Next target: 14 days. One week at a time.

[Streak Chart Image showing current vs longest streak bars]
```

## Benefits

✅ **Rich Visual Coaching** - Charts make progress tangible and engaging
✅ **Automatic Delivery** - No manual intervention required
✅ **Persona-Consistent** - Images complement text in user's chosen style
✅ **Data-Driven** - Visualizations reinforce insights with evidence
✅ **Platform-Agnostic** - Works on WhatsApp, Telegram, Discord, etc.
✅ **No External APIs** - All processing happens locally
✅ **Future-Proof** - Agent-based approach allows easy enhancements

## Comparison: Before vs After

### Before (Text Only)
```
📊 Weekly Progress: Morning meditation

This week: 6/7 days (86%)
Current streak: 9 days
Trend: -14% vs last week

See attached visualizations for detailed analysis.
📎 Attachments: /tmp/trends-h_abc123-123456.png
```
❌ User can't see visualizations
❌ Less engaging
❌ Limited impact

### After (With Images)
```
📊 Weekly Progress: Morning meditation

This week: 6/7 days (86%)
Current streak: 9 days
Trend: -14% vs last week

[Trends Chart showing clear declining pattern]
[Heatmap showing missed days highlighted in red]
```
✅ User sees their progress visually
✅ More engaging and motivating
✅ Higher coaching impact

## Troubleshooting

### Images not appearing in messages

**Check 1: Verify JSON output includes attachments**
```bash
npx tsx scripts/proactive_coaching.ts --habit-id h_abc123 --weekly-checkin --format json | jq '.messages[0].attachments'
```

**Check 2: Verify image files are created**
```bash
ls -lh /tmp/*h_abc123*.png
file /tmp/*h_abc123*.png  # Should say "PNG image data"
```

**Check 3: Verify cron message includes image instructions**
```bash
clawdbot cron list | grep -A 10 "HabitFlow: Weekly Check-in"
# Should include "use the Read tool to display each image file"
```

**Check 4: Re-sync cron jobs**
```bash
npx tsx scripts/sync_reminders.ts sync-coaching
```

### Images are generated but not displayed

This typically means the agent isn't parsing the JSON or reading the images. Ensure:
- Cron job uses `--format json`
- Cron message instructs agent to "use the Read tool"
- clawdbot version supports image display in Read tool

## Future Enhancements

While the current implementation is complete, potential enhancements include:

1. **Custom Image Themes** - Match visualization colors to user preference
2. **Compressed Images** - Optimize PNG file sizes for faster delivery
3. **Multi-Image Layouts** - Side-by-side chart comparisons
4. **Animated Charts** - GIF animations showing progress over time
5. **PDF Reports** - Complete weekly reports as PDF attachments

## Summary

Image attachments are **fully implemented** and **production-ready**. The system:

- ✅ Generates PNG charts automatically
- ✅ Outputs structured JSON with image paths
- ✅ Instructs agents to read and display images
- ✅ Delivers complete coaching messages with visualizations
- ✅ Works across all messaging platforms
- ✅ Tested and validated

Users now receive rich, visual coaching messages that combine personalized insights with data-driven visualizations, significantly enhancing the coaching experience!