@khalido/home 0.0.0-stage → 0.1.0

package/src/connectors/enphase/client.ts

@@ -0,0 +1,244 @@
+import { z } from "zod";
+import { ConnectorError, fetchTimeout, getJson } from "../../connector.ts";
+import {
+  Login,
+  Meters,
+  Production,
+  Readings,
+  type Measurement,
+} from "./schemas.ts";
+
+/** A failed Enphase call. `status` 401 means the token is wrong or expired. */
+export class EnphaseError extends ConnectorError {}
+
+/** Solar right now and today. Watts and watt-hours as the gateway reports them, negatives included. */
+export type EnphaseState = {
+  productionW?: number;
+  productionWhToday?: number; // undefined when the gateway's daily counter is missing or broken (see anomaly)
+  productionWhLifetime?: number;
+  consumptionW?: number; // needs a consumption meter
+  consumptionWhToday?: number;
+  consumptionWhLifetime?: number;
+  netW?: number; // positive imports from the grid, negative exports
+  source: "meter" | "inverters"; // where production came from
+  readingTime?: string; // the gateway's own reading time
+  anomaly?: string; // something the gateway reported that cannot be right, kept visible rather than corrected
+};
+
+/** A daily counter equal to the lifetime one is the software 8 bug seen on KO's gateway (D8.3.5528): not today's energy. */
+const today = (m: Measurement | undefined) =>
+  m?.whToday !== undefined && m.whToday !== m.whLifetime
+    ? m.whToday
+    : undefined;
+
+const find = (list: Measurement[], type: string, measurementType?: string) =>
+  list.find(
+    (m) =>
+      m.type === type &&
+      (measurementType === undefined || m.measurementType === measurementType),
+  );
+const live = (m: Measurement | undefined) =>
+  m && (m.activeCount ?? 0) > 0 ? m : undefined;
+
+/**
+ * Map `/production.json` and `/ivp/meters` to a state. A meter counts only when `/ivp/meters` says
+ * "enabled" and its reading has `activeCount > 0` (KO's v1 code, pyenphase); else production falls back to the inverters.
+ */
+export function toState(production: unknown, meters: unknown): EnphaseState {
+  const p = Production.parse(production);
+  const enabled = new Set(
+    Meters.parse(meters)
+      .filter((m) => m.state === "enabled")
+      .map((m) => m.measurementType),
+  );
+  const prodMeter = enabled.has("production")
+    ? live(find(p.production, "eim", "production"))
+    : undefined;
+  const inverters = find(p.production, "inverters");
+  const hasConsumption =
+    enabled.has("total-consumption") || enabled.has("net-consumption");
+  const total = hasConsumption
+    ? live(find(p.consumption, "eim", "total-consumption"))
+    : undefined;
+  const net = hasConsumption
+    ? live(find(p.consumption, "eim", "net-consumption"))
+    : undefined;
+  const at = (prodMeter ?? inverters)?.readingTime;
+  const broken = [prodMeter, total].some(
+    (m) => m?.whToday !== undefined && m.whToday === m.whLifetime,
+  );
+  return {
+    productionW: (prodMeter ?? inverters)?.wNow,
+    productionWhToday: today(prodMeter),
+    productionWhLifetime: (prodMeter ?? inverters)?.whLifetime,
+    consumptionW: total?.wNow,
+    consumptionWhToday: today(total),
+    consumptionWhLifetime: total?.whLifetime,
+    ...(broken
+      ? {
+          anomaly:
+            "the gateway's whToday equals its lifetime total; today is counted from the lifetime counter instead",
+        }
+      : {}),
+    netW: net?.wNow,
+    source: prodMeter ? "meter" : "inverters",
+    readingTime: at ? new Date(at * 1000).toISOString() : undefined,
+  };
+}
+
+/**
+ * Map `/ivp/meters` and `/ivp/meters/readings` to a state: ~100 ms on KO's gateway against 1–10 s for
+ * `/production.json` (measured, Bun 1.4.2). Consumption is production plus net import on a net-consumption meter,
+ * or read directly from a total-consumption meter (pyenphase's meter types). No daily totals here: callers count today.
+ */
+export function fromReadings(meters: unknown, readings: unknown): EnphaseState {
+  const enabled = Meters.parse(meters).filter((m) => m.state === "enabled");
+  const byEid = new Map(Readings.parse(readings).map((r) => [r.eid, r]));
+  const reading = (type: string) =>
+    byEid.get(enabled.find((m) => m.measurementType === type)?.eid ?? -1);
+  const prod = reading("production");
+  const net = reading("net-consumption");
+  const total = reading("total-consumption");
+  const pW = prod?.activePower;
+  const consumptionW =
+    total?.activePower ??
+    (net?.activePower !== undefined && pW !== undefined
+      ? pW + net.activePower
+      : undefined);
+  const pLife = prod?.actEnergyDlvd;
+  const consumptionWhLifetime =
+    total?.actEnergyDlvd ??
+    (pLife !== undefined &&
+    net?.actEnergyDlvd !== undefined &&
+    net.actEnergyRcvd !== undefined
+      ? pLife + net.actEnergyDlvd - net.actEnergyRcvd
+      : undefined);
+  const at = prod?.timestamp;
+  return {
+    productionW: pW,
+    productionWhLifetime: pLife,
+    consumptionW,
+    consumptionWhLifetime,
+    netW:
+      net?.activePower ??
+      (consumptionW !== undefined && pW !== undefined
+        ? consumptionW - pW
+        : undefined),
+    source: "meter",
+    readingTime: at ? new Date(at * 1000).toISOString() : undefined,
+  };
+}
+
+/** What a gateway client needs: its LAN address, an owner token, and a `fetch` that accepts its certificate. */
+export type EnphaseOptions = {
+  host: string;
+  token: string;
+  fetch: typeof fetch;
+};
+
+/** The gateway's address as a bare host: a scheme prefix and a trailing slash, as people paste it, are dropped. */
+export const gatewayHost = (host: string) =>
+  host
+    .trim()
+    .replace(/^https?:\/\//i, "")
+    .replace(/\/+$/, "");
+
+/** A read-only client for the IQ Gateway's local API (software 7 and later). */
+export function enphaseClient(options: EnphaseOptions) {
+  const headers = {
+    authorization: `Bearer ${options.token}`,
+    accept: "application/json",
+  };
+  // `host` is read at each call, so a getter follows a move.
+  const get = (path: string, signal?: AbortSignal) =>
+    getJson(options.fetch, `https://${gatewayHost(options.host)}${path}`, {
+      init: { headers },
+      signal,
+      error: EnphaseError,
+    });
+  return {
+    get,
+    /** Production, consumption and net now: the fast meter readings when a production meter is on, else `/production.json`. */
+    async read(signal?: AbortSignal): Promise<EnphaseState> {
+      const meters = await get("/ivp/meters", signal);
+      const metered = Meters.parse(meters).some(
+        (m) => m.measurementType === "production" && m.state === "enabled",
+      );
+      return metered
+        ? fromReadings(meters, await get("/ivp/meters/readings", signal))
+        : toState(await get("/production.json?details=1", signal), meters);
+    },
+  };
+}
+
+/** When a JWT expires, from its `exp` claim. Throws on anything that is not a JWT. */
+export function tokenExpiry(token: string): Date {
+  const payload = token.split(".")[1];
+  if (!payload) throw new EnphaseError("not a JWT");
+  const json = JSON.parse(atob(payload.replace(/-/g, "+").replace(/_/g, "/")));
+  const exp = z.object({ exp: z.number() }).parse(json).exp;
+  return new Date(exp * 1000);
+}
+
+/** Whole days until `expiresAt`, negative once expired. */
+export const daysLeft = (expiresAt: Date, now: Date) =>
+  Math.floor((expiresAt.getTime() - now.getTime()) / 86_400_000);
+
+/**
+ * Mint an owner token as Enphase's TEB-00060 shows: log in for a session id, then ask Entrez for the gateway's token.
+ * Two calls to Enphase's cloud; nothing is stored here.
+ */
+export async function mintToken(options: {
+  username: string;
+  password: string;
+  serial: string;
+  fetch: typeof fetch;
+}) {
+  const form = new URLSearchParams({
+    "user[email]": options.username,
+    "user[password]": options.password,
+  });
+  const login = await fetchTimeout(
+    options.fetch,
+    "https://enlighten.enphaseenergy.com/login/login.json",
+    { method: "POST", body: form },
+  );
+  const session = Login.safeParse(await login.json().catch(() => undefined));
+  if (!login.ok || !session.success)
+    throw new EnphaseError(`Enphase login failed (HTTP ${login.status})`, {
+      status: login.status,
+    });
+  const res = await fetchTimeout(
+    options.fetch,
+    "https://entrez.enphaseenergy.com/tokens",
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        session_id: session.data.session_id,
+        serial_num: options.serial,
+        username: options.username,
+      }),
+    },
+  );
+  const token = (await res.text()).trim();
+  if (!res.ok)
+    throw new EnphaseError(`Entrez refused the token (HTTP ${res.status})`, {
+      status: res.status,
+    });
+  return { token, expiresAt: tokenExpiry(token) };
+}
+
+/**
+ * A `fetch` for the gateway that skips certificate verification, for this gateway's requests only (Bun's `tls` option).
+ * The gateway's chain ends at Enphase's unpublished `root-a.PKI.CA`, and Bun 1.4.2 neither trusts a partial chain nor
+ * runs `checkServerIdentity` with verification off, so it cannot pin (measured). Reserve the gateway's IP. Node: see README.
+ */
+export function bunGatewayFetch(): typeof fetch {
+  const f = (input: RequestInfo | URL, init?: RequestInit) =>
+    fetch(input, {
+      ...init,
+      tls: { rejectUnauthorized: false },
+    } as RequestInit);
+  return f as typeof fetch;
+}

