@khalido/home 0.1.3 → 0.2.1

package/docs/using.md

@@ -13,12 +13,12 @@ Give every device a fixed address in your router (a DHCP reservation; eero, UniF
 ```ts
 import { NODE_TLS, nodePinnedFetch } from "@khalido/home/node";
 loadHome(config, { env: process.env, readFile, tls: NODE_TLS }); // from a home config
-hue({ host, bridgeId, key, ca, fetch: nodePinnedFetch(bridgeId, ca) }); // or one integration
+hue({ host, bridgeId, key, fetch: nodePinnedFetch(bridgeId) }); // or one integration
 ```
 
 Checked on Node 24.20 and 26.11 against a local TLS server (2026-10-28): the right CA and CN pass, another certificate or CN is rejected. Not yet against a real bridge.
 
-Pairing, pinning, the event stream and the rate limits are in [`src/connectors/hue/README.md`](../src/connectors/hue/README.md). On the local network the bridge still needs an application key: without one it answers 403. `home pair` gets one with the link button; no cloud account is involved.
+Pairing from code is `pairWhenPressed` ([hue.md](hue.md#pairing) has the whole flow); pinning, the event stream and the rate limits are in [`src/connectors/hue/README.md`](../src/connectors/hue/README.md). On the local network the bridge still needs an application key: without one it answers 403. `home pair` gets one with the link button; no cloud account is involved.
 
 ## One home
 
@@ -37,6 +37,8 @@ health(home.snapshot(), Date.now()); // per integration: ok, stale or down, with
 
 `createHome` stamps each part with `lastGoodAt` (its last good read) and `downSince` (when it stopped being connected). `health` judges from those: a polling connector is stale after 2½ polls with no good read and down after 3 polls not connected; Hue and Cast are down after 2 minutes not connected. Health takes each connector's interval from its manifest; a home that changes one (the weather's `pollMinutes`) passes it: `health(snapshot, now, { pollSeconds: { weather: 60 * 60 } })`. For a one-shot read (a script, a printed brief), `settle(integrations, { ms })` runs them until each has answered and returns the snapshot.
 
+From a config file, with everything a Bun app on the home's network passes (Cast, discovery, an address cache), the call is at the top of [config.md](config.md).
+
 ## Every device, the same way
 
 `homeDevices(home.snapshot(), config)` lists every device the home has: each Hue light, room and zone, the Daikin, the Enphase gateway, each Cast device and group, each printer and the Soloist speaker. Each answers the same questions in the same words: `connector`, `id`, `name`, `kind` (light, group, speaker, display, tv, ac, printer, solar; `cast` for a Cast model the library doesn't know), `available` (and when it is false, `reason`: `offline`, `auth`, `config` or `crashed`), `asOf` (when the device last reported or was last read; a quiet light can be hours old and current), `state` (one word: on, off, idle, busy, cool, printing), `text` (one line for people), `room` and, for a group, `members`. A field the device hasn't reported is absent. The config is optional: with it a device takes its entry's `room`, and a device with no name of its own (the Daikin, the gateway) its entry's `name`; a device's own name is never replaced. While a connector isn't connected none of its devices is `available`, and each keeps its last values.
@@ -54,9 +56,102 @@ for (const d of homeDevices(home.snapshot(), config)) {
 
 Below that is the connector's snapshot, exactly as the device sent it (`home.part("hue")?.state`). One connector alone: `castHomeDevices(home.part("cast"))`, and likewise `hueHomeDevices`, `daikinHomeDevices`, `enphaseHomeDevices`, `printersHomeDevices`, `spotifyHomeDevices`. The list is for reading; a write goes to the device's connector, with `d.id` where it takes one.
 
+For a map of the home, `byRoom(home.snapshot(), config)` gives `{ rooms, unplaced }`: each room of the config in order (`id`, `name`, `floor`, `devices`), and `noData`, the connectors the config places in that room that have nothing to list yet, so an unread room isn't drawn as an empty one. A connector that is down but has read before still lists its devices, `available: false`.
+
 ## Writes
 
-Writes hang off the integration: `home.integration("daikin")?.client.write(setMode("cool"))`, `home.integration("hue")?.client.recallScene(id)`, `home.integration("cast")?.setVolume(…)`, `home.integration("spotify")?.play(link)`. Each goes through the device's write lane: spaced, and a burst to one light or the AC merges so the last value lands. Spotify's writes resolve with `{ state, confirmed }`, the state once Soloist reported the change, and `duck(fn, { to })` and `interrupt(fn)` turn the music down or pause it around an announcement, returning what happened to it (`music`: `untouched`, `restored`, `kept` or `failed`). `speakerState(part)` says the speaker in one word (offline, waiting, idle, playing, paused) and `spotifyChanges(change.before, change.after)` turns an `onChange` into events (started, resumed, paused, stopped, track, stalled, recovered, offline, waiting, picked), those from the library's own `duck` or `interrupt` marked `own`.
+A write changes someone's house: make one only when a person asked for it. Writes hang off the integration, `home.integration(name)`, and each goes through the device's write lane: spaced, and a burst to one light or the AC merges so the last value lands.
+
+| Connector | Call                                                                                                               | Resolves with                                                                                    |
+| --------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
+| daikin    | `.client.power(on, opts?)`, `.client.mode(mode, targetC?, opts?)`                                                  | `{ state, confirmed }`                                                                           |
+| spotify   | `.play(link?)`, `.pause()`, `.next()`, `.setVolume(0–100)`, `.activate()` and the rest                             | `{ state, confirmed }`                                                                           |
+| spotify   | `.duck(fn, { to })`, `.interrupt(fn)`                                                                              | `{ value, music, why? }`: `fn`'s result, and `music` `untouched`, `restored`, `kept` or `failed` |
+| cast      | `.announce(target, clip, { volume? })`                                                                             | `{ played, why?, restored, notRestored }`                                                        |
+| cast      | `.announceAll(targets, clip, { volume? })`                                                                         | one of those per target, each with its `target`                                                  |
+| cast      | `.setVolume(target, 0–1)`, `.setMuted(target, on)`, `.stop(target)`                                                | nothing                                                                                          |
+| hue       | `.client.light(name, change, opts?)`, `.room(name, change, opts?)`, `.scene(name, room?, opts?)`, `.allOff(opts?)` | `{ state, confirmed }`, `state` the light, the room, or every light                              |
+| hue       | `.client.put(kind, id, body)`, `.client.recallScene(id)`                                                           | the bridge's answer, for what the typed writes don't cover                                       |
+
+- **`confirmed`** is true once the device reported what was asked. False is a result, not an error: the write was sent and the device hasn't shown it yet, and `state` is how it stood.
+- **Dry run.** `opts` is `{ dryRun: true }` on Hue's and the Daikin's writes: every check made before sending runs (the name, the range, a lost light; a colour off the gamut shows moved in the body) and nothing is sent. The device can still refuse a real write that a dry run passed. The result has `wouldSend`, the request it would make (Hue: `{ method, path, body }`; Daikin adds `sets`, `{ on?, mode?, targetC? }`), `state` as things stand now, and `confirmed: false`, so check `wouldSend` first. A wrong name still throws with the names that exist. For testing a bot end to end with people home; `home … --dry-run` does the same from the terminal.
+- **Use the returned state.** The Daikin's part in the snapshot is from its last poll and can be 120 s behind, unless you call `home.refresh("daikin")`.
+- **Daikin defaults.** `mode("cool")` is 25 °C and `mode("heat")` 27 (`DEFAULT_TARGET_C`); `mode("cool", 23)` for another. `power(true)` brings the unit back as it was last left.
+- **A target** for Cast is a device's or group's name or id. A clip is `{ url, type? }` or `{ bytes, type }`; bytes need `castServe`.
+- **Clips: MP3 or AAC.** A 24 kHz mono WAV played on the displays and failed on the audio-only speakers (2026-11-09), so convert a WAV from a text-to-speech engine first.
+- **Adding one while it runs.** `await home.add(integration)` starts it on the running home; the rest keep their sockets. One already there under that name is stopped first, so this is also how an `unavailable` part comes back once its key is fixed. `await home.remove(name)` stops one and drops its part. After pairing Hue from a chat, add the bridge's entry to the config (`loadHome` refuses an entry whose key is unset, so it can't be there before), build it as the config would, so it gets the pinned fetch and discovery, and add that one:
+
+  ```ts
+  const { key } = await pairWhenPressed({
+    host,
+    fetch: bunPinnedFetch(bridgeId),
+    deviceType: "chota#pi",
+  });
+  const built = loadHome(config, {
+    ...options,
+    env: { ...process.env, HUE_APPLICATION_KEY: key },
+  });
+  await home.add(built.find((i) => i.name === "hue")!);
+  ```
+
+  A replaced part starts over from `connecting`, with no state and no `lastGoodAt`, and no `onChange` until its first report. The second `loadHome` keeps its own copy of the address cache, so pass the same `cache` and expect the last writer to win.
+
+- **Hue by name.** `room("Bedroom", { brightness: 40, kelvin: 2700 })`, `light("Desk lamp", { color: "#ff8800" })`, `scene("Relax", "Bedroom")`, and `allOff()` for every light in the home. A change is `{ on?, brightness?, color?, kelvin?, transitionMs? }`; an unknown name throws with the names that exist.
+- **Volume scales differ:** Cast 0–1, Spotify 0–100.
+
+Announce only where nothing is playing, with the music on this machine turned down meanwhile:
+
+```ts
+import { castFreeSpeakers } from "@khalido/home/cast";
+
+const cast = home.integration("cast");
+const state = home.part("cast")?.state;
+if (cast && state) {
+  // Every free speaker and display, a whole group where all of it is free, never a TV.
+  const { free, skipped } = castFreeSpeakers(state); // skipped: { name, why }
+  const announce = () =>
+    cast.announceAll(free, { url: clipUrl }, { volume: 0.3 });
+  const speaker = home.integration("spotify");
+  const results = speaker
+    ? (await speaker.duck(announce, { to: 20 })).value
+    : await announce();
+  for (const r of results) if (!r.played) log(`${r.target}: ${r.why}`);
+}
+```
+
+`castStatus(state)` gives each device's and group's `idle`, `restorable`, `busy` or `offline`, with the app and title. For Spotify, `speakerState(part)` says the speaker in one word (offline, waiting, idle, playing, paused, or elsewhere when the account's music is on another Spotify device; `spotifyElsewhere(home.snapshot())` names the Cast device when it is one) and `spotifyChanges(change.before, change.after)` turns an `onChange` into events (started, resumed, paused, stopped, track, stalled, recovered, offline, waiting, picked), those from the library's own `duck` or `interrupt` marked `own`.
+
+## When something is wrong
+
+Two places say so, for two different things.
+
+**A part's status** is about the connection, and reading it never throws:
+
+| `status`       | Means                                     | Do                                                          |
+| -------------- | ----------------------------------------- | ----------------------------------------------------------- |
+| `connecting`   | not answered yet                          | wait                                                        |
+| `connected`    | reading                                   |                                                             |
+| `disconnected` | unreachable now; the last `state` is kept | nothing: it keeps trying, and looks for a device that moved |
+| `unavailable`  | stopped for good                          | read `reason`, fix it, `home.add` it again                  |
+
+`reason` is set on `unavailable`, when known: `auth` (a key or token was rejected: a person must re-key), `config` (a setting or file is wrong) or `crashed` (its `run` threw; a bug). `detail` is the sentence for a person, `anomaly` an odd reading passed through. An `unavailable` part does not recover by itself: after the fix, `home.add` a fresh one under the same name.
+
+**A write that can't be made throws** a `ConnectorError` (`HueError`, `DaikinError` and so on are subclasses), with the HTTP `status` when there was one and, where code can act on it, a `code`:
+
+| `code`        | From         | Means                                                                         |
+| ------------- | ------------ | ----------------------------------------------------------------------------- |
+| `link_button` | hue          | pairing: the bridge's button has not been pressed                             |
+| `offline`     | spotify, hue | not connected; for Hue, a light the bridge has lost                           |
+| `waiting`     | spotify      | signed out: someone must pick the speaker in the Spotify app                  |
+| `inactive`    | spotify      | it is not the active device; `activate()` first, if that is wanted            |
+| `refused`     | spotify      | Soloist answered no                                                           |
+| `timeout`     | spotify      | no answer in time                                                             |
+| `invalid`     | spotify, hue | a value it can't take, or for Hue a name that doesn't exist; nothing was sent |
+| `ipp`         | printers     | the printer answered an IPP error, its number in `status`                     |
+
+Other failures carry no `code`: read the message (a Daikin setpoint off its range, a Cast target that doesn't exist, a device that didn't answer). Cast's `announce` throws only before anything changed; after that a failure is `played: false` with `why`.
+
+`ConnectorCode` is the union, so a `switch` over it fails to compile when one is added.
 
 ## Text for people and agents
 

package/examples/home.jsonc

@@ -22,6 +22,8 @@
       "name": "Living",
       "floor": "ground",
       "hueRoom": "11111111-1111-4111-8111-111111111111",
+      // Photos of the room, for whoever draws or shows it; the library only carries the paths.
+      "photos": ["photos/living-1.jpg", "photos/living-2.jpg"],
     },
     {
       "id": "room-kitchen",
@@ -49,7 +51,6 @@
       "host": "192.0.2.2",
       "bridgeId": "0017880000000000",
       "key": "HUE_APPLICATION_KEY",
-      "ca": "hue-root-ca.pem",
     },
     {
       "id": "ac",

package/home.schema.json

@@ -82,6 +82,14 @@
           "hueRoom": {
             "description": "the Hue room, zone or grouped_light id whose lights this room's marker shows",
             "type": "string"
+          },
+          "photos": {
+            "description": "photos of the room, as paths relative to the config or from ~/; the library never reads them, a drawing agent or an app does",
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
           }
         },
         "required": [
@@ -116,9 +124,9 @@
                 "description": "env name holding the application key from `home pair`"
               },
               "ca": {
+                "description": "a root CA (PEM) to trust instead of Signify's two, which the package carries; relative to the config file",
                 "type": "string",
-                "minLength": 1,
-                "description": "Signify's root CA (PEM), relative to the config file"
+                "minLength": 1
               },
               "id": {
                 "type": "string"
@@ -137,7 +145,6 @@
               "host",
               "bridgeId",
               "key",
-              "ca",
               "id"
             ],
             "additionalProperties": {}

package/llms.txt

@@ -2,22 +2,35 @@
 
 > Small, typed home automation for TypeScript, published on npm as `@khalido/home`, with a `home` command. It starts with one home's devices: Philips Hue, a Daikin AC, Enphase solar, Google Cast, AirPrint printers and a Spotify Soloist speaker on the local network; Amber Electric prices, Up Bank spending and the weather from the cloud. Runs on Bun 1.4+ and Node 24+; the CLI needs Bun. MIT.
 
-The library never reads the environment or a file: callers pass addresses, keys and a `fetch`. `createHome` runs integrations and keeps one typed snapshot; `loadHome` builds them from a home config that names env vars, never secrets. Every field a device reports is optional, and odd readings pass through in `anomaly` rather than being corrected. Writes go through a per-device lane: spaced, bursts merged.
+The library never reads the environment or a file: callers pass addresses, keys and a `fetch`. `createHome` runs integrations and keeps one typed snapshot; `loadHome` builds them from a home config that names env vars, never secrets. Every field a device reports is optional, and odd readings pass through in `anomaly` rather than being corrected. Writes go through a per-device lane: spaced, bursts merged. Write to a device only when a person asked for that change.
+
+## What you call
+
+- **One home:** `loadHome(config, options)` builds the integrations and `createHome(integrations, onChange)` runs them: `home.start(signal)`, `home.snapshot()`, `home.part(name)`, `home.refresh(name)`, `home.integration(name)` for the writes, and `home.add(integration)` / `home.remove(name)` to change the set while it runs. `health(home.snapshot(), Date.now())` judges each part. All from `@khalido/home`.
+- **Every device, one shape:** `homeDevices(snapshot, config?)` gives a `DeviceRecord` per device (`connector`, `id`, `name`, `kind`, `available`, `reason`, `state`, `text`, `room`), with the connector's own typed row in `detail`. `byRoom(snapshot, config)` groups them by the config's rooms, for a map.
+- **Why a part is down:** `part.status` (`connected`, `disconnected`, `unavailable`) and, when `unavailable`, `part.reason` (`auth`, `config`, `crashed`). Errors are `ConnectorError` with a typed `code`.
+- **Hue** (`@khalido/home/hue`): `pairWhenPressed` waits for the bridge's button and returns `{ key }`; Signify's root certificates are in the package, so `hue({ host, bridgeId, key })` needs no file. Writes by name: `client.light(name, change)`, `client.room(name, change)`, `client.scene(name, room?)`, `client.allOff()`, with `change` `{ on?, brightness?, color?, kelvin?, transitionMs? }`, each resolving `{ state, confirmed }`. `{ dryRun: true }` as the last argument checks and returns `wouldSend` without sending.
+- **Daikin** (`@khalido/home/daikin`): `client.power(on)` and `client.mode(mode, targetC?)` resolve `{ state, confirmed }`, and take `{ dryRun: true }` last; cool defaults to 25 °C and heat to 27.
+- **Cast** (`@khalido/home/cast`): `castStatus(state)` and `castFree(state, targets, { forms? })`, on the Cast part's state, say what is playing and where an announcement would disturb nothing; `castFreeSpeakers(state)` is the one call for every free speaker and display; `announce`, `announceAll`, `setVolume`, `setMuted`, `stop`.
+- **Spotify Soloist** (`@khalido/home/spotify`): `play`, `pause`, `setVolume` and the rest resolve `{ state, confirmed }`; `duck` and `interrupt` wrap an announcement. `speakerState(part)` is `elsewhere` when the music is on another Spotify device.
+- **Discovery** (`@khalido/home/finders`, Node-side): `FINDERS`, one finder per connector, and `fileCache`. **Node** needs the fetches in `@khalido/home/node`.
+- **The command:** `home`, `home devices`, `home <connector>`, and writes such as `home daikin cool`, `home room <name> on`, `home cast announce`.
 
 ## Start here
 
 - [README](https://raw.githubusercontent.com/khalido/home.ts/main/README.md): what it is, install, the connectors
-- [Using it from an app](https://raw.githubusercontent.com/khalido/home.ts/main/docs/using.md): createHome, loadHome, health, change events, writes, energy
+- [Using it from an app](https://raw.githubusercontent.com/khalido/home.ts/main/docs/using.md): the whole wiring on Bun, every device in one list, each write and what it returns, errors, health, energy
 - [The home config](https://raw.githubusercontent.com/khalido/home.ts/main/docs/config.md): devices by identity, rooms, discovery
-- [The home command](https://raw.githubusercontent.com/khalido/home.ts/main/docs/cli.md): status, probe, discover, per-connector verbs
+- [The home command](https://raw.githubusercontent.com/khalido/home.ts/main/docs/cli.md): status, devices, probe, discover, per-connector verbs
 - [Agent skill: use-home](https://raw.githubusercontent.com/khalido/home.ts/main/skills/use-home/SKILL.md): reading safely, connecting, the rules for writes
 
 ## Connectors
 
-- [hue](https://raw.githubusercontent.com/khalido/home.ts/main/src/connectors/hue/README.md): lights, rooms, scenes over the bridge's event stream
-- [daikin](https://raw.githubusercontent.com/khalido/home.ts/main/src/connectors/daikin/README.md): the AC over its local API
+- [hue](https://raw.githubusercontent.com/khalido/home.ts/main/src/connectors/hue/README.md): lights, rooms, scenes over the bridge's event stream; pairing
+- [hue: Signify's guidance](https://raw.githubusercontent.com/khalido/home.ts/main/docs/hue.md): certificates, discovery, write rates, rooms, colour, pairing, and what this library does about each
+- [daikin](https://raw.githubusercontent.com/khalido/home.ts/main/src/connectors/daikin/README.md): the AC over its local API: power and mode writes that report what the unit then said
 - [enphase](https://raw.githubusercontent.com/khalido/home.ts/main/src/connectors/enphase/README.md): solar from the IQ Gateway
-- [cast](https://raw.githubusercontent.com/khalido/home.ts/main/src/connectors/cast/README.md): Cast devices and groups, volume, announcements
+- [cast](https://raw.githubusercontent.com/khalido/home.ts/main/src/connectors/cast/README.md): Cast devices and groups, what each is playing, volume, announcements
 - [printers](https://raw.githubusercontent.com/khalido/home.ts/main/src/connectors/printers/README.md): AirPrint printers over IPP
 - [spotify](https://raw.githubusercontent.com/khalido/home.ts/main/src/connectors/spotify/README.md): a Spotify Soloist speaker: state, confirmed writes, duck and interrupt, change events, stall watch
 - [amber](https://raw.githubusercontent.com/khalido/home.ts/main/src/connectors/amber/README.md): live electricity prices and forecast

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khalido/home",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "home.ts: small, typed home automation for TypeScript: Hue, Daikin, Enphase, Google Cast, AirPrint printers and a Spotify Soloist speaker on the local network; Amber prices, Up Bank spending and the weather from the cloud.",
   "license": "MIT",
   "author": "Khalid Omar",

package/skills/draw-home/README.md

@@ -1,5 +1,7 @@
 # draw-home: references
 
+Where the skill is going, from a floor plan PDF to a live view: [khalido/home.ts#3](https://github.com/khalido/home.ts/issues/3).
+
 Good drawing references to read before drawing a home, newest idea first. All are skills or kits for coding agents; read for craft, keep this skill's contract (`SKILL.md` section 3) where they disagree.
 
 | Reference                                                                                                                                                     | What it is                                                                                                                                                                                                                                                                                                                                         | Use it for                                                                                                                                                                          | Licence                                                          |

package/skills/draw-home/SKILL.md

@@ -67,7 +67,7 @@ Make a **room table** first, in the SVG's header comment: each room, its floor,
 }
 ```
 
-Room ids start with `room-`; names are what the person calls them (an unlabelled room keeps `""` until they say). No `room` on whole-house devices (solar, prices). The solar array is drawn on the roof with its own marker; set the Enphase device's `marker` to its id, and `capacityW` only when the person gives the rated size. Lights are placed through the room's `hueRoom`, not as devices. `marker` in the config always means an SVG marker id.
+Room ids start with `room-`; names are what the person calls them (an unlabelled room keeps `""` until they say). No `room` on whole-house devices (solar, prices). The solar array is drawn on the roof with its own marker; set the Enphase device's `marker` to its id, and `capacityW` only when the person gives the rated size. Lights are placed through the room's `hueRoom`, not as devices. A room's `photos` lists the pictures it was drawn from, as paths relative to the config, when the person wants them kept. `marker` in the config always means an SVG marker id.
 
 ## 5. Check before hand-over
 

package/skills/use-home/SKILL.md

@@ -9,8 +9,8 @@ description: Use the `home` command and the @khalido/home library to see and run
 
 ## Rules
 
-- **Reads are free.** `home`, `home <connector>`, `home discover`, `home probe`, `home up spend` and every `--json` read touch nothing.
-- **Writes only on request.** Lights, AC, speakers, Up categories and tags, webhooks: run one only when the person asked for that change, then read back and report the state it left. Never write to "test" something.
+- **Reads are free.** `home`, `home <connector>` with no verb, `home devices`, `home discover`, `home probe`, `home up spend` and every `--json` read touch nothing.
+- **Writes only on request.** Lights, AC, speakers, printing, Up categories and tags, webhooks: run one only when the person asked for that change, then read back and report the state it left. Never write to "test" something: `--dry-run` on a Hue or Daikin write (`home room …`, `home scene …`, `home lights off`, `home daikin …`, `home printers print …`) checks it and prints what it would send, sending nothing (a print's dry run also asks the printer to validate the job, which prints nothing); other commands refuse the flag.
 - **Never print a key, token or password**, not even part of one. Say "set" or "unset". Env names are fine; values are not.
 - **Nothing private into a public repo**: no IPs, MACs, serials, device or room names, Up transactions or balances. A real `home.jsonc`, `home.svg` and floor plan live in a private folder.
 - **Show values as read.** A missing field is unknown, not zero. An `anomaly` is something odd the device said: report it, never smooth it.
@@ -43,7 +43,7 @@ Weather: `blocks` holds morning, afternoon and evening for today and tomorrow in
 
 **Keys** come from environment variables by name (`.env.example` lists them; Bun loads `.env` from the working directory). A real environment variable beats `.env`. Some keys come from a command, not a website:
 
-- Hue: press the bridge's button, then `home pair` within 30 s; it prints the env lines. Set `HUE_CA_FILE` to Signify's root CA (`src/connectors/hue/README.md`).
+- Hue: `home pair`, then press the bridge's button within the 60 s it counts down; it prints the env lines. Signify's root certificates are in the package.
 - Enphase: `home enphase login` once a year writes the owner token to `~/.config/home/enphase-token.json` (0600).
 - Amber, Up, Google Weather: a token from each service's website.
 - Spotify (Soloist): no key in `home`; Soloist's own API key is the daemon's. Set `SOLOIST_WS` to the address its `--ws` opens. Signed out is normal until someone picks the speaker in the Spotify app.

package/src/cli/cast.ts

@@ -7,9 +7,12 @@ import { tmpdir } from "node:os";
 import { extname, join } from "node:path";
 import {
   cast,
+  type CastDevice,
   type CastSnapshot,
+  castText,
   resolvedFrom,
 } from "../connectors/cast/index.ts";
+import { findCast } from "../connectors/cast/state.ts";
 import { serveClip } from "../connectors/cast/serve.ts";
 import { tlsConnect } from "../connectors/cast/tls.ts";
 import { addressBook } from "../discover.ts";
@@ -52,7 +55,10 @@ export function castNow() {
 
 /** Open every Cast socket, wait until each has answered (at most 10 s), run one write over them, then close them all. */
 async function withCast<T>(
-  act: (c: ReturnType<typeof castNow>) => Promise<T>,
+  act: (
+    c: ReturnType<typeof castNow>,
+    state: () => CastSnapshot | undefined,
+  ) => Promise<T>,
 ): Promise<T> {
   const c = castNow();
   const stop = new AbortController();
@@ -64,7 +70,7 @@ async function withCast<T>(
       Date.now() < until && (last?.status ?? "connecting") === "connecting";
     )
       await Bun.sleep(50);
-    return await act(c);
+    return await act(c, () => last?.state);
   } finally {
     stop.abort();
     await running;
@@ -105,19 +111,59 @@ export const CAST_OPTIONS: [string, string, { type: unknown[] }?][] = [
   ["--volume <0-100>", "announce: the volume for the clip"],
 ];
 
+/** How long a write waits for the device to report the change before saying it was only sent. */
+const SHOWN_MS = 2000;
+
+/** One write, then the device's line once it reports what was asked, or that it has not yet. */
+const wrote = (
+  name: string,
+  write: (c: ReturnType<typeof castNow>) => Promise<void>,
+  shown: (d: CastDevice) => boolean,
+) =>
+  withCast(async (c, state) => {
+    await write(c);
+    const now = () => {
+      const s = state();
+      const d = s && findCast(s.devices, name);
+      return s && d ? { line: castText(d, s), ok: shown(d) } : undefined;
+    };
+    for (const until = Date.now() + SHOWN_MS; Date.now() < until;) {
+      if (now()?.ok) break;
+      await Bun.sleep(50);
+    }
+    const after = now();
+    console.log(
+      after?.ok
+        ? after.line
+        : `sent; the device has not reported it yet${after ? ` (${after.line})` : ""}`,
+    );
+  });
+
 export const castVerbs: Verbs = {
   async volume([name, value]) {
     if (!name) usage(CAST_USAGE);
     const level = percentLevel(value);
-    await withCast((c) => c.setVolume(name!, level));
+    await wrote(
+      name!,
+      (c) => c.setVolume(name!, level),
+      (d) => d.volume !== undefined && Math.abs(d.volume - level) < 0.006,
+    );
   },
   async mute([name, value]) {
     if (!name || (value !== "on" && value !== "off")) usage(CAST_USAGE);
-    await withCast((c) => c.setMuted(name!, value === "on"));
+    await wrote(
+      name!,
+      (c) => c.setMuted(name!, value === "on"),
+      (d) => d.muted === (value === "on"),
+    );
   },
   async stop([name]) {
     if (!name) usage(CAST_USAGE);
-    await withCast((c) => c.stop(name!));
+    await wrote(
+      name!,
+      (c) => c.stop(name!),
+      (d) => d.idle === true,
+    );
   },
   async announce(_, o) {
     const [say, file] = [text(o.say), text(o.file)];

package/src/cli/context.ts

@@ -38,6 +38,8 @@ export const usage = (message: string): never => fail(message, "usage");
 /** The options cac parses: the global ones, and each command's own. */
 export type Options = {
   json?: boolean;
+  /** `--dry-run`: Hue and Daikin writes check and say what they would send, and send nothing. */
+  dryRun?: boolean;
   config?: string;
   write?: string | true;
   passes?: number | string;

package/src/cli/daikin.ts

@@ -0,0 +1,71 @@
+// `home daikin on|off` and `home daikin cool|heat|auto|dry|fan [°C]`: one write to the AC, then what it reports.
+// Live on KO's unit (2026-11-11): on, and dry to cool at 25. Off, heat, auto, fan and a fan speed are untried.
+import {
+  acText,
+  type DaikinApplied,
+  daikinClient,
+  DEFAULT_TARGET_C,
+  type Mode,
+  setTarget,
+} from "../connectors/daikin/index.ts";
+import { findDaikins } from "../finders.ts";
+import { env, fail, type Options, usage, type Verbs } from "./context.ts";
+
+export const DAIKIN_USAGE = `usage: home daikin on | off | cool [°C] | heat [°C] | auto [°C] | dry | fan  (cool ${DEFAULT_TARGET_C.cool} and heat ${DEFAULT_TARGET_C.heat} when no °C is given)`;
+
+let found: Promise<string | undefined> | undefined;
+/** The unit's address: DAIKIN_HOST, else the first to answer the UDP broadcast (asked once a run). Undefined when none does. */
+export const daikinHost = (): Promise<string | undefined> =>
+  (found ??= env.DAIKIN_HOST
+    ? Promise.resolve(env.DAIKIN_HOST)
+    : findDaikins().then((units) => units[0]?.ip));
+
+async function unit() {
+  const host =
+    (await daikinHost()) ??
+    fail("no Daikin answered the UDP broadcast; set DAIKIN_HOST", "network");
+  return daikinClient({ host, fetch });
+}
+
+/** What a write left, in a line: the unit as it then reported, that it has not reported the change yet, or what a dry run would send. */
+const said = ({ state, confirmed, wouldSend }: DaikinApplied) =>
+  console.log(
+    wouldSend
+      ? `dry run, nothing sent: would set ${JSON.stringify(wouldSend.sets)} (now ${acText(state)})`
+      : confirmed
+        ? acText(state)
+        : `sent; the unit has not reported it yet (${acText(state)})`,
+  );
+
+const power =
+  (on: boolean) =>
+  async ([extra]: string[], o: Options) =>
+    extra
+      ? usage(DAIKIN_USAGE)
+      : said(await (await unit()).power(on, { dryRun: !!o.dryRun }));
+
+const mode =
+  (m: Mode) =>
+  async ([value, extra]: string[], o: Options) => {
+    if (extra || (value !== undefined && !/^\d+(\.\d+)?$/.test(value)))
+      usage(DAIKIN_USAGE);
+    const c = value === undefined ? undefined : Number(value);
+    // A setpoint the mode can't take is a usage error, said before looking for the unit.
+    if (c !== undefined)
+      try {
+        setTarget(c, m);
+      } catch (e) {
+        usage(`${(e as Error).message}; ${DAIKIN_USAGE}`);
+      }
+    said(await (await unit()).mode(m, c, { dryRun: !!o.dryRun }));
+  };
+
+export const daikinVerbs: Verbs = {
+  on: power(true),
+  off: power(false),
+  cool: mode("cool"),
+  heat: mode("heat"),
+  auto: mode("auto"),
+  dry: mode("dry"),
+  fan: mode("fan"),
+};

package/src/cli/enphase.ts

@@ -7,8 +7,16 @@ import {
   tokenExpiry,
 } from "../connectors/enphase/index.ts";
 import { daysLeft } from "../connectors/enphase/client.ts";
-import { writePrivate } from "../finders.ts";
-import { env, fail, homeTimeZone, TOKEN_FILE, type Verbs } from "./context.ts";
+import { addressBook } from "../discover.ts";
+import { FINDERS, writePrivate } from "../finders.ts";
+import {
+  addresses,
+  env,
+  fail,
+  homeTimeZone,
+  TOKEN_FILE,
+  type Verbs,
+} from "./context.ts";
 
 /** The cached Enphase token, or undefined if `home enphase login` has not run. A corrupt file throws, naming it. */
 export function enphaseToken(): { token: string; expiresAt: Date } | undefined {
@@ -31,12 +39,30 @@ export function enphaseToken(): { token: string; expiresAt: Date } | undefined {
   }
 }
 
-/** Enphase as an integration from IQ_GATEWAY_HOST and the token file, for `home status`. */
-export function enphaseFromEnv() {
+/**
+ * Enphase as an integration for `home status`: IQ_GATEWAY_HOST, else the address cache, else the first gateway mDNS finds.
+ * With the gateway's serial from the cache, a read that fails is followed by discovery at once, so an IQ_GATEWAY_HOST left
+ * behind by a DHCP move still reads, and its detail says where the gateway went.
+ */
+export async function enphaseFromEnv() {
   const t =
     enphaseToken() ?? fail("no Enphase token", "auth", "home enphase login");
+  const book = addressBook(addresses.cache);
+  const serial = Object.keys(book.entries())
+    .find((k) => k.startsWith("enphase:"))
+    ?.slice("enphase:".length);
+  const cached = serial ? book.fresh("enphase", serial) : undefined;
+  const host =
+    env.IQ_GATEWAY_HOST ??
+    cached?.host ??
+    (await FINDERS.enphase())[0]?.host ??
+    fail("no gateway found by mDNS; set IQ_GATEWAY_HOST", "network");
   return enphase({
-    host: env.IQ_GATEWAY_HOST!,
+    host,
+    serial,
+    find: FINDERS.enphase,
+    seen: (h) => book.seen("enphase", serial, { host: h }),
+    hostCached: true, // an env address is as likely stale as a cached one: look again after one failure
     token: t.token,
     fetch: bunGatewayFetch(),
     timeZone: homeTimeZone(),