# `[2026-09-15]` ESPHome modernised for ha-dev; `kb` search tool for the personal Worldtree KB

## ESPHome on esh-docker-vm (commits `d1769ed`, `8073a6a`, `687c699`, `c659fa5`)

Container had been on 2025.8.2 since April — twelve releases behind — because
the image reference was **untagged**: docker pulled `latest` once at creation
and never again. Every current Everything Presence sensor failed
`esphome config` on it. Now pinned `2026.8.2`; all six sensors validate.

⚠ Pre-state was worse than "old": there was **no `cli-plugins` directory**, so
`docker compose` printed a help blurb and **exited 0** — a silent no-op a deploy
script cannot distinguish from success.

Three things the job surfaced that were not in the request:

- **The config dir was 538 MB, not the 3 KB reported.** `.esphome/platformio` is
  508 MB of toolchain, `.esphome/build` another 31 MB — both regenerable.
  Relocating as-asked would have inflated restic's `/opt/docker` source ~45x
  against its own ~12 MB budget. Both subtrees excluded in
  `/etc/restic/profiles.yaml`.
- **2026.8.2 deprecates the bare `USERNAME`/`PASSWORD` env names** and says they
  will stop working — i.e. a **silent auth loss** on some later bump, on a
  privileged host-network container that flashes firmware. Renamed.
- **Device Builder 1.0.0 ships remote-build ON by default** binding `0.0.0.0:6055`.
  ⚠⚠ **Two switches, only one closes the port**:
  `set_offloader_settings {remote_builds_enabled}` is the OUTBOUND half and
  leaves the receiver listening; `remote_build/set_settings {enabled}` is the
  receiver-side master switch. The one *named* like the master switch is not.
  Both set false; `ESPHOME_REMOTE_BUILD_HOST=127.0.0.1` kept as a backstop
  because the off state lives in one JSON file whose in-code default is `True`
  and whose store soft-recovers to defaults on a malformed blob.

⚠ I committed a false claim that mDNS advertisement was gone. It was not —
`helpers.dashboard_advertise` still announces `_esphomebuilder._tcp` at 6052.
Corrected in `c659fa5`.

## `kb` — direct search over the personal Worldtree KB (commit `68fa80f`)

`scripts/kb` + `scripts/kb-search.py`, on PATH as `~/.local/bin/kb`. ~0.9 s over
7,634 files, no tokens.

⭐ **The Worldtree HTTP API cannot answer a question about the operator's notes.**
`/search` there searches conversation MESSAGES; a note that plainly exists comes
back as a clean empty result with no error. Searching for `shrimp` returned 0 —
and so did `the` and `a`, which is the **only** reason the empty result was read
as an empty ACCOUNT rather than an empty KB.

Two measurements shaped the design: **7,492 of 7,634 notes are ingested library
material** (4,155 fiction chapters, 3,287 book sections, 50 papers) so NOTES and
LIBRARY are ranked separately; and only **137 notes carry a frontmatter
`summary:`**, so the description falls through three shapes.

⚠ Both of the tool's own bugs produced confident wrong output rather than
errors: deriving the word list from argv made a quoted multi-word query one
pattern (`kb "shrimp sous vide"` → "no match" for a note it had just found), and
resolving the payload from `dirname $0` broke the moment it was symlinked.