package/src/connectors/enphase/index.ts

@@ -0,0 +1,241 @@
+import { type Clock, localDay, realClock } from "../../clock.ts";
+import { z } from "zod";
+import { filePath, type Integration } from "../../home.ts";
+import { type Finder, lostDetail, relocator } from "../../discover.ts";
+import { kw, type Manifest } from "../../manifest.ts";
+import { poller } from "../../poll.ts";
+import {
+  daysLeft,
+  enphaseClient,
+  EnphaseError,
+  type EnphaseState,
+  gatewayHost,
+  tokenExpiry,
+} from "./client.ts";
+
+export {
+  bunGatewayFetch,
+  EnphaseError,
+  type EnphaseOptions,
+  type EnphaseState,
+  enphaseClient,
+  mintToken,
+  tokenExpiry,
+} from "./client.ts";
+
+/** Poll every 60 s, as Home Assistant's enphase_envoy does. */
+export const POLL_MS = 60_000;
+/** Warn when the token has fewer days left than this (Home Assistant's threshold). */
+const TOKEN_WARN_DAYS = 30;
+
+/** An IQ Gateway in a home config: its last known address, its serial (its identity), and the owner token's file. */
+export const configSchema = z.looseObject({
+  connector: z.literal("enphase"),
+  host: z.string().describe("the gateway's last known address"),
+  serial: z
+    .string()
+    .optional()
+    .describe(
+      "the gateway's serial, as mDNS `serialnum` (and /info) report it: its identity",
+    ),
+  token: filePath.describe(
+    "the owner token file: JSON with a `token` field (what `home enphase login` writes), or the bare token",
+  ),
+  marker: z
+    .string()
+    .startsWith("marker-")
+    .optional()
+    .describe(
+      "the plan's marker where the solar array is drawn, on the roof outside any room",
+    ),
+  capacityW: z
+    .number()
+    .positive()
+    .optional()
+    .describe(
+      "the array's rated size in watts, from the installer's paperwork; never guessed from the gateway",
+    ),
+});
+
+/** Enphase settings: last known address, owner token, and optionally its serial and an mDNS discovery to find it again if it moves. `fetch` must accept the gateway's certificate: `bunGatewayFetch()` in Bun (see README). */
+export type EnphaseConfig = {
+  host: string;
+  token: string;
+  serial?: string;
+  find?: Finder;
+  fetch: typeof fetch;
+  clock?: Clock;
+  timeZone?: string;
+  seen?: (host: string) => void;
+  hostCached?: boolean;
+}; // seen: after each good read, for an address cache; hostCached: `host` came from it // timeZone: where "today" starts (IANA), the runtime's by default
+
+/** What the snapshot holds: the latest reading, when it was taken, and the token's days left. */
+export type EnphaseSnapshot = EnphaseState & {
+  asOf: string;
+  tokenDaysLeft: number;
+  todaySince?: string; // set when "today" is counted locally from the lifetime counter: it starts here, not at midnight
+  productionWPeakToday?: number; // the highest productionW this integration has read today, one read a minute, since `peakSince`
+  peakSince?: string; // midnight's first read, or when the integration started
+};
+
+/** The IQ Gateway as a home integration: one read now, then every 60 s. */
+export function enphase(
+  config: EnphaseConfig,
+): Integration<EnphaseSnapshot, "enphase"> {
+  const clock = config.clock ?? realClock;
+  const where = relocator({
+    host: gatewayHost(config.host),
+    id: config.serial,
+    find: config.find,
+    clock,
+    cached: config.hostCached,
+  });
+  const client = enphaseClient({
+    ...config,
+    get host() {
+      return where.host();
+    },
+  });
+  const poll = poller(clock);
+  return {
+    name: "enphase",
+    refresh: () => (where.reset(), poll.nudge()),
+    async run(signal, update) {
+      const expiresAt = tokenExpiry(config.token); // a bad token fails this integration only
+      let last: EnphaseSnapshot | undefined;
+      let day:
+        | {
+            date: string;
+            since: string;
+            production?: number;
+            consumption?: number;
+            peakW?: number;
+          }
+        | undefined;
+      let moved: string | undefined; // kept in `detail` so a consumer can persist the new address
+      while (!signal.aborted) {
+        const now = new Date(clock.now());
+        const date = localDay(now.getTime(), config.timeZone); // the home's day, not the runtime's: a bot on a UTC box still resets at local midnight
+        const tokenDaysLeft = daysLeft(expiresAt, now);
+        // The one owner of the login ask: in `detail` whether the read works or not, so it shows while the gateway is unreachable too.
+        const warn =
+          tokenDaysLeft < 0
+            ? "token expired; run `home enphase login`"
+            : tokenDaysLeft < TOKEN_WARN_DAYS
+              ? `token expires in ${tokenDaysLeft} days; run \`home enphase login\``
+              : undefined;
+        try {
+          const s = await client.read(signal);
+          if (day?.date !== date)
+            day = {
+              date,
+              since: now.toISOString(),
+              production: s.productionWhLifetime,
+              consumption: s.consumptionWhLifetime,
+            };
+          if (s.productionW !== undefined)
+            day.peakW = Math.max(day.peakW ?? s.productionW, s.productionW);
+          const since = (lifetime?: number, start?: number) =>
+            lifetime !== undefined && start !== undefined
+              ? lifetime - start
+              : undefined;
+          last = {
+            ...s,
+            productionWhToday:
+              s.productionWhToday ??
+              since(s.productionWhLifetime, day.production),
+            consumptionWhToday:
+              s.consumptionWhToday ??
+              since(s.consumptionWhLifetime, day.consumption),
+            todaySince:
+              s.productionWhToday === undefined ? day.since : undefined,
+            productionWPeakToday: day.peakW,
+            peakSince: day.since,
+            asOf: now.toISOString(),
+            tokenDaysLeft,
+          };
+          where.ok();
+          config.seen?.(where.host());
+          update({
+            status: "connected",
+            detail: [moved, warn].filter(Boolean).join("; ") || undefined,
+            anomaly: s.anomaly,
+            state: last,
+          });
+        } catch (error) {
+          if (signal.aborted) return; // stopped mid-read: not a failure
+          if (error instanceof EnphaseError && error.status === 401)
+            return update({
+              status: "unavailable",
+              detail:
+                "the gateway rejected the token; run `home enphase login`",
+              state: last,
+            });
+          const r = await where.failed(signal);
+          if (r.moved) {
+            moved = r.moved;
+            continue; // read at the new address now; that read reports, with the move in `detail`
+          }
+          update({
+            status: "disconnected",
+            detail: [lostDetail(r, error), warn].filter(Boolean).join("; "),
+            state: last,
+          });
+        }
+        await poll.wait(POLL_MS, signal);
+      }
+    },
+  };
+}
+
+/** "solar 2.1 kW, using 0.6 kW · token 300 days left". The login ask near the end is the integration's, in `detail`. */
+export function enphaseText(s: EnphaseSnapshot): string {
+  const solar =
+    s.productionW === undefined
+      ? ""
+      : [
+          `solar ${kw(s.productionW)}`,
+          s.consumptionW === undefined ? "" : `using ${kw(s.consumptionW)}`,
+        ]
+          .filter(Boolean)
+          .join(", ");
+  const token =
+    s.tokenDaysLeft === undefined ? "" : `token ${s.tokenDaysLeft} days left`;
+  return [solar, token].filter(Boolean).join(" · ");
+}
+
+export const manifest: Manifest<EnphaseSnapshot> = {
+  name: "enphase",
+  title: "Enphase IQ Gateway",
+  iotClass: "local_polling",
+  pollSeconds: POLL_MS / 1000,
+  access: "local HTTPS, owner token from `home enphase login`",
+  env: [
+    {
+      name: "IQ_GATEWAY_HOST",
+      example: "envoy.local",
+      what: "the IQ Gateway on the LAN (a scheme is tolerated)",
+    },
+    {
+      name: "IQ_GATEWAY_SERIAL_NUMBER",
+      example: "000000000000",
+      optional: true,
+      what: "for `home enphase login`; from the Enphase app: System > Devices > Gateway",
+    },
+    {
+      name: "ENPHASE_USERNAME",
+      example: "you@example.com",
+      optional: true,
+      what: "for `home enphase login`, once a year: the Enphase account",
+    },
+    {
+      name: "ENPHASE_PASSWORD",
+      example: "xxxxxxxx",
+      optional: true,
+      what: "for `home enphase login`; never stored, only sent to Enphase's login service",
+    },
+  ],
+  files: ["token"],
+  lines: ({ state }) => (state ? [enphaseText(state)] : []),
+};

