pp-hayward-omnilogic

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/devices/hayward-omnilogic/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# Hayward OmniLogic — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `hayward-omnilogic-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install hayward-omnilogic --cli-only
   ```
2. Verify: `hayward-omnilogic-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/devices/hayward-omnilogic/cmd/hayward-omnilogic-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## Pool sensor capabilities — configure once per site

Not every OmniLogic install has every sensor. Common variants:

- No pH or ORP probe (most basic salt-pool installs)
- No salt cell (chlorine-tab or liquid-chlorine pools)
- Water-temp sensor that only reads while the pump is running (a quirk of certain pump/sensor pairings)

When sensors are absent, Hayward's API returns `-1` or null for those fields. **Without telling the CLI which sensors actually exist, `status` will report `"caution"` for a perfectly healthy pool** simply because chemistry comes back as `unknown`. The `chemistry get`, `telemetry get`, and `status` commands include a `setup_hint` field in the JSON output when this is detected.

**Configure once per site:**

```bash
# Example: pool without pH/ORP probes, no salt cell, temp sensor needs pump flow
hayward-omnilogic-pp-cli capabilities set \
  --has-ph false --has-orp false --has-salt false --temp-needs-flow true

# Inspect:
hayward-omnilogic-pp-cli capabilities get --json
```

Stored in the local SQLite store per `MspSystemID`. After configuration: `status` correctly excludes the missing sensors from its verdict, `chemistry get` returns `not_equipped` instead of `unknown` for sensors that don't exist, and `water_temp = -1` while the pump is idle is reported as `"n/a (pump off)"` instead of "sensor offline".

**Agents seeing `setup_hint` in CLI output should surface the suggested `capabilities set` command to the user as a one-time setup step before relying on chemistry/temp verdicts.**
## When to Use This CLI

Pick this CLI when an agent needs to read or control a Hayward OmniLogic pool/spa system over the partner cloud API: pool owners managing one pool, integrators wiring OmniLogic into agentic workflows, and pool-service businesses managing many sites. The CLI replaces ad-hoc Python scripts on top of `omnilogic-api`, the Hayward mobile app for diagnostics and trends, and the per-site click-through pool-service operators do every morning.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Pool readiness at a glance
- **`status`** — One-shot "is the pool ready for guests?" view: chemistry in range, temp at setpoint, no active alarms, pump running, with a traffic-light verdict.

  _Reach for this when an agent or user wants a one-shot pool-state summary instead of correlating three commands._

  ```bash
  hayward-omnilogic-pp-cli status --json
  ```
- **`ready-by`** — Enables the heater and computes when to start it so the pool hits your target temperature by a specified arrival time, using the learned heat rate from telemetry history.

  _Use this instead of "set heater + setpoint and guess" when the user has a specific swim time._

  ```bash
  hayward-omnilogic-pp-cli ready-by 18:00 --temp 84
  ```

### Local state that compounds
- **`chemistry log`** — Weekly/monthly pH, ORP, salt, and temperature history from the local store, exportable as CSV or JSON for HOA / service / insurance records.

  _Use this when an agent needs trend data or a compliance log over a date range._

  ```bash
  hayward-omnilogic-pp-cli chemistry log --since 30d --csv
  ```
- **`chemistry drift`** — Detects pH/ORP/salt drift versus a rolling baseline before Hayward's static thresholds fire; --forecast projects when each metric will leave the safe range.

  _Reach for this when the user wants early warning, not just "alarm is active."_

  ```bash
  hayward-omnilogic-pp-cli chemistry drift --forecast --json
  ```
- **`runtime`** — Pump hours, heater hours, salt-cell hours derived from telemetry deltas — for maintenance planning, warranty, and end-of-season service.

  _Use this when a service-business agent needs maintenance projections or a warranty case-file._

  ```bash
  hayward-omnilogic-pp-cli runtime --since 90d --json
  ```
- **`command-log`** — Every Set* command issued via this CLI is logged with who/when/what/result. --replay <id> re-issues a prior command for quick undo or redo.

  _Use this when an agent or operator needs to know what was changed recently or roll back a misfire._

  ```bash
  hayward-omnilogic-pp-cli command-log --since 7d
  ```

### Diagnostics the cloud can't do
- **`why-not-running`** — Diagnose why a pump, heater, or light isn't running: correlates active alarms, current relay state, scheduled run windows, heater demand, and superchlor lockouts into one explanation.

  _Reach for this when an agent is asked to triage "X isn't running" instead of telling the user to open the app._

  ```bash
  hayward-omnilogic-pp-cli why-not-running 'Main Pump'
  ```
- **`schedule diff`** — Diffs today's MSP-config schedule tree against prior versioned snapshots; catches silent edits made by service techs or by other app users.

  _Use this when a user reports unexpected pool behavior and you need to know what changed._

  ```bash
  hayward-omnilogic-pp-cli schedule diff --since yesterday
  ```

### Multi-site operations
- **`sweep`** — Across every site in the account, surface active alarms, out-of-range chemistry, and offline controllers in a single report — built for pool-service businesses doing route planning.

  _Use this when an agent is asked to prioritize the day's truck rolls across many pools._

  ```bash
  hayward-omnilogic-pp-cli sweep --alarms --chemistry --json
  ```

## Command Reference

**alarms** — Active alarms across the OmniLogic system

- `hayward-omnilogic-pp-cli alarms` — List active alarms for a site or every site.

**chemistry** — Chemistry-only view of telemetry plus historical-store-backed readouts

- `hayward-omnilogic-pp-cli chemistry` — Current chemistry snapshot: pH, ORP, salt, water temp, with safe-range verdict.

**chlorinator** — Salt chlorinator configuration

- `hayward-omnilogic-pp-cli chlorinator` — Set chlorinator config (op mode, timed percent, ORP timeout, etc). Defaults to current MSP values for any flag you...

**config** — Equipment inventory (MSP config tree) per site

- `hayward-omnilogic-pp-cli config` — Fetch the equipment inventory for one site — pumps, heaters, chlorinator, lights, valves, relays, sensors.

**equipment** — Generic on/off + timed-run control for valves, relays, lights, and accessory pumps

- `hayward-omnilogic-pp-cli equipment off` — Turn an equipment item off.
- `hayward-omnilogic-pp-cli equipment on` — Turn an equipment item on. Use --for to run for a bounded duration; otherwise stays on until you turn it off.

**heater** — Heater control (enable/disable + setpoint)

-