breadhelp/EVENTS.md

breadhelp — bread event integration

breadhelp is a standalone GTK help center: it works exactly the same with or without breadd running. When breadd is present, it publishes one event after the main window is actually shown. 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: help. Transport: bread-utils's bread_client module (feature bread-client) — breadhelp links it directly. Each emit is its own short-lived connection. Command verbs are only received while breadhelp listen is running — that process holds the bread.command.help.** subscription open.

Events published (bread.help.*)

Event	Data	When
bread.help.opened	{ "autostart": bool }	The main help window is presented (ApplicationWindow::present). autostart is true when that invocation was launched with --autostart.
bread.help.open.done	{}	bread.command.help.open was received and breadhelp was spawned. This is the command confirmation, not proof the window mapped — the spawned process is the same no-args invocation as SUPER+/.
bread.help.open.failed	{ "error": "<message>" }	bread.command.help.open was received but this binary could not be started.

Not emitted when:

• every-login --autostart builds a hidden window because onboarding is already done (silent autostart)
• first-run --autostart presents the main window on the day-zero wizard; the tour overlay starts after that wizard finishes (or is skipped). bread.help.opened is emitted for that first-run present.
• --onboard / --tour-event (tour only)
• --screenshot (capture, not a user-visible open)

Commands honored (bread.command.help.*)

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

Verb	Data	Effect
open	none	Same as running breadhelp with no flags: present the main help window (GApplication forwards to an already-running primary instance). Emits bread.help.open.done / .failed.

bread.spawn(function()
    bread.emit("bread.command.help.open")
    bread.wait("bread.help.open.done", { timeout = 5000 })
end)

Not implemented: extra verbs

There is no onboard / tour / suggest command verb. Those already exist as local CLI flags (--onboard, --tour-event, --suggest). If/when a bus verb maps to real extra behavior, add it then — do not stub one as a no-op 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 — the help center, tour, and screenshots are entirely unaffected.
• If breadd restarts, the command subscription reconnects automatically (BreadClient::subscribe's background thread has its own backoff loop); no restart of breadhelp listen is needed.
• If breadhelp listen is not running, commands are a graceful no-op at the bus (no subscriber). The CLI still works.