package/src/connectors/enphase/schemas.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+
+// Shapes from Enphase's TEB-00060 and pyenphase's recorded gateway replies (MIT, software 7 and 8).
+// Loose objects, optional fields: a firmware change degrades a reading, it does not throw.
+
+/** One measurement in `/production.json`: an `inverters` total or an `eim` meter reading. */
+export const Measurement = z.looseObject({
+  type: z.string(), // "inverters" | "eim" | "acb" (battery)
+  measurementType: z.string().optional(), // eim: "production" | "total-consumption" | "net-consumption"
+  activeCount: z.number().optional(), // 0 means the meter is not really measuring
+  wNow: z.number().optional(),
+  whToday: z.number().optional(),
+  whLifetime: z.number().optional(),
+  readingTime: z.number().optional(), // unix seconds
+});
+export type Measurement = z.infer<typeof Measurement>;
+
+/** `GET /production.json?details=1`. */
+export const Production = z.looseObject({
+  production: z.array(Measurement).default([]),
+  consumption: z.array(Measurement).default([]),
+});
+
+/** `GET /ivp/meters`: which current transformers exist and whether they are switched on. */
+export const Meters = z.array(
+  z.looseObject({
+    eid: z.number().optional(),
+    measurementType: z.string(),
+    state: z.string(),
+  }),
+);
+
+/** `GET /ivp/meters/readings`: one reading per meter, joined to `/ivp/meters` by `eid`. */
+export const Readings = z.array(
+  z.looseObject({
+    eid: z.number(),
+    timestamp: z.number().optional(), // unix seconds
+    activePower: z.number().optional(), // W: production, or grid import (negative = export) on a net meter
+    actEnergyDlvd: z.number().optional(), // Wh lifetime: produced, or imported on a net meter
+    actEnergyRcvd: z.number().optional(), // Wh lifetime: exported on a net meter
+  }),
+);
+
+/** The JSON from Enphase's login: only the session id is used. */
+export const Login = z.looseObject({ session_id: z.string() });

