@khalido/home 0.0.0-stage → 0.1.0

package/skills/draw-home/README.md

@@ -0,0 +1,26 @@
+# 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/`.
+
+| 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                                                              |
+| [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.
+
+## The casa-serra starting prompt (the author's, for the camera option)
+
+The casa-serra author's own starting prompt, kept here because its last paragraph is the working method this skill also uses: propose before building, checkpoints with a recording, nothing finished that KO did not choose. Swap the brackets for the home.
+
+> I want to build a scroll-driven landing page for [a house]. The idea: the page opens on a flat floor plan, like a sheet an architect prints. Black ink on paper, room names, dimensions. Nothing looks 3D. When the visitor scrolls, the walls rise out of the drawing, the camera comes down to the front door and walks through [the rooms you want, in order] at eye height. Each room stays a line drawing until the camera gets there, then the real materials sweep across it.
+>
+> What I care about: the floor plan is not a picture. It is the real 3D model, cut at about 1.2 m and seen from straight above through a very long lens. The drawing and the building are the same thing. The camera travels deep into the space, room after room; it does not orbit the building from outside. It should feel like [your level of ambition]: big rooms, real furniture, late afternoon light. three.js, GSAP ScrollTrigger and Lenis, plain files, no build step. Free CC0 materials for the textures.
+>
+> Before you write any code, propose the layout of the building with sizes I can picture, and the camera path stop by stop. Give me two or three directions to choose from and wait for my answer. Then build in checkpoints. First checkpoint only: the plan sheet, the walls rising, and the walk to the first room. Record it and show me before you go further.
+
+For a home with live state, the plan sheet is `plan.svg` from the config and the walk's stops are the rooms with devices; the camera option in `SKILL.md` says how the state is drawn at each stop.

package/skills/draw-home/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: draw-home
+description: Draw a simple, themeable SVG plan of a home from photos, a floor plan or a description, plus the rooms in home.jsonc (the home config) that place devices, so an app can show each device's live state on it. Use when asked to draw, trace or update a house plan or home view for @khalido/home. One home per run.
+---
+
+# Draw a home
+
+The library does not draw. This guide is for the coding agent that does: turn what the person has (a floor plan PDF or photo, phone photos of rooms, a sketch, a description) into a drawing plus its entries in the home config, private when they describe a real house:
+
+- `home.svg`: a plain plan, one group and one empty marker per room.
+- `home.jsonc`: the home config (`src/config.ts`, `home.schema.json`). This skill writes its `plan.svg` and `rooms`, and a device's `room` or `marker`; the connectors' fields (addresses, ids, key names) belong to whoever sets the device up. `checkPlan` checks the result.
+
+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.
+
+- **The plan first, at full resolution**: a builder's or renovation plan beats photos for layout. Photos settle names, doors and where devices sit.
+- **Unknown stays unknown.** A room the source leaves unlabelled gets a neutral id (`room-unnamed-a`) and a question to the person. No furniture, fittings, dimensions or decoration to make it look rich.
+- **Devices from the person or from the connectors** (`home discover`, Hue's room list), never guessed from a photo of a lamp.
+- **Not to scale is fine**; say so. If a plan is old, say the house as built may differ.
+
+## 2. Draw
+
+- 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.
+
+## 3. The contract (an app draws on this; keep it exact)
+
+1. Each room is `<g class="room" id="room-…" data-floor="…" data-name="…">` with its shape and label. Ids are lowercase, stable, never renamed once devices refer to them.
+2. Each room holds one empty `<g class="marker" id="marker-…" transform="translate(x,y)">` at its top-right inner corner. Apps draw state there at the origin and never move it.
+3. `currentColor` and low-alpha fills, so a page that inlines the SVG themes it; a `<style>` on `svg:root` colours it when opened alone; `prefers-color-scheme` for dark. One file, no external loads.
+4. A header comment: source, date, not to scale, the room table, and this contract. `role="img"` and an `aria-label` on the root.
+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.
+
+**Energy on the plan** (the numbers are the library's, the drawing and animation are the app's):
+
+- **Solar.** The Enphase device's `marker` in `home.jsonc` names a `<g class="marker" id="marker-…">` outside any room, where the array is drawn on the roof (the panels as a group of low-alpha rects, the marker at its top-right corner). The app glows the panels from `solarLevel(energyNow(…), capacityW)`: against the device's `capacityW` (rated watts, from the config, never guessed) when set, else against today's highest reading so far (`solarPeakTodayW`). The two scales mean different things, so the drawing says which ("of 6.6 kW" or "of today's peak"). The level is never clamped: above 1 is drawn as full and labelled as read. "No data" when `solarW` is undefined.
+- **Flow.** Lines run panels → house while `solarW` is above zero, and house ↔ grid from the outer wall to the plan's edge, animated in the direction of `energyNow.flow`: outward while `"exporting"`, inward while `"importing"`, still while `"balanced"` (the library's 20 W display band). The speed or density scales with `surplusW` when exporting and `gridW` when importing. "No data" (no animation, grey line) when `gridW` is undefined; never a last value shown as live.
+- Labels beside the lines come from the same object: "exporting 1.2 kW, earning 42 c/h" from `surplusW` and `surplusCentsPerHour`, never recomputed in the app.
+
+**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.
+
+## 4. home.jsonc
+
+```jsonc
+{
+  "$schema": "<path to home.schema.json>",
+  "plan": { "svg": "home.svg" },
+  "rooms": [
+    // id matches <g class="room" id="…">; hueRoom: the Hue room whose lights this room's marker shows, once known
+    {
+      "id": "room-living",
+      "name": "Living",
+      "floor": "ground",
+      "hueRoom": "<hue room id>",
+    },
+  ],
+  // devices: set `room` on one that already exists; adding a device is the connector's job, not this skill's
+}
+```
+
+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.
+
+## 5. Check before hand-over
+
+- [ ] Every room-table row is drawn or listed as left out; every room has a marker; ids match the config's `rooms`; `checkPlan` reports nothing and `home config check` runs clean (`test/config.test.ts` shows the SVG check).
+- [ ] Open it in a browser, light and dark, at 320 px and 900 px wide: labels readable, nothing overlaps, no scroll.
+- [ ] Side by side with the source plan: same rooms, same order, same doors.
+- [ ] **Review**: a second agent with fresh context gets the source, the room table and the SVG (not your report), checks each row, and reports `wrong`, `guessed`, `ok`. Open three of its findings yourself.
+- [ ] Private files stay private: a real `home.svg` and `home.jsonc` live beside the person's settings, never in this repo or any public one.
+
+Hand over: the two paths, the room table's open questions, and what could not be verified.

package/skills/use-home/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: use-home
+description: Use the `home` command and the @khalido/home library to see and run a home - lights, AC, solar, prices, weather, speakers, printers, household spending. Covers connecting (keys, addresses, discovery on macOS and Linux), reading safely, the JSON and exit codes, what each status means, and the rules for writes. Use when asked about the house ("is the AC on?", "what's solar doing?", "will it rain at pickup?"), when running a scheduled check of the home, or when setting `home` up on a new machine.
+---
+
+# Use home
+
+`home` reads the house from the machine it runs on: devices on the LAN directly, cloud services (Amber, Up, weather) over HTTPS. There is no server and no cloud of ours in between. Read freely; write only when a person asks.
+
+## 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.
+- **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.
+
+## Reading
+
+```sh
+home                          # every connector, one line each, energy now on top; exits 0
+home weather                  # one connector; exits 1 when it is not connected
+home weather --json | jq .blocks.today
+home up spend --json          # household spending this window, by category
+home --help                   # every command and verb
+```
+
+The contract (in `docs/cli.md`): stdout is data, stderr everything else. `--json` errors are `{"error", "code", "fix"}` on stderr; `fix` is the one command that resolves it. Exit 0 success (empty included), 1 a failure or a connector not connected, 2 a wrong command or argument.
+
+What a status means:
+
+| Status         | Meaning                                                                            | What to do                                        |
+| -------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `connected`    | read and current                                                                   | use it                                            |
+| `connecting`   | still starting (a 15 s cap in the CLI)                                             | wait, or run again                                |
+| `disconnected` | the device or service did not answer; the last good state is kept, with its `asOf` | say so; check the device is on and at its address |
+| `unavailable`  | stopped for good: a key rejected, a setting wrong                                  | the `detail` names it; fix the key or setting     |
+| `not set up`   | env names or a file missing (`needs` lists them)                                   | set them, or say what is needed                   |
+
+Weather: `blocks` holds morning, afternoon and evening for today and tomorrow in the home's time zone; `rainSoon` says when rain starts in the next two hours (needs the Google key). Energy: `now` in `home --json` is the one owner of solar, use, grid flow and cost per hour; never recompute it.
+
+## Connecting
+
+**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`).
+- 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.
+
+Copying a working `.env` (and the CA file) to another machine works: the keys are not tied to the machine.
+
+**A config instead of env**: `--config home.jsonc` or `HOME_CONFIG`. It names devices by identity, rooms and the location; secrets stay env names. `home config check` shows what it would set up and every problem, secrets only as set or unset.
+
+## Addresses
+
+- **Reserve them.** Give the Hue bridge, the Enphase gateway, the AC and the printers a DHCP reservation in the router. Then the config's or env's addresses stay right and discovery is only a fallback.
+- **Devices are matched by identity, not address**: Hue's bridge id, the Daikin's MAC, the gateway's serial, a Cast id. A device that moves is found again by discovery after failed reads; the detail says "moved from a to b".
+- **The address cache** (`~/.cache/home/addresses.json`, `home cache`, `home cache clear`) keeps what discovery found between runs.
+- `home discover` lists what answers on the network and which `home` supports; with a config, `home discover --write` updates moved addresses and new devices in it.
+
+## Discovery (mDNS and DNS-SD)
+
+Hue, Enphase, Cast and printers announce themselves over mDNS. `home` asks the system's own mDNS daemon rather than listening itself:
+
+- **macOS**: `dns-sd`, built in.
+- **Linux** (Raspberry Pi OS): `avahi-browse`. avahi-daemon runs by default; the command is a package: `sudo apt install avahi-utils`. Without it, discovery says "avahi-browse not found".
+- **Daikin** answers a UDP broadcast on port 30050, on both.
+
+If discovery finds nothing: the machine must be on the same network and subnet as the devices (not a guest network, not a separate VLAN), multicast must pass (no "multicast optimisation" or client isolation on the access point), and a firewall must allow mDNS (UDP 5353). `home probe` checks each device read-only at its address, with no keys.
+
+## From code
+
+```ts
+import { createHome, loadHome } from "@khalido/home";
+const home = createHome(loadHome(config, options));
+await home.start(signal); // runs until signal aborts
+home.part("weather")?.state?.blocks; // typed by name; never touches a device
+await home.refresh("daikin"); // read now; resolves when it has reported
+```
+
+`docs/using.md` covers wiring it into an app (Bun and Node). Automations ("if X then Y") belong in the app, not the library: the library gives the facts (`sunNow`, `rainSoon`, `dayBlocks`, `energyNow`) and the writes.
+
+## A scheduled check
+
+A routine that runs `home --json` periodically should: report what changed or looks wrong (a connector down, an anomaly, a token close to expiry, rain soon); stay silent when all is well; never write; never quote keys or addresses into a message.

package/src/cli/cache.ts

@@ -0,0 +1,29 @@
+// `home cache [clear]`: the addresses kept between runs, or delete them so the next run discovers afresh.
+import { rmSync } from "node:fs";
+import {
+  addresses,
+  CACHE_FILE,
+  type Options,
+  printJson,
+  usage,
+} from "./context.ts";
+
+export async function cacheCommand(
+  verb: string | undefined,
+  o: Options,
+): Promise<void> {
+  if (verb === "clear")
+    return (
+      rmSync(CACHE_FILE, { force: true }),
+      console.log(`deleted ${CACHE_FILE}`)
+    );
+  if (verb !== undefined) usage("usage: home cache [clear]");
+  const entries = addresses.cache.read();
+  if (o.json) return printJson(entries);
+  console.log(CACHE_FILE);
+  for (const [key, c] of Object.entries(entries))
+    console.log(
+      `  ${key}${c.name ? ` (${c.name})` : ""}: ${c.host}${c.port === undefined ? "" : `:${c.port}`} · seen ${c.seenAt}`,
+    );
+  if (!Object.keys(entries).length) console.log("  empty");
+}

package/src/cli/cast.ts

@@ -0,0 +1,172 @@
+// `home cast announce|volume|mute|stop …`: one write to a Cast device or group, by its name or castId. `announce` plays a
+// clip (macOS `say`, or a file) and puts back what was playing and the volume; another app it interrupts cannot be resumed, and it says so.
+import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { extname, join } from "node:path";
+import {
+  cast,
+  type CastSnapshot,
+  resolvedFrom,
+} from "../connectors/cast/index.ts";
+import { serveClip } from "../connectors/cast/serve.ts";
+import { tlsConnect } from "../connectors/cast/tls.ts";
+import { addressBook } from "../discover.ts";
+import { FINDERS } from "../finders.ts";
+import type { Part } from "../home.ts";
+import {
+  addresses,
+  expandHome,
+  fail,
+  printJson,
+  text,
+  usage,
+  type Verbs,
+} from "./context.ts";
+
+/** Every Cast device and group, read once: what `home status` and `home probe` run without a config. Cached addresses first; discovery when there are none or one fails. */
+export function castNow() {
+  const book = addressBook(addresses.cache);
+  const expect = Object.entries(book.entries()).flatMap(([key, c]) =>
+    key.startsWith("cast:") && c.port !== undefined
+      ? [
+          {
+            castId: key.slice(5),
+            name: c.name ?? key.slice(5),
+            host: c.host,
+            port: c.port,
+          },
+        ]
+      : [],
+  );
+  return cast({
+    resolve: async () => resolvedFrom(await FINDERS.cast()),
+    connect: tlsConnect,
+    expect,
+    seen: (id, a) => book.seen("cast", id, a),
+    serve: serveClip,
+  });
+}
+
+/** 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>,
+): Promise<T> {
+  const c = castNow();
+  const stop = new AbortController();
+  let last: Part<CastSnapshot> | undefined;
+  const running = c.run(stop.signal, (p) => (last = p));
+  try {
+    for (
+      const until = Date.now() + 10_000;
+      Date.now() < until && (last?.status ?? "connecting") === "connecting";
+    )
+      await Bun.sleep(50);
+    return await act(c);
+  } finally {
+    stop.abort();
+    await running;
+  }
+}
+
+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>';
+
+/** A 0–100 argument as the 0–1 a Cast device takes. */
+function percentLevel(value: string | undefined): number {
+  const n = Number(value);
+  if (value === undefined || value.trim() === "" || !(n >= 0 && n <= 100))
+    usage(CAST_USAGE);
+  return n / 100;
+}
+
+/** What a clip file plays as, by its extension; the Default Media Receiver plays these, not AIFF. */
+const AUDIO_TYPES: Record<string, string> = {
+  ".mp3": "audio/mpeg",
+  ".m4a": "audio/mp4",
+  ".mp4": "audio/mp4",
+  ".aac": "audio/aac",
+  ".wav": "audio/wav",
+  ".ogg": "audio/ogg",
+  ".flac": "audio/flac",
+};
+
+/** The options `home cast` takes, beyond the global ones. Strings stay strings: "007" is a name, not 7. */
+export const CAST_OPTIONS: [string, string, { type: unknown[] }?][] = [
+  [
+    "--to <name>",
+    "announce: the device or group, by name or castId",
+    { type: [String] },
+  ],
+  ["--say <text>", "announce: words spoken by macOS `say`", { type: [String] }],
+  ["--file <path>", "announce: an audio file to play", { type: [String] }],
+  ["--volume <0-100>", "announce: the volume for the clip"],
+];
+
+export const castVerbs: Verbs = {
+  async volume([name, value]) {
+    if (!name) usage(CAST_USAGE);
+    const level = percentLevel(value);
+    await withCast((c) => c.setVolume(name!, level));
+  },
+  async mute([name, value]) {
+    if (!name || (value !== "on" && value !== "off")) usage(CAST_USAGE);
+    await withCast((c) => c.setMuted(name!, value === "on"));
+  },
+  async stop([name]) {
+    if (!name) usage(CAST_USAGE);
+    await withCast((c) => c.stop(name!));
+  },
+  async announce(_, o) {
+    const [to, say, file] = [text(o.to), text(o.say), text(o.file)];
+    // 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(
+        (a, i) =>
+          a === f &&
+          (process.argv[i + 1] === undefined ||
+            process.argv[i + 1]!.startsWith("--")),
+      ),
+    );
+    if (bare) usage(CAST_USAGE);
+    if (!to || !say === !file) usage(CAST_USAGE);
+    const volume =
+      o.volume === undefined ? undefined : percentLevel(text(o.volume));
+    let type: string;
+    let bytes: Uint8Array;
+    if (file) {
+      type =
+        AUDIO_TYPES[extname(file).toLowerCase()] ??
+        fail(
+          `${file}: not a type the Default Media Receiver plays (${Object.keys(AUDIO_TYPES).join(" ")})`,
+        );
+      bytes = readFileSync(expandHome(file));
+    } else {
+      // AAC in an MP4 container, which the Default Media Receiver plays (say's default AIFF it does not). Without
+      // --data-format=aac, m4af holds uncompressed PCM (afinfo, macOS 27.0).
+      const tmp = join(tmpdir(), `home-say-${randomUUID()}.m4a`);
+      try {
+        const said = spawnSync(
+          "say",
+          ["-o", tmp, "--file-format=m4af", "--data-format=aac", say!],
+          { stdio: ["ignore", "ignore", "pipe"] },
+        );
+        if (said.error || said.status !== 0)
+          fail(`say: ${said.error?.message ?? said.stderr.toString().trim()}`);
+        bytes = readFileSync(tmp);
+      } finally {
+        rmSync(tmp, { force: true });
+      }
+      type = "audio/mp4";
+    }
+    const r = await withCast((c) =>
+      c.announce(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}`);
+  },
+};

