Installation was six scripts each carrying its own copy of the container host's
IP, three that had to agree on IDENTITY_TOKEN, and every service URL typed by
hand with a port in it. Any one could be wrong, and the symptom was always the
same and always late: an image that boots fine and then can't reach something,
found after a 40-minute build and a reboot.
Two properties fix that class of bug:
- Nothing is written twice. No script in tools/ contains an IP, port or token.
- Anything derivable is derived. You give the subnet prefix once and one last
octet per host; every address and service URL is computed from those.
THE TWINNED PAIR. container_host.ip_last_octet 12 and llm_host 13 mean the
container host's OLLAMA_HOST *is* http://<prefix>.13:11434 — computed in the
same build, not typed into two files and kept in sync. Move the LLM host to .21
and the container host's Ollama URL follows; change the subnet and both halves
move along with every kiosk's URLs. Neither image can be built pointing at an
address the other isn't using. Both carry the same SMARTHOME_PAIR_ID (a hash of
the config's meaning, not its bytes) so two USB sticks can be checked against
each other later.
validate-config.py runs before every build and refuses to start on an error, so
a mistake costs seconds not an hour. It catches duplicate ports (including the
music_assistant/pantry_vision 8095 clash that Compose can't see because MA runs
network_mode:host — open decision #31), both hosts on one address, duplicate
hostnames across kiosks and audio endpoints, placeholder tokens (checked before
the length check, so padding "changeme" to 32 chars doesn't pass), a private key
pasted where the public one goes, and a kiosk pointed at a disabled service.
build-all.sh is the normal entry point — the images are a set that has to agree
with itself, so building one is the exception. It builds the core pair, every
kiosk, and every audio endpoint including both architectures (amd64 live-build
ISO and arm64 rpi-image-gen img are different toolchains, not one image).
The two new host ISOs install unattended with everything burnt in, including
service env files generated from derived values — which permanently removes the
class of bug that had chores.env shipping IDENTITY_URL=http://127.0.0.1:8097.
setup-container-host.sh and setup-llm-host.sh now read every config value as
${VAR:-default} so the images configure them without editing.
That also makes every ISO a credential: Wi-Fi PSK, tokens, MQTT and HA
credentials are readable by anyone holding the stick. .gitignore covers the
filled-in CoreSystemConfig.json and build-output/.
Tested: 43 config validation/derivation checks and 44 builder checks against the
real code paths with only `lb` stubbed — every generated env file, preseed,
network config, first-boot unit and build stamp is verified, including that a
port collision refuses the build before writing anything. No ISO has been built;
`lb build` needs live-build, root and a long fetch. tools/README.md says so.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two unchecked items from the README status list that were buildable in-repo
rather than blocked on hardware.
hosts/llm-host/ — Phase 3's LLM machine:
- Auto-detects gpu vs cpu tier (nvidia-smi must both exist AND succeed; a
leftover driver package on a machine whose card was pulled satisfies only
the first and would fail later at container start).
- Runs Ollama as a pinned container rather than curl|sh into a root shell,
matching how everything else here is deployed. Deliberately does NOT install
the GPU driver — the most hardware/kernel-specific step on that box.
- Sets OLLAMA_HOST=0.0.0.0 inside the container. Ollama binds loopback by
default, which in Docker means the published port forwards to nothing and
every caller sees a connection refused indistinguishable from "the host is
off" — and since every consumer here is built to tolerate exactly that, it
degrades silently. Same class of bug as chores' 127.0.0.1 env values.
- Takes a position on Ollama contention (open decision #4's resource half):
MAX_LOADED_MODELS=1 so a 14B text model and a vision model swap predictably
instead of thrashing VRAM or OOM-ing mid-request, NUM_PARALLEL=1 for
predictable Assist latency, KEEP_ALIVE=30m so a household that talks to
Assist a few times an hour isn't paying model-load cost every time.
- Documents that Ollama has NO authentication and its API can delete models,
not just generate — added to network-integration.md's port table, since the
network is the entire boundary.
docs/caldav-integration.md — Phase 8's notes:
- The four independent clients and their directions (digest-engine read-only,
chores' busy-check read-only, trash-calendar create-only under a UID-prefix
ownership invariant, HA's own bridge).
- Why they share one Nextcloud app password, and the two costs: rotation
touches three env files plus HA and fails quietly, and the read-only
invariant is a CODE property, not a permission boundary — an app password
can't be scoped read-only or per-calendar, so the server would not catch a
regression that started writing.
- The two traps worth knowing before debugging them: unexpanded recurrence
reporting a meeting on the day it was created, and CALDAV_VERIFY_TLS=false.
Neither has been run — no Debian machine, no GPU, no live Nextcloud. The script
is syntax-checked and its generated compose validated as YAML for both tiers;
that is the whole of the testing, and both READMEs say so.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Records the networking decision behind Phase 6b's arrival notifications so it
doesn't get re-derived later.
ntfy stays LAN-only: identity -> ntfy is a container-to-container call that never
reaches OPNsense, and remote delivery rides a WireGuard split tunnel routing only
the smart-home VLAN. No DMZ, no port forward, no certificates, no inter-VLAN rule.
Both alternatives were weighed and rejected, with reasons recorded:
- DMZ + port forward buys only "notifications without the VPN connected," at the
cost of a public listener, TLS upkeep, and mandatory ntfy auth — an exposed
topic leaks "the house is empty right now".
- DMZ + NAT reflection does avoid a new inter-VLAN rule (the smart-home VLAN's
existing outbound-WAN allow already covers traffic to your own public IP), but
makes a purely internal path depend on the ISP and external DNS being up, so
two devices metres apart stop talking during a WAN outage. CGNAT breaks it
outright, and the rule it avoids was the safe direction anyway.
New §2.1 covers the split tunnel itself, including the trap that motivated it:
AllowedIPs must be the actual VLAN prefix, never 192.168.0.0/16, which collides
with typical café/hotel LANs and breaks the phone's connectivity there. Plus
always-on VPN yes / lockdown no, and no DNS= so queries aren't pulled home.
The household uses no Apple devices, which removes the only forcing function for
exposure (ntfy's iOS app needs APNs and therefore an upstream relay). Open
decision #37 closes as a household decision; the Apple case is kept as a
footnote in case that ever changes.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Rides the same arrival transition the visit log is built from, so "arrived" has
exactly one definition in this service rather than two that could disagree.
- notify_on_arrival (default off) is the "if enabled" half: push me when someone
gets home. announce_arrivals (default ON) is a separate per-person opt-OUT of
being announced, for anyone who doesn't want their comings and goings
broadcast. The asymmetry is deliberate — if both defaulted off, ticking
"notify me" would look broken until everyone else opted in too.
- Per-person notify_topic falling back to NTFY_DEFAULT_TOPIC. Topics are
deduplicated, or a five-person household sharing one topic would get five
identical pushes per arrival. The arriver is never told about themselves;
subscribers who are away still are, since that's most of the point.
- The first sample after startup notifies nobody and establishes a baseline
instead — otherwise a restart after a gap would fire "X just got home" for
everyone already on the sofa. Costs one missed notification in that window.
- Face-recognition arrivals say "was just recognised at home", not "just got
home" — the signals aren't equally reliable and the reader should know which.
- Pushes are sent outside _db_lock and isolated from each other, so a hanging
ntfy can't stall request handling and one bad push can't swallow the rest.
- POST /people/<id>/test-notification, because the alternative way to find a
typo'd topic is to wait for someone to walk in and notice nothing happened.
identity itself never touches the WAN — it POSTs to the ntfy already in this
stack. Whether the push reaches a phone that's AWAY is a network question, and
docs/network-integration.md's existing answer (WireGuard in, never a
port-forward) applies unchanged; iOS can't do this locally at all, since ntfy's
iOS app needs APNs and therefore an upstream relay. Documented as a table.
Also fixes two pre-existing bugs found while wiring this up: chores' template
pointed IDENTITY_URL and NTFY_URL at 127.0.0.1, which inside that container is
the container itself. chores would have reached neither identity nor ntfy, and
done nothing at all — silently, since both paths fail soft by design. Deployed
chores.env files still carry the old values and need editing by hand.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Extends Phase 6's identity rather than adding a service — all of this is facts
about who someone is, already identity's job.
- admin.html/admin.js: manage people/guests, edit every field, prune, history,
access log. Deliberately not kiosk-shaped and not linked from any wall panel —
a panel anyone can walk up to shouldn't carry a "prune these people" button.
- Nicknames are an input alias only. /resolve accepts them; every payload also
carries speak_name (always the real name) and chores/ uses it for reminders.
A nickname colliding with anyone's name or nickname is refused; a spoken string
matching two people refuses with ambiguous_name rather than picking one.
- Visit history sampled from identity's own /presence. home:null writes nothing,
ever — an HA outage must not record a departure that didn't happen. Departures
need sustained absence (BLE flaps) and are stamped at the last time actually
seen. "With whom" is an interval-overlap query, not a second table.
- Pruning splits selecting from deleting: the filter fills the checkboxes, the
delete goes by explicit id, and the filter is never re-run at delete time.
- Device rights are an answer, never an action — identity stores grants and
answers GET /device-access; HA asks and HA acts. Deny is the default and the
only fallback. Grants can expire; every check is logged, denials included.
- Chore assignment prefers an assignee who's home but doesn't let an absent one
block the chore (CHORE_ASSIGNMENT_STRICT flips that). Litter still ignores
both exemption and assignment.
- Admin-added identifiers still enforce TRUSTED_ENTITY_PREFIXES; only the
"in range right now" check is relaxed, never the allowlist.
Resolves open decision #26; adds #34-37 for the new unknowns (DEPARTURE_GRACE_
SECONDS is untuned, the panel has never been opened in a browser).
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Phase 19: trash-calendar (Kennelbach ICS -> CalDAV) and transit (GTFS
departures + OpenTripPlanner-backed voice route planning, slow walking
speed assumed). Phase 20: Tapo camera integration via identity's new
Frigate face-recognition presence signal, and chores, a presence/
calendar-driven household task nudger ("I don't care who does it, as
long as it gets done") with a passive fairness tally, litter culprit
attribution, and per-person chore_exempt/chore_reminder_style settings
on identity.
Also: the HA integrations + hardware-monitoring catalogs, Music
Assistant wiring, docs/network-integration.md (OPNsense VLAN
segmentation, no WAN port-forwards), the ESPHome BLE-proxy firmware,
and RuView CSI-presence integration (github.com/ruvnet/ruview) with
household automations for sleep/distress/concurrent-vitals/bathroom-
occupancy — all flagged with their real unverified assumptions and
open decisions. Fixed two real port collisions surfaced while wiring
this in (OTP vs. zigbee2mqtt on 8080, Music Assistant vs. pantry-vision
on 8095).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01K6CrKjW3yVptUnjG35HjC1
identity/ (Phase 6, rewritten from the original Node-RED sketch): a
person <-> BLE-identifier registry built directly as a Python service.
Solves multi-phone (multiple identifiers per person), anti-spoofing
(only allowlisted IRK-resolved/fixed-tag entities are ever accepted as
registration candidates, never a raw or randomized MAC), device-less
people (a grandmother without a smartphone gets a no_device registration
plus a hand-operated home/away toggle, reported as "unknown" rather than
a false "away"), and anonymous guests (POST /register/guest, no name
needed). Every person gets an automatic profile picture from their most
recent registration photo. /presence also reports a best-effort room per
person as groundwork for an eventual floor-plan view (not built).
Registration is single-utterance voice ("register me as <name>") or a
touchscreen form; ambiguous/conflicting candidates never auto-commit.
hosts/door-panel/ (Phase 18, new host): structurally kitchen-display's
twin - one Sway workspace, one Chromium kiosk window - defaulting to
identity's weather+clothing/who's-home/groceries-running-low dashboard,
with voice registration as its actual purpose (mic on by default, unlike
every other host's opt-in).
hosts/kitchen-display/: adds opt-in voice satellite and a "Show
registration" screen pointed at identity's register.html, reusing the
same camera-equipped-endpoint registration flow.
pantry-vision/: adds GET /shopping-list (Grocy's own volatile/missing
products, reshaped) for the door panel's "running low" section.
setup-container-host.sh: wires ENABLE_IDENTITY (identity + identity-web,
published like pantry-vision since kiosk browsers call it directly, plus
a persistent SQLite/photos volume unlike pantry-vision's stateless
design) and fixes the HA_URL example to the host's real LAN IP (HA runs
network_mode: host, unreachable by container name - the same situation
Node-RED's own config already documents).
docs/: Phase 6 rewritten, Phase 18 added, hardware/software/guardrail/
open-decision entries throughout project-plan.md and README.md.
components.md gains RuView presence nodes (one per room), fixed BLE tags,
and 2 spare webcams, with the price estimate updated to match.
Nothing here has been run against real hardware, a real HA instance, or
real Private BLE Device entities - TRUSTED_ENTITY_PREFIXES above all
needs checking against a live instance before registration finds
anything. See identity/README.md and hosts/door-panel/README.md for the
itemized verification lists.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01K6CrKjW3yVptUnjG35HjC1
hosts/touch-panel/: cheap touch controllers sometimes report as an absolute-
position HID mouse instead of a real digitizer, which makes libinput hand
sway a type:pointer device instead of type:touch. Add a type:pointer
fallback (flat accel profile, no pointer acceleration, cursor hidden on
idle) so taps still work as single-touch clicks in that case, plus a udev
rule template (configs/udev/99-touchscreen-override.rules) to re-tag a
specific known device back to full wl_touch semantics once its USB vendor/
product ID is known. Documented in a new README section and reflected in
project-plan.md's hardware/guardrail/open-decision entries for Phase 16.
docs/components.md: replace the Lenovo ThinkSmart View pick for Loggia (a
locked-down Teams/Zoom appliance, not a general Linux box) with a cheap
all-in-one touchscreen PC, then supersede that with the Lenovo all-in-one
already on hand for that room — moved from Need to Have throughout. Also
adds a Need section: missing components broken into sub-parts (Sound
System, Voice Reciever) with real Amazon listings found via search.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01K6CrKjW3yVptUnjG35HjC1
hosts/touch-panel/: a touch-driven Sway kiosk with a full Spotify GUI client
(Flathub), a dedicated Home Assistant Chromium kiosk window, a general web
browser, an always-on eww touch dock for app switching, an on-screen keyboard
(wvkbd), and touchpanel-agent giving HA/the LLM the same MQTT-mediated control
the thin client has.
hosts/kitchen-display/ + pantry-vision/: a camera-vision grocery cataloguing
endpoint for the fridge/pantry. The kiosk's browser captures a photo via
getUserMedia and sends it to the new pantry-vision service, which asks an
Ollama vision model to identify the item and estimate shelf life; the
proposal is always human-confirmed before being written into Grocy stock.
The same display shows inventory sorted by soonest-to-expire and Grocy's
recipes.
Wires ENABLE_PANTRY_VISION into setup-container-host.sh and documents both
phases in docs/project-plan.md and README.md, matching this project's
existing per-host hardware/software/guardrail/open-decision conventions.
Nothing here has been run against real hardware, a real camera, or a real
Grocy/vision-model instance — see each new README's verification list.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01K6CrKjW3yVptUnjG35HjC1
Two additions:
- Thin client: an eww weather/clock overlay over the idle-gallery slideshow.
Time/date come from the local clock, weather from a new retained MQTT topic
(smarthome/weather/current) an HA automation has to publish — degrades to
clock-only if that never happens. idle-gallery.sh owns the overlay's
visibility, mirroring how fullscreen-watcher.sh already owns the
now-playing widget's.
- hosts/audio-endpoint/: headless, per-room-independent Spotify Connect
appliances for rooms without a thin client, no shared/synced stream. Two
build pipelines sharing one architecture-independent systemd
unit/wrapper: arm64 (Raspberry Pi + HiFiBerry Amp2) via rpi-image-gen
producing a real flashable .img, and amd64 (mini PC + USB DAC/amp) reusing
the thin client's own live-build toolchain stripped of its graphical/kiosk
stack. Both reuse the thin client's existing apt-first/documented-fallback
Spotify Connect install logic rather than reinventing it. rpi-image-gen's
exact config schema is flagged explicitly as unverified — no ARM build
environment was available to validate it against the real tool.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WgTwMqiho8DT6ue5S49WBP
Three additions to the thin-client/container-host stack:
- admin-canvas + admin-web (Phase 13): an on-demand display surface for the
sys-admin-llm, mirroring digest-engine/digest-web's write/read split but as
a small always-on token-gated write API instead of a scheduled job. New
"4:admin" thin-client workspace, MQTT button, and duplicated canvas-sdk with
stat/image/video/chart window kinds.
- ESPHome firmware for the Waveshare ESP32-S3-Touch-LCD-1.85C-V2 (Phase 14):
a voice satellite + round-display status screen, evaluated as a DIY
alternative to Home Assistant Voice PE. Media/cover-art always takes
priority over an idle weather/time/date cycle, with a voice-state
visualizer overlaid on top. On-device wake word (micro_wake_word) feeding
the existing Assist pipeline, per-room "media_player_entity_id" wiring
documented explicitly to avoid cross-room bleed. Validated with ESPHome's
own config validator; not yet flashed to real hardware.
- Capture-card ("receiver box") video source selection on the thin client: a
new "5:capture" workspace and HA select that dynamically enumerates
USB/PCIe capture cards (re-scanned periodically for hot-plug), launches
mpv against the chosen one, and unconditionally excludes the gesture-
control camera from the list to preserve its existing no-HA-entity
invariant.
Also fixes a pre-existing bug found along the way: digest-browser's pkill
pattern matched any --kiosk mpv/firefox process rather than its own, which
would have let the new admin-browser/capture-view scripts kill each other's
windows.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WgTwMqiho8DT6ue5S49WBP
Every generated document now goes through a second, independent Ollama call
(synth/counter_run.py) before anything is written to output/: it checks quotes,
figures, named theoretical connections, and cross-source correlations against
the exact context the original synthesis pass saw, dropping anything that
doesn't trace back to it. A quote the model claims is grounded also gets a
deterministic substring-search backstop, since that's the one claim type
checkable without trusting the verifying call's own word for it.
The verifier shares the same RCI-derived theoretical basis as the document
it's checking, not a neutral outside standard — its job is confirming the
underlying facts are real and the theory genuinely matches their structure,
not flagging correct Marxist analysis as unverifiable for being theoretical
rather than a bare fact.
Fails safe in one direction only: a document that can't be verified at all
(Ollama unreachable a second time) is kept but marked unverified, never
silently passed through unchecked and never blanked outright. A document that
fails entirely is replaced with an honest "withheld pending verification"
placeholder.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPD1RhBsjdFKFLpMCLiVT6
Implements both new subsystems from the project plan end to end:
- hosts/thin-client/: Debian live-build Sway kiosk image — greetd autologin,
wayvnc (replaces RDP, per open decision #1), thinclient-agent (HA MQTT
discovery + swaymsg control, the sole LLM-reachable surface), mpv/mpv-mpris,
spotifyd/Steam Link, minimal-chrome Firefox with uBlock Origin/SponsorBlock
preinstalled, a fullscreen-aware now-playing widget, persistent audio-output
selection, outbound RDP/VNC via Remmina, HA mobile-app text/pointer remote
control via ydotool, an optional opt-in gesture-control camera (MediaPipe
hand tracking, off by default at two independent gates), a maintenance-shell
keybind, a German default keymap, and an idle-timeout photo slideshow from a
new gallery SMB share on the container host.
- digest-engine/: quarter-daily LLM digest — email/Signal/Telegram/Discord/
WhatsApp ingestion (WhatsApp via a headful-Chromium bridge, opt-in, highest
risk), news (including RCI/marxist.com theoretical sources and a broad
mainstream/state-affiliated outlet list), financial indicators, flight/naval
traffic and an OPNsense Suricata-alerts summary as political-analysis
evidence, Grocy/CalDAV household ingestion, an evening-only recipe and
shopping-list suggestion from soon-to-expire stock, and a vendored
digest-canvas SDK (globe/window/glow) rendering compact and full views. A
digest that goes unviewed (no thin-client canvas display or voice playback)
is merged into the next run instead of being discarded, tracked via a
retained MQTT message on the shared broker.
Both are wired into hosts/container-host/scripts/setup-container-host.sh via
the existing ENABLE_X/X_BLOCK pattern, off by default. docs/project-plan.md and
README.md are updated to match; remaining open decisions and manual-
verification items are tracked in-repo (project-plan.md §4, digest-engine/
README.md, hosts/thin-client/README.md).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPD1RhBsjdFKFLpMCLiVT6
Amir Alexander Abdelbaki