breadcrumbs/EVENTS.md

breadcrumbs — bread event integration

breadcrumbs is a standalone Wi-Fi state machine: it works exactly the same with or without breadd running. When breadd is present and the breadcrumbs watch daemon (or the systemd user service it installs) is up, breadcrumbs publishes events into the shared bread automation fabric and listens for a small set of commands. See the parent bread repo's Documentation.md — specifically its "Namespaces" and "Integrating a bread* app" sections — for the general convention this follows.

App id: crumbs. Transport: bread-utils's bread_client module (feature bread-client) — the watch process links it directly, since it's the long-running piece that both emits on real transitions and holds the command subscription open.

One-shot CLI invocations (breadcrumbs status, profile set, init, …) do not emit or subscribe on their own. A breadcrumbs profile set home while the watcher is running is picked up on the watcher's next tick (state is re-read every loop) and then published as bread.crumbs.profile.changed. If the watcher is not running, the CLI still switches the profile on disk — there is just nobody listening for bread.command.crumbs.*, and nobody emitting bread.crumbs.*.

Events published (bread.crumbs.*)

Event	Data	When
bread.crumbs.profile.changed	{ "from": "<name>", "to": "<name>" }	The watch loop observes that the persisted active profile is no longer the one it last acted on (CLI profile set, detect --apply, bread.command.crumbs.set_profile, or a time-of-day schedule switch). Not emitted on watcher start just because a profile is already selected.
bread.crumbs.health.changed	{ "profile": "<name>", "health": "<variant>", "ssid": <string or null>, "iface": <string or null>, "ip": <string or null>, "exit_node": "<string>", "tailscale": <variant or null> }	The watch loop's health classification changes — including the first observation after start, and the forced re-evaluation after a profile change. Not emitted on every poll tick while the classification stays the same.
bread.crumbs.network.changed	{ "from": <ssid or null>, "to": <ssid or null>, "profile": "<name>" }	The active SSID changed between watch-loop ticks. from is null on the first association observed after start (or after a profile switch).
bread.crumbs.tailscale.changed	{ "profile": "<name>", "state": <variant or null>, "exit_node": "<string>" }	The Tailscale health state (or its mere presence) changed between ticks. state is the TsHealth variant name or null when Tailscale isn't installed.
bread.crumbs.set_profile.done	{ "profile": "<name>" }	bread.command.crumbs.set_profile persisted the new profile.
bread.crumbs.set_profile.failed	{ "error": "<message>" }	bread.command.crumbs.set_profile was received but rejected (unknown profile, missing profile field, config unreadable).

health is the Rust enum variant name, not a prettier label:

Variant	Meaning
Up	Adapter present, internet reachable, Tailscale healthy if the profile requires it.
DownNoNet	No internet.
CaptivePortal	No internet and an HTTP response arrived that wasn't the 204 generate_204 returns — traffic is being intercepted (captive/guest portal). Needs a browser sign-in, not a reconnect.
DownTailscaleManual	Tailscale required but needs login / isn't installed — cannot auto-fix.
DownTailscaleOther	Tailscale required and unhealthy for some other (usually auto-recoverable) reason.
NoAdapter	No Wi-Fi interface.
UnknownProfile	Persisted profile name is not in the config.

ssid is the currently-associated SSID, or null when there isn't one (no adapter, not associated, unknown profile).

Commands honored (bread.command.crumbs.*)

These are only received while breadcrumbs watch / breadcrumbs.service is running. Publishing a command with no subscriber is a silent no-op — that is the documented bread convention, not a breadcrumbs bug.

Verb	Data	Effect
set_profile	{ "profile": "<name>" }	Persist <name> via the same state::set_profile path the CLI uses. Wakes the watch loop immediately so the new profile is classified (and recovered, if down) on the next tick rather than waiting out the current poll interval. Does not run flow::run on the command thread — that would race the watch loop. Emits bread.crumbs.set_profile.done/.failed.

Not implemented: extra verbs

There is no pin, select, scan, init, or other command verb. The CLI already covers those as synchronous one-shots (breadcrumbs init, breadcrumbs scan, …), and breadcrumbs has no "pinned network" concept to hang a bus verb on. If/when that changes, the corresponding bread.command.crumbs.* verb should be added at the same time, not stubbed out ahead of it.

Fail-safe behavior

• If breadd isn't installed or isn't running, emit is a silent no-op (BreadClient::emit never blocks or errors the caller) and the command subscription simply never receives anything — breadcrumbs' actual Wi-Fi / Tailscale / watch functionality is entirely unaffected either way.
• If breadd restarts, the command subscription reconnects automatically (BreadClient::subscribe's background thread has its own backoff loop); no restart of the breadcrumbs watcher is needed.
• If the breadcrumbs watcher is not running, commands are a graceful no-op at the bus (no subscriber) and no bread.crumbs.* events fire. The CLI still works.