package/src/cli/config.ts

@@ -0,0 +1,52 @@
+// `home config check [path]`: validate a home config and print what it would set up, secrets as set or unset by name.
+import { existsSync } from "node:fs";
+import { checkHome } from "../config.ts";
+import { manifestOf } from "../manifests.ts";
+import {
+  configPathOf,
+  env,
+  fromConfig,
+  type Options,
+  printJson,
+  readConfig,
+  usage,
+} from "./context.ts";
+
+export async function configCommand(
+  verb: string | undefined,
+  file: string | undefined,
+  o: Options,
+): Promise<void> {
+  const path = file ?? configPathOf(o);
+  if (verb !== "check" || !path)
+    usage(
+      "usage: home config check [path]   (or set HOME_CONFIG, or pass --config)",
+    );
+  const { config, setup, problems } = checkHome(readConfig(path!), env);
+  const files = [
+    ...Object.entries(config?.plan ?? {}).flatMap(([k, v]) =>
+      typeof v === "string" ? [[`plan.${k}`, v]] : [],
+    ),
+    ...setup.flatMap((s) =>
+      (manifestOf(s.name)?.files ?? [])
+        .filter((k) => typeof s.settings[k] === "string")
+        .map((k) => [`${s.from}.${k}`, s.settings[k] as string]),
+    ),
+  ];
+  for (const [field, p] of files)
+    if (!existsSync(fromConfig(path!, p!)))
+      problems.push(`${field}: no file ${p}`);
+  if (o.json) return printJson({ setup, problems });
+  for (const s of setup) {
+    const parts = [
+      `from ${s.from}`,
+      ...Object.entries(s.settings).map(([k, v]) => `${k} ${v}`),
+      ...Object.entries(s.secrets).map(([k, v]) => `${k} ${v}`),
+    ];
+    console.log(`${s.name.padEnd(9)}${parts.join(" · ")}`);
+  }
+  console.log(
+    problems.length ? problems.map((p) => `problem: ${p}`).join("\n") : "ok",
+  );
+  if (problems.length) process.exitCode = 1;
+}

