@khalido/home 0.1.0 → 0.1.2

package/docs/cli.md

@@ -3,6 +3,7 @@
 ```sh
 home <connector> [--json]     # one connector's lines: amber, cast, daikin, enphase, hue, printers, spotify, up, weather
 home [status|doctor] [--json] # each integration: connected or not, which env names it still needs, rooms
+home up transactions | categories | uncategorised | spend | categorise | tag | webhooks  # Up Bank's lists and reports; categorise and tag write
 home lights off               # one write to the whole-home group
 home room <name> on|off|<1-100>
 home scene <name>
@@ -12,18 +13,19 @@ home discover [--json] [--passes n]  # which smart-home devices answer here (mDN
 home cache [clear]            # the addresses kept between runs, or delete them so the next run discovers afresh
 home config check [path]      # validate a home config: what it would set up, secrets as set or unset by name, every problem
 home discover --write [path]  # with a config (the path, else --config or HOME_CONFIG): match what answers by identity, add new devices, update moved hosts and renamed Cast names in place
-home probe                    # read-only, no keys: Hue's public config, Daikin by UDP broadcast, the IQ Gateway's /info, each weather source, each Cast device's status
+home probe                    # read-only, no keys: Hue's public config, Daikin by UDP broadcast, the IQ Gateway's /info, each weather source, each Cast device's and printer's status
 home locate "<street address>" [--write [path]]  # latitude and longitude from OpenStreetMap's Nominatim; --write sets them in the config's location (and timezone, when absent, to this machine's)
-home cast announce --to <name> (--say "<text>" | --file <path>) [--volume 0-100]  # play a clip, then put back what was playing and the volume
+home cast announce --to <name> [--to <name>…] (--say "<text>" | --file <path>) [--volume 0-100]  # exit 1 if any didn't play; play a clip, then put back what was playing and the volume
 home cast volume <name> <0-100>
 home cast mute <name> on|off
 home cast stop <name>         # end the running app; the device returns to its idle screen
-home spotify pause | play [link] | next | volume <0-100>  # the Soloist speaker at SOLOIST_WS; volume held to SOLOIST_MAX_VOLUME; prints what Soloist then reported
+home spotify activate | pause | play [link] | next | volume <0-100>  # the Soloist speaker at SOLOIST_WS; volume held to SOLOIST_MAX_VOLUME; prints what Soloist then reported
 ```
 
 ## Output
 
 - **stdout is data, stderr everything else.** Notes such as "nothing to categorise" or "no webhooks" go to stderr, so `home … | jq` never sees them.
+- **Bun on PATH.** The command starts with `#!/usr/bin/env bun`. A non-login SSH shell may not have `~/.bun/bin` on its PATH: run `PATH="$HOME/.bun/bin:$PATH" home`.
 - **`--json` shapes.** `home --json` is one object keyed by connector, with `now` (`energyNow`) first. `home <connector> --json` is that connector's object: `status`, `needs`, `access`, `detail`, `anomaly`, then its state (the weather adds `line`, its text). Lists (`home up transactions`, `uncategorised`, `spend --by merchant`) are arrays, `[]` when empty.
 - **Errors under `--json`** are one object on stderr: `{"error": "…", "code": "usage" | "auth" | "network" | "error", "fix": "home enphase login"}`; `fix` is there only when one command resolves it. In text: `home: <error> (run \`<fix>\`)`.
 - **Exit codes.** 0 success, empty results included. 1 a failure, and `home <connector>` when that connector is not `connected`, so a script can test one. 2 a wrong command, verb or argument. `home` alone lists every connector and exits 0 whatever their state.

package/docs/config.md

