irrigation-scheduler

SKILL.md

---
name: irrigation-scheduler
description: Schedule and monitor irrigation zones with weather-aware skip rules and water usage tracking. Use when asked to manage irrigation timing, set up zone schedules, configure rain-based skip rules, check water usage, trigger manual watering, or apply seasonal duration presets. Triggers include "irrigation", "sprinkler schedule", "watering zones", "skip when raining", "water usage tracking", "manual run irrigation", or any task involving automated watering management.
---

# irrigation-scheduler

Schedule irrigation zones with weather-aware automatic skips and water usage tracking.

## When to Use

- Setting up irrigation schedules for multiple zones
- Configuring weather-based skip rules (rain forecast, recent rain, freeze protection)
- Triggering manual irrigation runs
- Checking water usage by zone and time period
- Applying seasonal duration presets (Summer 1.5x, Fall 0.75x, etc.)
- Reviewing irrigation history and skip events

## Prerequisites

1. irrigation-scheduler running (Docker or local)
2. At least one zone configured
3. Location coordinates set in Settings (for weather integration)

## Key Concepts

### Zones

Each zone represents one physical irrigation circuit. Zones have:
- Name and description
- Flow rate (GPH) for water usage calculation
- Coverage area (sqft) for reporting
- One or more schedules
- One or more skip rules

### Schedules

A schedule defines when a zone runs: days of week, start time, and duration in minutes. A zone can have multiple schedules (e.g., one for weekdays, one for weekends). Duration multiplier from season presets is applied on top of the base duration.

### Skip Rules

| Rule Type | Description |
|---|---|
| rain_forecast | Skip if rain forecast exceeds N mm in next H hours |
| rain_yesterday | Skip if rain fell yesterday exceeding N mm |
| temperature_below | Skip if temperature is below N degrees (freeze protection) |

Skip rules only apply to scheduled runs. Manual runs always proceed.

### Season Presets

Apply a multiplier to all zone durations at once. Example: Summer preset (1.5x) makes a 30-minute schedule run for 45 minutes. Removing a preset restores base durations.

## API Reference

### Quick Examples

```bash
# List all zones
curl http://localhost:3001/api/zones

# Trigger a manual run (zone_id + duration in minutes)
curl -X POST http://localhost:3001/api/runs/manual \
  -H "Content-Type: application/json" \
  -d '{"zone_id": "uuid-here", "duration_min": 20}'

# Stop a running zone
curl -X PUT http://localhost:3001/api/runs/{run-id}/stop

# Get skip preview for today
curl http://localhost:3001/api/weather/skip-preview

# Check water usage
curl "http://localhost:3001/api/runs?limit=30"
```

## Environment Variables

| Variable | Description | Default |
|---|---|---|
| PORT | HTTP port | 3001 |
| DATA_DIR | SQLite and data directory | ./data |
| AUTH_PASSWORD | Optional login password | (empty) |
| NODE_ENV | development or production | development |
| SESSION_SECRET | Required in production | (required) |
| DEFAULT_LATITUDE | Initial latitude for weather | 0 |
| DEFAULT_LONGITUDE | Initial longitude for weather | 0 |

Boolean env vars use `0` (false) and `1` (true).

## Troubleshooting

### Zone not running at scheduled time

1. Confirm zone is enabled: `GET /api/zones/:id` - check `enabled: 1`
2. Confirm schedule days_of_week includes today (0=Sun)
3. Check if a skip rule triggered: `GET /api/runs?status=skipped`
4. Verify server timezone matches your local timezone in Settings

### Skip rules not triggering

Weather data requires valid latitude/longitude in Settings. Check `GET /api/weather` returns data. If weather fetch fails, the scheduler falls back to run as scheduled (safe default).

### Water usage shows 0

Flow rate must be set on the zone for usage calculation. Update via `PUT /api/zones/:id` with `flow_rate_gph` value.