---
name: nexus-hvac-report
description: >
  Build an HVAC performance & efficiency report for the selected customer's NexRev Nexus fleet —
  worst-performing RTUs, efficiency scores, runtime & cycling, energy cost, schedule-savings
  opportunities, and predictive-maintenance alerts — as a branded HTML + PDF. For organization owners: prompts you to pick one of your customers from the Nexus customer list, then scopes the whole report to that customer.
  Use whenever someone wants an HVAC scorecard, RTU performance review, "which units are
  performing worst", cooling/heating efficiency, HVAC energy cost, short-cycling or runtime
  problems, or HVAC predictive-maintenance flags. Trigger on "HVAC report", "RTU scorecard",
  "worst performing units", "HVAC efficiency", "HVAC cost", "which AC units have problems",
  "HVAC health", or "cooling performance". Supports once-off and scheduled delivery.
  Part of the Nexus Operate (Organization) plugin (organization edition).
---

# Nexus HVAC Report

Produce an executive HVAC report for the selected customer — ranked worst performers, efficiency,
runtime health, energy cost, and maintenance risk — as a branded **HTML dashboard + PDF**.

## Before you start — read the shared references (`${CLAUDE_PLUGIN_ROOT}`)
- `references/scoping.md` — **required.** How this edition resolves scope.
- `references/footprint-discovery.md` — resolve scope + pick a site/area/device.
- `references/branding.md` — the HTML/PDF brand pipeline + report-data schema.
- `references/scheduling-recurring-reports.md` — only if recurring.

Data source: the **`nexrev-nexus` MCP**. If unavailable, say so and stop.

## Workflow

### 1. Resolve scope & target
Scope: first resolve scope — call `list_customers`, have the user pick one customer by name, and pass that `customerId` to every subsequent tool (see `scoping.md`). Then use `footprint-discovery.md` to confirm the customer and let the
user choose **all sites**, one **site** (by name), or one **device/RTU** (by name). Default
time window: **`ago: "7d"`** (offer 24h / 30d).

### 2. Pull HVAC analytics (only what the chosen scope needs)
Pass `siteName` / `deviceName` for the chosen target (plus the scope `customerId` for the org
edition). Core set for a fleet report:
- **Ranked performance** — `hvac_efficiency_analysis` (`analysisType: "efficiency"`): overall
  efficiency score per unit → rank ascending to find worst performers.
- **Energy & cost** — `hvac_efficiency_analysis` (`energy_consumption`, then `cost` with
  `energyCostPerKwh` if the user has a rate; default 0.12).
- **Runtime health** — `hvac_runtime_analysis` (`runtime`, and `cycling` to flag short-cycling).
- **Savings opportunities** — `hvac_monitoring` (`schedule_optimization`; optionally `degree_day`).
- **Maintenance risk** — `hvac_predictive_analysis` (`maintenance_alerts`, optionally
  `failure_prediction` / `health_score`).
- **Fleet rollup (multi-site only)** — `hvac_portfolio_analysis` (`executive_summary`). This
  needs customer/org scope (a site-level key can't call it — degrade to per-site).
- Optional deep dives when asked: `hvac_temperature_analysis` (`setpoint_deviation`,
  `differential`), `hvac_equipment_analysis` (`economizer`, `ashrae_compliance`),
  `hvac_environment_analysis` (`humidity`, `co2`).

### 3. Ask the theme (once-off runs only)
Dark or light (bluewhite)? Scheduled runs use the stored theme (default dark).

### 4. Assemble the report data (schema in `branding.md`)
- `title`: `"HVAC Report — <Customer>"` (add `— <Site>` if scoped).
- `meta`: Customer, Scope, Period (the window), Generated.
- `kpis`: Units analyzed, Avg efficiency score, Worst-performer score, Est. energy cost,
  Maintenance alerts, Short-cycling units.
- `sections`:
  - `table` **"Worst-performing units"** — Unit, Site, Efficiency score, Runtime, Flag —
    sorted worst first (top N, e.g. 10).
  - `bars` **"Efficiency by site"** or **"Energy cost by site"** (multi-site).
  - `table` **"Maintenance alerts"** — Unit, Site, Alert, Severity.
  - `text` **"Recommendations"** — schedule-optimization savings, cycling fixes, top actions.
Only include what you retrieved; never invent scores or costs.

### 5. Render (branded HTML + PDF)
```
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/render_html.py --profile <profile.json> --theme <dark|light> --data hvac.json --out hvac.html
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/render_pdf.py --html hvac.html --out hvac.pdf
```
Profile = `${CLAUDE_PLUGIN_ROOT}/assets/brand_profile.default.json` (or the customer's stored profile).

### 6. Deliver, then offer recurrence
Give both files with a one-line summary (e.g. "3 units below 60% efficiency; 2 short-cycling").
Offer a schedule (e.g. weekly) per `scheduling-recurring-reports.md`.

## Guardrails
- One customer at a time. Always pass the chosen `customerId`. Never combine multiple customers into a single report — offer to loop instead. Don't use cross-customer benchmarking modes.
- Pick units/sites by name, not GUID. Rank worst-first so the report leads with what matters.
- Never fabricate scores, costs, or alerts — if a tool returns nothing (sparse data), say so.