@@ -24,11 +24,11 @@ const home = createHome(
 - **A device entry is only how to reach it and where it is**: its identity (the Hue `bridgeId`, a Daikin's `mac`, the Enphase `serial`, a Cast `castId`), its last known `host`, a key's env name, a file's path, its `room`. What a device reports about itself (model, firmware) comes live; a note about it is a comment.
 - **Secrets are env variable names** (`"key": "AMBER_KEY"`), resolved against the `env` the caller passes; a pasted key fails the schema. Files (`ca`, `token`) are paths the caller reads, relative to the config; the library reads nothing.
 - **Problems name the field**: an unknown connector, a missing env name or a device in a missing room is an error, never a skip. `checkHome` returns them all; `loadHome` throws them all. Unknown keys pass through for a consumer's own settings.
-- **One device per connector** for now (each integration is named by its connector), except Cast: one entry per device and speaker group (`name`, the Google Home name, and `castId`, the mDNS id), all read by one `cast` integration that finds every address by discovery, since a group's moves with its leader. A `spotify` entry is only its Soloist `url` (and `maxVolume`): a socket on the same machine, with nothing to discover.
+- **One device per connector** for now (each integration is named by its connector), except printers (one entry each, by `uuid`) and Cast: one entry per device and speaker group (`name`, the Google Home name, and `castId`, the mDNS id), all read by one `cast` integration that finds every address by discovery, since a group's moves with its leader. A `spotify` entry is only its Soloist `url` (and `maxVolume`): a socket on the same machine, with nothing to discover.
 - **Identity, not address.** A device is recognised by the id its own discovery reports; `host` is a cache. `home discover` lists what answers (mDNS, Daikin's UDP broadcast), in two passes 5 s apart since both drop answers now and then: the first pass prints at once, the second only what it adds (`--passes 1` for a quick look; `--json` waits for both); with a config (`--config` or `HOME_CONFIG`) it then matches those against it by identity and prints new devices, moved addresses and conflicts (a different device at an entry's host). `home discover --write <file>` adds the new ones (each with an id no entry has), updates moved hosts and refreshes the `name` of a Cast entry renamed in the Google Home app through `jsonc-parser`'s edits, every comment and other line left as it was, and writes only a result that passes `checkPlan`. Nothing else writes the file; the library never does. Two devices with one id are a config problem.
 - **A device that moves is found again, without periodic scans**, when the caller passes `finders` to `loadHome` (`FINDERS` from `@khalido/home/finders`, Node-side like `weather/ftp`; the CLI does, and jaldi and chota-bot can). After three failed reads in a row (Hue: three failed reconnects of its event stream), Hue, Daikin and Enphase run their discovery (two passes, the second skipped when the first finds the device), switch to the address their identity now answers at and say "moved from a to b" in `detail` (persist it with `home discover --write`); otherwise they look again at 1, 5 and 15 minutes, then hourly for as long as reads fail, so a device back from the wall socket reads again without a restart. The detail says what discovery found ("not found by discovery", or "discovery finds it at its address but reads fail", or "discovery failed: …" when it could not run), and "no answer for a day" once a day has passed; the part stays `disconnected`, since `unavailable` is for a rejected key. `refresh()` resets the wait. Amber and the weather have no discovery and do not take part. Cast always needs `finders.cast`: discovery is how it finds every address.
 - **Discovery is rare: addresses are cached between runs.** `loadHome(config, { cache, configAt })` takes an `AddressCache` (`read()` and `write(entries)`, keyed by connector and identity, each entry `{ host, port?, name?, seenAt }`). A cached address newer than the config (`configAt`, the file's modified time) is tried first, a failure there scans at once rather than after three, and each address that answers is written back when it changed or predates the config, so a config edit is re-trusted at the first good read. Nothing evicts an entry but `home cache clear`: a device gone for good keeps its entry, and `home status` without a config, which reads every Cast entry from the cache, shows it as not found until then. The consumer persists it: the CLI keeps `$XDG_CACHE_HOME/home/addresses.json` (default `~/.cache/home/addresses.json`, 0600) through `fileCache` from `@khalido/home/finders`, written at the end of `status`, `probe` and `discover`; jaldi's sidecar and chota-bot pass `FINDERS` and their own cache the same way. The config's `host` stays the human-set fallback and `home discover --write` the way to change the config. `home status` from a Cast config: 0.33–0.44 s cold, 0.13 s with a warm cache, 1.4 s once when a cached address has gone stale (Bun 1.4.2, measured 2026-10-13).
-- **Parsing** is the caller's: the CLI uses Bun's built-in `Bun.JSONC.parse` (comments and trailing commas, no dependency); `jsonc-parser` (already a dependency, for `home discover --write`) parses it anywhere else. `bun run schema` rewrites `home.schema.json` from the zod schema, and a test fails if they drift.
+- **Parsing** is through `jsonc-parser` (comments and trailing commas), on Bun and Node alike; a syntax error throws. `bun run schema` rewrites `home.schema.json` from the zod schema, and a test fails if they drift.
 - `createHome` stays for code-first use.
 
 ## Drawing the home

package/docs/decisions.md

@@ -148,3 +148,4 @@ KO's decisions on this package, newest block last. They override every other doc
 - **Signed out reads as waiting**, everywhere: `speakerState` says `waiting`, the detail says "waiting for someone to pick it", the write error's code is `waiting`.
 - **Stalls (Soloist issue #5) are noticed by default and repaired only when asked** (`repairStalls: true`): the repair is the library's first write nobody asked for, so a consumer opts in. Two signals, since the issue doesn't say whether the reported position freezes: a frozen position across fresh reports, and still playing well past the track's end, the symptom actually reported. One repair per track, never a loop. The nudges (seek, then pause and play; a skip past the end) are guesses until a stall is seen live.
 - **The project is home.ts; the npm package stays `@khalido/home`** (KO, 2026-11-08), so imports stay short (`@khalido/home/spotify`). It is home automation for TypeScript, starting with the devices in KO's house, and is meant to grow into more of the basics.
+- **Spotify: inactive is refused, and activating is the caller's choice** (KO, 2026-11-09). Soloist accepts and drops `set_volume` while it isn't the active device. `setVolume` refuses with code `inactive`, and `activate()` is separate, because activating makes a new stream and can jump the volume to the level last saved. `duck` runs `fn` anyway, with `music: "untouched"`, because the announcement matters more. `play` goes active itself, since someone asking for music wants it to start; `resume` doesn't, since it worked inactive. The `maxVolume` cap says "lowered" only once Soloist reports it.

package/docs/google.md

@@ -61,7 +61,7 @@ chota's morning print needs an hourly slice (rain chance, mm, condition) for lin
 
 **Auth.** The caller passes `getToken(): Promise<string>`. The library stores no token. chota passes its better-auth token. A `home calendar login` in the CLI (loopback OAuth, token file in `~/.config/home/`, 0600, like `home enphase login`) comes later and needs an OAuth client in Google Cloud.
 
-**State.** The next 14 days per calendar, trimmed to id, title, start, end, all-day, location. Not kept by default: description, attendees, links. All-day events are dates, not instants; they use the home's `timeZone` from the config, never the machine's. Weather has this bug today (`hhmm` in `weather/index.ts`). Calendar must not copy it.
+**State.** The next 14 days per calendar, trimmed to id, title, start, end, all-day, location. Not kept by default: description, attendees, links. All-day events are dates, not instants; they use the home's `timeZone` from the config, never the machine's. Weather's `hhmmIn` does the same.
 
 **Helpers**, pure: `eventsOn(day)`, `next()`, `search(text)`. One owner for "what is today".
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khalido/home",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",
@@ -98,7 +98,7 @@
     }
   },
   "bin": {
-    "home": "./src/cli/main.ts"
+    "home": "src/cli/main.ts"
   },
   "files": [
     "CHANGELOG.md",

package/skills/draw-home/README.md

@@ -1,15 +1,14 @@
 # draw-home: references
 
-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. Local clones live in `~/code/refs/`.
+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                                                          |
 | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
-| [iso-glow](https://isoglow.dev/) (April Zhu; local `~/code/refs/iso-glow/iso-glow/`)                                                                          | A skill that turns a description of an object, device or building into one HTML file: a fine-line isometric drawing where active parts glow and interactive parts respond, with optional orbitable 3D                                                                                                                                              | A live home view: devices that glow when on, pulses when a reading lands; "Glow kit" and "Lessons" sections                                                                         | MIT                                                              |
-| [Anatomy](https://skills.wheresryan.sh/anatomy) ([wheresryan22/anatomy](https://github.com/wheresryan22/anatomy); local `~/code/refs/anatomy/`)               | Solid-figure isometric explanatory drawings, with an iso kit and six worked examples                                                                                                                                                                                                                                                               | An isometric cutaway of the house: craft rules, `kit/iso-kit.mjs` (in the Anatomy repo), `examples/desk-computer/` (in the Anatomy repo)                                            | MIT                                                              |
-| [Hairline](https://github.com/lucasmarkes/hairline) (local `~/code/refs/hairline/`)                                                                           | Line-sketch drawings with a small kernel and a validator                                                                                                                                                                                                                                                                                           | A light, hand-drawn plan style                                                                                                                                                      | MIT                                                              |
-| [ai-iso-skill](https://github.com/MrBongoC/ai-iso-skill) `iso-figure` (local `~/code/refs/ai-iso-skill/`)                                                     | Flat-faced isometric figures on a box, ~10 KB pages                                                                                                                                                                                                                                                                                                | The lightest isometric option                                                                                                                                                       | MIT                                                              |
+| [iso-glow](https://isoglow.dev/) (April Zhu)                                                                                                                  | A skill that turns a description of an object, device or building into one HTML file: a fine-line isometric drawing where active parts glow and interactive parts respond, with optional orbitable 3D                                                                                                                                              | A live home view: devices that glow when on, pulses when a reading lands; "Glow kit" and "Lessons" sections                                                                         | MIT                                                              |
+| [Anatomy](https://skills.wheresryan.sh/anatomy) ([wheresryan22/anatomy](https://github.com/wheresryan22/anatomy))                                             | Solid-figure isometric explanatory drawings, with an iso kit and six worked examples                                                                                                                                                                                                                                                               | An isometric cutaway of the house: craft rules, `kit/iso-kit.mjs` (in the Anatomy repo), `examples/desk-computer/` (in the Anatomy repo)                                            | MIT                                                              |
+| [Hairline](https://github.com/lucasmarkes/hairline)                                                                                                           | Line-sketch drawings with a small kernel and a validator                                                                                                                                                                                                                                                                                           | A light, hand-drawn plan style                                                                                                                                                      | MIT                                                              |
+| [ai-iso-skill](https://github.com/MrBongoC/ai-iso-skill) `iso-figure`                                                                                         | Flat-faced isometric figures on a box, ~10 KB pages                                                                                                                                                                                                                                                                                                | The lightest isometric option                                                                                                                                                       | MIT                                                              |
 | [casa-serra](https://github.com/Sam1983Aing/casa-serra) (Sam1983Aing; live demo linked from the README, three.js + GSAP ScrollTrigger + Lenis, no build step) | "A flat floor plan that becomes a house as you scroll": the plan "is not a picture. It is the real 3D model, cut at 1.2 m and seen from straight above through a very long lens"; scrolling raises the cut so the walls rise, rooms stay a line drawing until the camera reaches them, geometry built in code, a still and a clip for weak devices | The strongest version of the "SVG with a camera" option (`SKILL.md`): one model in metres, the flat plan as the top view of it, zoom and orbit as a redraw. Added by KO 2026-10-13. | No licence file (checked 2026-10-13): approach only, never paste |
-| sfl-mes `device-drawing` (`~/code/sfl-mes/.claude/skills/device-drawing/`, private)                                                                           | KO's skill for drawing one machine that moves with its live reading                                                                                                                                                                                                                                                                                | Sources-first discipline, the live contract (no data, never clamp, fit the host), the review step                                                                                   | KO's                                                             |
 
 Default stays a flat plan (`examples/home.svg`): it is the fastest to draw, reads at card size, and is easy for an app to draw state on. Pick iso-glow or Anatomy when the home view is the point rather than a panel beside it.
 

package/skills/draw-home/SKILL.md

@@ -12,8 +12,6 @@ The library does not draw. This guide is for the coding agent that does: turn wh
 
 Start from `examples/home.svg` and `examples/home.jsonc`. Never start from a blank file. If the person already has a `home.jsonc`, edit its `rooms` and `plan` in place, keeping its comments, and leave every other field alone.
 
-This is the home-sized version of the sfl-mes `device-drawing` skill (`~/code/sfl-mes/.claude/skills/device-drawing/`), which draws single machines; read it when a rule here seems thin.
-
 ## 1. Sources, before any geometry
 
 Make a **room table** first, in the SVG's header comment: each room, its floor, its name as the person says it, and the source (plan sheet and page, or photo). Nothing is drawn that has no row.
@@ -27,7 +25,7 @@ Make a **room table** first, in the SVG's header comment: each room, its floor,
 
 - Rooms as rectangles, or simple paths for L-shapes; walls, the front door, stairs. Front of the house in the same place on every floor; one floor per band of the canvas, labelled, ground below.
 - **Style: a flat plan by default.** `README.md` beside this file lists the drawing references (iso-glow, Anatomy, Hairline, iso-figure) with what each is good for.
-- **Isometric options.** A glowing fine-line drawing in the [iso-glow](https://isoglow.dev/) style suits a live view; an isometric cutaway in the **Anatomy** style (solid figures, MIT, `~/code/refs/anatomy/`, [skills.wheresryan.sh/anatomy](https://skills.wheresryan.sh/anatomy)) is an option when the person asks for it: read its `SKILL.md` craft rules and `examples/desk-computer/` (in the Anatomy repo), keep this contract, and draw rooms as low boxes with the markers on their floors.
+- **Isometric options.** A glowing fine-line drawing in the [iso-glow](https://isoglow.dev/) style suits a live view; an isometric cutaway in the **Anatomy** style (solid figures, MIT, [skills.wheresryan.sh/anatomy](https://skills.wheresryan.sh/anatomy)) is an option when the person asks for it: read its `SKILL.md` craft rules and `examples/desk-computer/` (in the Anatomy repo), keep this contract, and draw rooms as low boxes with the markers on their floors.
 
 ## 3. The contract (an app draws on this; keep it exact)
 
@@ -38,7 +36,7 @@ Make a **room table** first, in the SVG's header comment: each room, its floor,
 5. The SVG fills its host (`width: 100%; height: 100%`; the viewBox holds everything).
 6. **Zoomable**: one root `<g id="plan">` holding every floor, no fixed pixel sizes, labels sized so they still read when a single room fills the screen. Each room group's `getBBox()` is its zoom target, so keep a room's label and marker inside its shape.
 
-**What an app does with it** (from sfl-mes's live contract): it draws each device's state into its room's marker from `home.snapshot()`. A missing part is "no data": grey marker, no value, never a stale number shown as live. Values are shown as read, never clamped; odd ones (`Part.anomaly`) get a flag. Hover names the device. Controls live in the app's side panel, not in the SVG.
+**What an app does with it:** it draws each device's state into its room's marker from `home.snapshot()`. A missing part is "no data": grey marker, no value, never a stale number shown as live. Values are shown as read, never clamped; odd ones (`Part.anomaly`) get a flag. Hover names the device. Controls live in the app's side panel, not in the SVG.
 
 **Energy on the plan** (the numbers are the library's, the drawing and animation are the app's):
 
@@ -48,7 +46,7 @@ Make a **room table** first, in the SVG's header comment: each room, its floor,
 
 **Interactive, in the app**: wheel or pinch zooms and drag pans (animate the `viewBox`, or a transform on `#plan`); clicking a room zooms to its bounding box and opens that room's devices in the side panel; Escape or double-click returns to the whole house; arrow keys move between rooms. Respect reduced motion (jump, do not animate). A flat plan only zooms and pans.
 
-**SVG with a camera** (the interactive option, Anatomy's approach and sfl-mes's "spin"): build the house once as a model in metres (each room a box: x, y, width, depth, floor height; walls and doors on it), and render it to SVG through a camera `{ azimuth, elevation, target, zoom }` with Anatomy's `fitProjection` (`~/code/refs/anatomy/kit/iso-kit.mjs`). The scene is a pure function of the camera, so zooming, orbiting and "fly to this room" are a redraw with a new camera, eased; drag orbits, wheel zooms, click a room sets the target to its centre. The rendered SVG still meets the contract above: one `<g class="room">` per room and a marker projected to the room's top corner on every redraw. Keep the model in its own file named by `plan.json` in the config (sizes are data, not hard-coded in the drawing), and spring back to the default camera on Escape.
+**SVG with a camera** (the interactive option, Anatomy's approach): build the house once as a model in metres (each room a box: x, y, width, depth, floor height; walls and doors on it), and render it to SVG through a camera `{ azimuth, elevation, target, zoom }` with Anatomy's `fitProjection` (`kit/iso-kit.mjs` in the Anatomy repo). The scene is a pure function of the camera, so zooming, orbiting and "fly to this room" are a redraw with a new camera, eased; drag orbits, wheel zooms, click a room sets the target to its centre. The rendered SVG still meets the contract above: one `<g class="room">` per room and a marker projected to the room's top corner on every redraw. Keep the model in its own file named by `plan.json` in the config (sizes are data, not hard-coded in the drawing), and spring back to the default camera on Escape.
 
 ## 4. home.jsonc
 

package/src/cli/cast.ts

@@ -34,6 +34,7 @@ export function castNow() {
           {
             castId: key.slice(5),
             name: c.name ?? key.slice(5),
+            model: c.model,
             host: c.host,
             port: c.port,
           },
@@ -71,7 +72,7 @@ async function withCast<T>(
 }
 
 export const CAST_USAGE =
-  'usage: home cast announce --to <name> (--say "<text>" | --file <path>) [--volume 0-100] | volume <name> <0-100> | mute <name> on|off | stop <name>';
+  'usage: home cast announce --to <name> [--to <name>…] (--say "<text>" | --file <path>) [--volume 0-100] | volume <name> <0-100> | mute <name> on|off | stop <name>';
 
 /** A 0–100 argument as the 0–1 a Cast device takes. */
 function percentLevel(value: string | undefined): number {
@@ -96,7 +97,7 @@ const AUDIO_TYPES: Record<string, string> = {
 export const CAST_OPTIONS: [string, string, { type: unknown[] }?][] = [
   [
     "--to <name>",
-    "announce: the device or group, by name or castId",
+    "announce: the device or group, by name or castId; repeat for several",
     { type: [String] },
   ],
   ["--say <text>", "announce: words spoken by macOS `say`", { type: [String] }],
@@ -119,7 +120,8 @@ export const castVerbs: Verbs = {
     await withCast((c) => c.stop(name!));
   },
   async announce(_, o) {
-    const [to, say, file] = [text(o.to), text(o.say), text(o.file)];
+    const [say, file] = [text(o.say), text(o.file)];
+    const to = [o.to].flat().filter(Boolean).map(String); // --to can repeat
     // cac gives "true" for a flag with no value: `--say` alone must not speak the word "true", so each flag needs a value after it.
     const bare = ["--to", "--say", "--file"].some((f) =>
       process.argv.some(
@@ -130,7 +132,7 @@ export const castVerbs: Verbs = {
       ),
     );
     if (bare) usage(CAST_USAGE);
-    if (!to || !say === !file) usage(CAST_USAGE);
+    if (!to.length || !say === !file) usage(CAST_USAGE);
     const volume =
       o.volume === undefined ? undefined : percentLevel(text(o.volume));
     let type: string;
@@ -160,13 +162,19 @@ export const castVerbs: Verbs = {
       }
       type = "audio/mp4";
     }
-    const r = await withCast((c) =>
-      c.announce(to!, { bytes, type }, { volume }),
+    const results = await withCast((c) =>
+      c.announceAll(to, { bytes, type }, { volume }),
     );
-    if (o.json) return printJson(r);
-    console.log(r.played ? "played" : `not played: ${r.why}`);
-    if (r.restored.length) console.log(`restored: ${r.restored.join(", ")}`);
-    for (const n of r.notRestored)
-      console.log(`not restored: ${n.name}: ${n.why}`);
+    if (results.some((r) => !r.played)) process.exitCode = 1; // docs/cli.md: 1 is a failure, so a script can tell
+    if (o.json) return printJson(to.length === 1 ? results[0] : results);
+    const named = results.length > 1;
+    for (const r of results) {
+      const who = named ? `${r.target}: ` : "";
+      console.log(`${who}${r.played ? "played" : `not played: ${r.why}`}`);
+      if (r.restored.length)
+        console.log(`${who}restored: ${r.restored.join(", ")}`);
+      for (const n of r.notRestored)
+        console.log(`${who}not restored: ${n.name}: ${n.why}`);
+    }
   },
 };

package/src/cli/discover.ts

@@ -14,7 +14,13 @@ import {
   KNOWN_SERVICES,
   matchFound,
 } from "../discover.ts";
-import { browse, daikinFound, FINDERS, findDaikins } from "../finders.ts";
+import {
+  browse,
+  daikinFound,
+  FINDERS,
+  findDaikins,
+  MissingTool,
+} from "../finders.ts";
 import {
   addresses,
   configPathOf,
@@ -83,6 +89,7 @@ export async function discover(o: Options): Promise<void> {
     clock: realClock,
     passes,
     key: (x) => (x.found ? foundKey(x.found) : `${x.what}:${x.name}`),
+    stopOn: (error) => error instanceof MissingTool,
     onPass: (n, added) => {
       if (o.json) return;
       const tty = process.stderr.isTTY;

package/src/cli/spotify.ts

@@ -31,7 +31,7 @@ export const spotifyFromEnv = () =>
   });
 
 export const SPOTIFY_USAGE =
-  "usage: home spotify pause | play [link] | next | volume <0-100>";
+  "usage: home spotify activate | pause | play [link] | next | volume <0-100>";
 
 async function withSpotify<T>(
   act: (s: ReturnType<typeof spotify>) => Promise<T>,
@@ -64,6 +64,7 @@ const said = ({ state, confirmed }: Applied) =>
   );
 
 export const spotifyVerbs: Verbs = {
+  activate: () => withSpotify((s) => s.activate()).then(said),
   pause: () => withSpotify((s) => s.pause()).then(said),
   next: () => withSpotify((s) => s.next()).then(said),
   play: ([link]) => withSpotify((s) => s.play(link)).then(said),

package/src/config.ts

@@ -509,7 +509,9 @@ export function loadHome(
         {
           castId: x.castId,
           name: x.name,
-          ...(c?.port === undefined ? {} : { host: c.host, port: c.port }),
+          ...(c?.port === undefined
+            ? {}
+            : { host: c.host, port: c.port, model: c.model }),
         },
       ];
     });

package/src/connectors/cast/README.md

@@ -4,16 +4,16 @@ Nest speakers, Nest Hubs, Chromecasts, Google TV and speaker groups, read over C
 
 ## Built
 
-- `cast({ resolve, connect })` keeps every Cast device and group current as one integration. `resolve()` returns what mDNS `_googlecast._tcp` found (`id`, `name` from TXT `fn`, `model` from `md`, host, port, `group`); the CLI runs `dns-sd`. `connect` is `tlsConnect` from `@khalido/home/cast/tls`. `expect` lists the config's entries, so one discovery misses shows as disconnected rather than vanishing. From a config, `resolve` is the shared two-pass discovery, done after the first pass once every entry has answered. An entry with a cached address (the address cache, `loadHome`'s `cache`) connects at once with a 1 s timeout; discovery runs only when an entry has none or a cached address fails, so a stale one still reads as `connecting` until discovery has had its say. A cached port other than 8009 marks a group, since devices always listen on 8009.
+- `cast({ resolve, connect })` keeps every Cast device and group current as one integration. `resolve()` returns what mDNS `_googlecast._tcp` found (`id`, `name` from TXT `fn`, `model` from `md`, host, port, `group`); the CLI runs `dns-sd`. `connect` is `tlsConnect` from `@khalido/home/cast/tls`. `expect` lists the config's entries, so one discovery misses shows as disconnected rather than vanishing. From a config, `resolve` is the shared two-pass discovery, done after the first pass once every entry has answered. An entry with a cached address (the address cache, `loadHome`'s `cache`) connects at once with a 1 s timeout; discovery runs only when an entry has none or a cached address fails, so a stale one still reads as `connecting` until discovery has had its say. If discovery can't find the device either, it shows as disconnected at once rather than waiting on the same address again; the backoff still retries. A cached port other than 8009 marks a group, since devices always listen on 8009.
 - Per socket: `CONNECT` to `receiver-0`, receiver `GET_STATUS`, multizone `GET_STATUS` (a group's members; on a device's own port, the device alone, by its current name), then whatever the device pushes. A running app with the media namespace gets a `CONNECT` and media `GET_STATUS` on its `transportId`, as Home Assistant does. A device's `PING` is answered with `PONG`; a socket silent for three heartbeats (15 s), or without a receiver status 10 s after connecting, is closed and the detail says which.
 - A dropped socket reconnects with backoff (1 s doubling to 60 s) at whatever address discovery last gave. The drop starts one shared `resolve()` at once (a group's address changes with its leader); while anything stays down or missing, that one discovery repeats at 1, 5 and 15 minutes, then hourly, as the relocator does, never once per socket. `refresh()` re-asks every open socket and nudges the discovery, which also finds devices when nothing was found at start.
 - The part is `connecting` until every device has answered or failed, then `connected` while any is up; `detail` names the ones down. A payload of a known type the schema rejects is an `anomaly`, never thrown.
-- State (`CastSnapshot`, by mDNS id): app, `idle` (no app, or Backdrop's `isIdleScreen`), `standby`, volume (unrounded), muted, `volumeControl`, player state, title, artist; groups carry `members` and `leader`; devices carry `groups`, and `playingVia` when they show a playing group's media because their own is empty (Home Assistant's model, not yet seen live).
+- State (`CastSnapshot`, by mDNS id): `form` (`speaker`, `display` or `tv`, from `castForm(model)`; none for a model it doesn't know; the address cache keeps the model), app, `idle` (no app, or Backdrop's `isIdleScreen`), `standby`, volume (unrounded), muted, `volumeControl`, player state, title, artist; groups carry `members` and `leader`; devices carry `groups`, and `playingVia` when they show a playing group's media because their own is empty (Home Assistant's model, not yet seen live).
 - Names: a device's `name` in the snapshot is its own, from discovery's `fn` or its own multizone status (the same text on all six live devices, 2026-10-13), so a rename in the Google Home app shows once the device answers, even when every address came from the cache and discovery never ran; the config's name is only the placeholder until then. A group's multizone status lists its members, not itself, so a group's new name shows at the next discovery.
 - Writes, on the object `cast()` returns (`CastActions`), over the sockets it already holds, never a second connection. A target is a name (any case) or a castId; volume is 0 to 1, as the snapshot's. `setVolume`, `setMuted` (receiver `SET_VOLUME`; a group's goes to the group's socket; per device, levels and mutes each at most 30 a minute, the newest waiting one winning; one device's lane never waits on another's) and `stop` (receiver `STOP` of the running app; nothing when idle). Each request waits 10 s for its reply and a refusal (`LAUNCH_ERROR`, `LOAD_FAILED`, …) rejects, naming it.
-- `announce(target, clip, { volume?, timeoutMs? })`: `clip` is `{ url, type? }` or `{ bytes, type }`, bytes served through `serve` (`serveClip` from `@khalido/home/cast/serve`, passed to `cast()`). It reads the receiver status (and a Default Media Receiver's media status), for a group re-runs discovery first and reconnects if the leader moved, sets the volume if given and unmutes a muted target (as two requests: a `SET_VOLUME` takes a level or a mute, not both), launches the Default Media Receiver (`CC1AD845`), `LOAD`s the clip and waits for its media session to go `IDLE` with `FINISHED` (60 s plus the clip's length when the device reports it, or `timeoutMs`). Then, always: what the Default Media Receiver was playing is loaded again at its `currentTime`, an idle device gets `STOP`, then the volume and mute (a group's member by member, through each member's own socket, from the group's multizone status). Another app (Spotify, YouTube) is interrupted, as Google's own announcements do, and the result names it in `notRestored`. It returns `{ played, why?, restored, notRestored }` and throws only before anything changed (an unknown target, a socket down).
+- `announce(target, clip, { volume?, timeoutMs? })`: `clip` is `{ url, type? }` or `{ bytes, type }`, bytes served through `serve` (`serveClip` from `@khalido/home/cast/serve`, passed to `cast()`). It reads the receiver status (and a Default Media Receiver's media status), for a group re-runs discovery first and reconnects if the leader moved, sets the volume if given and unmutes a muted target (as two requests: a `SET_VOLUME` takes a level or a mute, not both), launches the Default Media Receiver (`CC1AD845`), `LOAD`s the clip and waits for its media session to go `IDLE` with `FINISHED` (60 s plus the clip's length when the device reports it, or `timeoutMs`). Then, always: what the Default Media Receiver was playing is loaded again at its `currentTime`, an idle device gets `STOP`, then the volume and mute (a group's member by member, through each member's own socket, from the group's multizone status). Another app (Spotify, YouTube) is interrupted, as Google's own announcements do, and the result names it in `notRestored`. It returns `{ played, why?, restored, notRestored }` and throws only before anything changed (an unknown target, a socket down). A clip gets 15 s to reach `PLAYING`, then the name of its type goes in the failure, since a device that can't play it took 35-44 s to say so; a receiver error sooner carries its reason and code. `timeoutMs` replaces both waits. `announceAll(targets, clip, options)` does several at once, one result per device, an unreachable target its own `played: false`; a group and one of its members would clash, untried.
 - `serveClip(bytes, type, { host?, signal? })` (`node:http`, Node-only like `tls.ts`): an address of this machine on the target's network (else the first non-internal IPv4), a random port and an unguessable path, `Content-Type` and `Content-Length`; the whole body to every GET and HEAD (a `Range` probe gets a full 200, which HTTP allows), so a player that probes before it fetches still gets the clip. It closes on `close()`, which `announce` calls once the clip has played, when `signal` aborts, or after 60 s. Not yet seen live: how the Default Media Receiver fetches, and the macOS local-network prompt the first serve may raise.
-- CLI: `home cast announce --to <name> (--say "<text>" | --file <path>) [--volume 0-100]`, `home cast volume <name> <0-100>`, `home cast mute <name> on|off`, `home cast stop <name>`. `--say` runs `say -o <tmp>.m4a --file-format=m4af --data-format=aac` (without the data format, m4af holds uncompressed PCM), serves it as `audio/mp4` and deletes the file. The library never runs `say`.
+- CLI: `home cast announce --to <name> [--to <name>…] (--say "<text>" | --file <path>) [--volume 0-100]`, `home cast volume <name> <0-100>`, `home cast mute <name> on|off`, `home cast stop <name>`. `--say` runs `say -o <tmp>.m4a --file-format=m4af --data-format=aac` (without the data format, m4af holds uncompressed PCM), serves it as `audio/mp4` and deletes the file. The library never runs `say`.
 - Config: one entry per device or group, `{ "connector": "cast", "name": "…", "castId": "…" }`, all folded into one `cast` integration; `home discover --write` fills them and refreshes a renamed entry's `name` (the same `castId` with a new `fn`), printed as `renamed`. No host: discovery gives every address.
 
 ## Protocol
@@ -26,7 +26,9 @@ CastV2 is TLS to port 8009 (a group: its own port), carrying length-prefixed pro
 - **Groups.** A group is its own mDNS entry, at its leader's address on a high port, and presents **its leader's certificate**. Multizone status on the group's port lists the members (by `deviceId`, the same dashed id) with their volumes; on a device's own port it lists only that device, so membership is read from group sockets only. TXT `rm` does not mark membership. `GET_CASTING_GROUPS` is refused.
 - **Receiver status**: hubs and the Chromecast Ultra run Backdrop (`E8C28D3C`) with `isIdleScreen: true`; the speakers report no application; the TV Streamer reports `isStandBy: true`, `isActiveInput: false` and a `fixed` volume; the Ultra's volume is `attenuation`.
 - No device sent a `PING` in 12 s of listening, so our 5 s ping is what keeps the socket's silence check honest.
-- Not seen yet: media status (nothing was playing), a group playing, a leader change, member changes, and Node's `tls` (no Node caller yet).
+- Media status first seen live 2026-11-09 (Bun 1.4.4): a paused title and artist on a TV.
+- **First announcements, 2026-11-09, from a Pi on 0.1.1.** MP3 played on two audio-only speakers and two displays, 7-8 s each, the clip fetched from the Pi's LAN address, idle and volume restored. A 24 kHz mono WAV played on the displays and failed on both audio-only speakers, "the clip stopped: ERROR" after 35-44 s. One WAV format tried: use MP3 or AAC.
+- Not seen yet: a group playing, a leader change, member changes, and Node's `tls` (no Node caller yet).
 
 ## TLS: verification off, the name checked
 

package/src/connectors/cast/index.ts

@@ -27,7 +27,8 @@ import {
 } from "./writes.ts";
 
 export type { CastConnect } from "./codec.ts";
-export type { CastDevice, CastSnapshot, Resolved } from "./state.ts";
+export { castForm } from "./state.ts";
+export type { CastDevice, CastForm, CastSnapshot, Resolved } from "./state.ts";
 export type {
   AnnounceResult,
   CastActions,
@@ -77,11 +78,17 @@ export type CastConfig = {
    * `host` and `port` (an address cache) an entry connects at once; discovery runs only when an entry has none, or a
    * cached address fails. A cached port other than 8009 is a group's (devices always listen on 8009).
    */
-  expect?: { castId: string; name: string; host?: string; port?: number }[];
+  expect?: {
+    castId: string;
+    name: string;
+    model?: string;
+    host?: string;
+    port?: number;
+  }[];
   /** Each address that connected and passed the certificate check, for an address cache; again with the device's new name when it reports a rename. `name` is the device's own, never a config's. */
   seen?: (
     id: string,
-    address: { host: string; port: number; name?: string },
+    address: { host: string; port: number; name?: string; model?: string },
   ) => void;
   clock?: Clock;
   /** Heartbeat interval; a socket silent for three of them is dropped. */
@@ -304,6 +311,7 @@ export function cast(
         host: d.host!,
         port: d.port!,
         name: named.has(id) ? d.name : undefined,
+        model: d.model,
       }); // a config's name never reaches the cache
       publish();
       void (async () => {
@@ -401,7 +409,8 @@ export function cast(
           // A cached address that fails is only stale: discover now and try where it answers, still "connecting".
           cached = false;
           await discover();
-          continue;
+          // Unless discovery can't find it: then the address is the one that just failed, and a second try only waits out the timeout. The backoff still retries.
+          if (!lastFound || lastFound.has(id)) continue;
         }
         const why = errorText(error);
         // A cached address the last discovery did not find says so, as a polling connector's does.
@@ -467,14 +476,19 @@ export function cast(
       report = update;
       running = signal;
       const expect = config.expect ?? [];
+      // A device with no model (a cache from before 0.1.2) goes through discovery once, or it would never get a `form`.
       const cached = expect.filter(
-        (e) => e.host !== undefined && e.port !== undefined,
+        (e) =>
+          e.host !== undefined &&
+          e.port !== undefined &&
+          (e.port !== 8009 || e.model !== undefined),
       );
       snapshot = found(
         snapshot,
         cached.map((e) => ({
           id: e.castId,
           name: e.name,
+          model: e.model,
           host: e.host!,
           port: e.port!,
           group: e.port !== 8009,

package/src/connectors/cast/schemas.ts

@@ -43,6 +43,7 @@ export const MediaStatus = z.looseObject({
         mediaSessionId: z.number().optional(),
         playerState: z.string().optional(), // "PLAYING" | "PAUSED" | "BUFFERING" | "IDLE"
         idleReason: z.string().optional(), // "FINISHED" | "CANCELLED" | "INTERRUPTED" | "ERROR"
+        detailedErrorCode: z.number().optional(),
         currentTime: z.number().optional(), // seconds into the media
         media: z
           .looseObject({

package/src/connectors/cast/serve.ts

@@ -15,10 +15,20 @@ const ipv4 = (a: string) =>
 const network = (address: string, netmask: string) =>
   ipv4(address) - (ipv4(address) % (2 ** 32 - ipv4(netmask)));
 
+type NetworkAddress = {
+  family: string;
+  address: string;
+  netmask: string;
+  internal: boolean;
+};
+
 /** This machine's IPv4 on the subnet that holds `host`, or with no host, its first non-internal IPv4. */
 export function lanAddress(
   host?: string,
-  interfaces = networkInterfaces(),
+  interfaces: Record<
+    string,
+    NetworkAddress[] | undefined
+  > = networkInterfaces(),
 ): string {
   const all = Object.values(interfaces)
     .flatMap((list) => list ?? [])

package/src/connectors/cast/state.ts

@@ -1,5 +1,15 @@
 import type { CastPayload } from "./schemas.ts";
 
+/** What a device is for, read from its model name; a model it doesn't know has none. A group is `kind: "group"`. */
+export type CastForm = "speaker" | "display" | "tv";
+export function castForm(model?: string): CastForm | undefined {
+  if (!model) return undefined;
+  if (/hub|tablet|display/i.test(model)) return "display";
+  if (/audio|speaker|mini|google home/i.test(model)) return "speaker";
+  if (/chromecast|streamer|\btv\b/i.test(model)) return "tv";
+  return undefined;
+}
+
 /** A Cast device or group as found by discovery: what `resolve` returns for each. */
 export type Resolved = {
   id: string;
@@ -18,6 +28,7 @@ export type CastDevice = {
   id: string;
   name: string;
   model?: string;
+  form?: CastForm; // devices: speaker, display or tv, when the model is one it knows
   kind: "device" | "group";
   host?: string;
   port?: number;
@@ -63,6 +74,7 @@ export function found(
       id,
       name: e.name,
       model: e.model,
+      form: kind === "device" ? castForm(e.model) : undefined,
       kind,
       host: e.host,
       port: e.port,

package/src/connectors/cast/tls.ts

@@ -18,7 +18,7 @@ export const tlsConnect: CastConnect = ({
   host,
   port,
   signal,
-  timeoutMs = 10_000,
+  timeoutMs = 3000,
 }) =>
   new Promise<CastChannel>((resolve, reject) => {
     const socket = connect({ host, port, rejectUnauthorized: false });