package/src/cli/context.ts

@@ -0,0 +1,118 @@
+// What every `home` command shares: the shell's environment, the config path, the address cache, and how to fail.
+// src/cli/ is the one place in src/ that reads the environment (names in .env.example); the library takes parameters.
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import type { AddressCache, CachedAddress } from "../discover.ts";
+import { parseJsonc } from "../config.ts";
+import { isTimeZone } from "../clock.ts";
+import { fileCache } from "../finders.ts";
+
+export const env = process.env;
+
+/** What went wrong, coarsely, as `--json` errors carry it: `usage` exits 2, the rest 1. */
+export type ErrorCode = "usage" | "auth" | "network" | "error";
+
+/** An error `home` reports in one line, or as `{ error, code, fix }` under `--json`. `fix` is the one command that resolves it. */
+export class CliError extends Error {
+  constructor(
+    message: string,
+    readonly code: ErrorCode = "error",
+    readonly fix?: string,
+  ) {
+    super(message);
+  }
+}
+
+/** Stop the command. `status` catches it per integration, so one failing connector never hides the others. */
+export const fail = (
+  message: string,
+  code?: ErrorCode,
+  fix?: string,
+): never => {
+  throw new CliError(message, code, fix);
+};
+/** A wrong command, verb or argument: the usage line, exit 2. */
+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;
+  config?: string;
+  write?: string | true;
+  passes?: number | string;
+  to?: unknown;
+  say?: unknown;
+  file?: unknown;
+  volume?: number | string;
+};
+
+/** An option's text as typed: cac turns a number-like value into a number, and `type: [String]` into an array. */
+export const text = (v: unknown): string | undefined =>
+  v === undefined ? undefined : String(Array.isArray(v) ? v.at(-1) : v);
+
+/** `--write [path]`: undefined when absent, "" when bare (the config from --config or HOME_CONFIG), else the path. */
+export const writeTo = (o: Options) =>
+  o.write === undefined ? undefined : o.write === true ? "" : String(o.write);
+
+/** `~/` as the home folder: neither Bun's .env loading nor the shell (inside quotes) expands it. */
+export const expandHome = (p: string) => p.replace(/^~(?=\/)/, homedir());
+
+/** The home config (JSONC) from --config or HOME_CONFIG; without one, `status` and `probe` read env names. */
+export const configPathOf = (o: Options) => {
+  const p = o.config ?? env.HOME_CONFIG;
+  return p ? expandHome(p) : undefined;
+};
+
+/** A path from the config, against the config's folder; `~/` is the home folder. */
+export const fromConfig = (path: string, p: string) =>
+  resolve(dirname(path), expandHome(p));
+
+export const readConfig = (path: string): unknown =>
+  parseJsonc(readFileSync(path, "utf8"));
+
+/** The owner token's cache: written only by `home enphase login`, owner-only. */
+export const TOKEN_FILE = join(
+  homedir(),
+  ".config",
+  "home",
+  "enphase-token.json",
+);
+
+/** Where discovered addresses are kept between runs (`home cache`), owner-only. */
+export const CACHE_FILE = join(
+  env.XDG_CACHE_HOME || join(homedir(), ".cache"),
+  "home",
+  "addresses.json",
+);
+
+/** The file cache, written once as `home` exits, with the latest addresses. */
+export const addresses = (() => {
+  const file = fileCache(CACHE_FILE);
+  let pending: Record<string, CachedAddress> | undefined;
+  const cache: AddressCache = {
+    read: () => file.read(),
+    write: (entries) => void (pending = entries),
+  };
+  return { cache, flush: () => pending && file.write(pending) };
+})();
+
+/** HOME_TIMEZONE, the env form of the config's `location.timezone`; this machine's zone when unset. */
+export function homeTimeZone(): string | undefined {
+  const zone = env.HOME_TIMEZONE;
+  return zone === undefined || isTimeZone(zone)
+    ? zone
+    : fail(
+        `HOME_TIMEZONE: an IANA time zone, e.g. Australia/Sydney, not ${zone}`,
+      );
+}
+
+/** Print as JSON, two-space indented. */
+export const printJson = (value: unknown) =>
+  console.log(JSON.stringify(value, null, 2));
+
+/** A connector's verbs beyond its status (`home cast announce …`): each takes the words after the verb and the options. */
+export type Verbs = Record<
+  string,
+  (args: string[], o: Options) => Promise<unknown>
+>;