package/src/connectors/hue/README.md

@@ -0,0 +1,50 @@
+# Hue
+
+Philips Hue over the bridge's local CLIP v2 API: HTTPS on the LAN, one key, one event stream. Square (v2) bridges only. `iot_class`: **local_push**.
+
+## Official docs
+
+Both pages need a free Hue developer login.
+
+- [Getting started](https://developers.meethue.com/develop/hue-api-v2/getting-started/): pairing (`POST /api` with `devicetype` and `generateclientkey`), the `hue-application-key` header, the resource URLs.
+- [Core concepts](https://developers.meethue.com/develop/hue-api-v2/core-concepts/): the resource model (devices own services; rooms and zones group them; `grouped_light`, `bridge_home`), the event stream, and the rate guidance.
+- [Using HTTPS](https://developers.meethue.com/develop/application-design-guidance/using-https/): the bridge certificate and Signify's root CA.
+
+The schemas here were checked against [openhue-api](https://github.com/openhue/openhue-api) (Apache-2.0), an OpenAPI spec of CLIP v2, not against Signify's gated pages. Treat every field as unconfirmed from the primary source; all are optional, so a change degrades rather than throws.
+
+## Pinning
+
+The bridge serves only its leaf certificate, `CN=<bridge id>`, signed by Signify's `root-bridge` CA (valid to 2038-01-19). Trust that CA and nothing else, and check the CN equals your bridge id. Never turn verification off: the key goes out on every request.
+
+- **Bun**: `bunPinnedFetch(bridgeId, ca)`, which `hue()` uses by default. Measured on Bun 1.4.2: 124 ms cold, 16 ms kept alive; a wrong bridge id is rejected.
+- **Node**: `nodePinnedFetch(bridgeId, ca)` from `@khalido/home/node`, undici's `fetch` with an `Agent` holding `ca` and the same CN check. Checked on Node 24.20 and 26.11 against a local TLS server (2026-10-28), not yet a real bridge.
+
+The CA's SHA-256 is `F0:BD:8E:65:09:E8:2F:77:4D:63:BC:00:9D:53:88:C9:69:FE:3D:CF:7D:6D:54:1D:63:51:B7:2B:89:8D:8A:CF`. It comes from a public mirror and passes `openssl verify` against a live BSB002; confirming it against the copy on the developer portal is still to do. It is not in the package yet: pass `ca` yourself (the CLI reads `HUE_CA_FILE`). The plan is a `HUE_BRIDGE_ROOT_CA` export here so pinning is one import.
+
+## Pairing
+
+`pair({ host, fetch, deviceType })` makes one `POST /api`. Until someone presses the bridge's link button it throws `HueError` with `code: "link_button"` (bridge error 101). It never retries in a loop; the caller decides how to prompt. Pairing happens once: the key it returns keeps working, and the library never stores it.
+
+## Events
+
+`GET /eventstream/clip/v2` with `Accept: text/event-stream`, read through `fetch` (the `EventSource` constructor takes no headers). Each message has `id: <unix seconds>:0` and `data:` holding an array of batches, each `add`, `update`, `delete` or `error`. Updates carry only changed fields, so `reduce` merges them. The bridge keeps a short buffer and does not say when you fell out of it, so after every reconnect `hue()` reads everything again. Reconnects back off 1 s, 5 s, 15 s, then every 60 s. A watchdog reconnects a connection that has sent no bytes, events or comment lines, for 90 s (`IDLE_MS`, aiohue's figure), so a silent half-close does not look connected forever. The bridge sends nothing on its own (aiohue source), so a quiet 90 s costs one silent reconnect: at once, with no `disconnected` and no step up the backoff, then the usual full read (one request; 16 ms kept alive, Bun 1.4.2, as measured under Pinning). Only a reconnect that fails is reported. So a bridge that accepts the stream and then never sends anything reconnects every 90 s, silently, for as long as that lasts. The alternative is aiohue's: it provokes traffic by writing a geofence client to the bridge every 60 s. That is a write to the bridge KO has not asked for, so it is not done; it is KO's call to switch. After three failed reconnects in a row, `hue({ find })` looks for the bridge by `bridgeId` (mDNS, two passes) and follows it to a new address, saying "moved from a to b" in `detail`, as Daikin and Enphase do; `loadHome` passes `finders.hue`.
+
+Unconfirmed: whether the bridge resumes from `Last-Event-ID`; how many streams one bridge allows.
+
+## Rates
+
+Two write lanes per client (`src/lane.ts`). `grouped_light` and `scene` writes go out 1 s apart, `light` writes 100 ms apart, each lane in order. A write to a resource whose last write is still waiting merges into it (`mergeBody`, the newer field winning), so a burst cannot build a backlog; the merged write keeps the first one's place in the lane. Unverified: which the bridge applies when a merge carries both `color_temperature` and `color`. That is Signify's guidance as secondary sources quote it (about 10 commands a second to lights, 1 a second to groups), unconfirmed from the gated page. Prefer one `grouped_light` or scene write over many light writes: the bridge sends it to every light at once.
+
+## Sources
+
+What this folder learned from, and on what terms. No code was copied.
+
+| Source                                                                                                           | Licence                      | Used for                             |
+| ---------------------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------ |
+| [Signify's Hue API docs](https://developers.meethue.com/develop/hue-api-v2/)                                     | Developer terms, login-gated | the API itself                       |
+| [openhue/openhue-api](https://github.com/openhue/openhue-api)                                                    | Apache-2.0                   | resource and event-stream shapes     |
+| [Home Assistant `hue` integration](https://github.com/home-assistant/core/tree/dev/homeassistant/components/hue) | Apache-2.0                   | how HA wires aiohue into entities    |
+| [home-assistant-libs/aiohue](https://github.com/home-assistant-libs/aiohue)                                      | Apache-2.0                   | reconnect behaviour                  |
+| [jash90/lumen-desktop](https://github.com/jash90/lumen-desktop)                                                  | MIT                          | the public copy of Signify's root CA |
+| [jdmg94/Hue-Sync](https://github.com/jdmg94/Hue-Sync)                                                            | Apache-2.0                   | resource types, cross-checked        |
+| [vchlum/smart-home](https://github.com/vchlum/smart-home)                                                        | MIT                          | a compact CLIP v2 event loop         |