Honor bread.command.search.open via breadsearch listen

EVENTS.md

@@ -10,8 +10,10 @@ convention this follows.
 App id: **`search`**. Transport: `bread-utils`'s `bread_client` module
 (feature `bread-client`) — the overlay links it directly. Each `emit` is
 its own short-lived connection (`BreadClient::emit` is fire-and-forget,
-the same stance as `bread-emit`). breadmill, the indexing daemon, does
-not talk to breadd.
+the same stance as `bread-emit`). Command verbs are only received while
+`breadsearch listen` is running — that process holds the
+`bread.command.search.**` subscription open. breadmill, the indexing
+daemon, does not talk to breadd.
 
 ## Events published (`bread.search.*`)
 
@@ -19,18 +21,42 @@ not talk to breadd.
 |-------|------|------|
 | `bread.search.opened` | `{}` | The overlay window maps (the search panel is shown). |
 | `bread.search.opened_result` | `{ "path": "<hit path>" }` | The user opens a hit — Enter / click opens the file, Ctrl+Enter reveals its folder. `path` is the hit's document path, not the parent folder. |
+| `bread.search.open.done` | `{}` | `bread.command.search.open` was received and `breadsearch` was spawned. This is the command confirmation, not proof the overlay mapped — the spawned process is the same PID-file toggle as a keybind. |
+| `bread.search.open.failed` | `{ "error": "<message>" }` | `bread.command.search.open` was received but this binary could not be started. |
 
 ## Commands honored (`bread.command.search.*`)
 
-None. The overlay is a short-lived toggle process with no existing command
-surface (no show/hide/query IPC beyond the PID-file toggle and breadmill's
-own query socket). Adding verbs would mean inventing a control plane that
-does not exist; if/when breadsearch grows one, the corresponding
-`bread.command.search.*` verbs should be added at the same time, not stubbed
-out ahead of it.
+These are only received while `breadsearch listen` is running. Publishing a
+command with no subscriber is a silent no-op — that is the documented
+bread convention, not a breadsearch bug.
+
+| Verb | Data | Effect |
+|------|------|--------|
+| `open` | none | Same as running `breadsearch` (PID-file toggle: show the overlay, or dismiss it if it is already up). Emits `bread.search.open.done` / `.failed`. |
+
+```lua
+bread.spawn(function()
+    bread.emit("bread.command.search.open")
+    bread.wait("bread.search.open.done", { timeout = 5000 })
+end)
+```
+
+### Not implemented: extra verbs
+
+There is no `query` / `close` / `reindex` command verb. breadmill already
+has its own query socket; inventing a bus query plane would be a new
+product surface. If/when that exists, add the corresponding
+`bread.command.search.*` verb at the same time, not stubbed 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) — breadsearch's
+  (`BreadClient::emit` never blocks or errors the caller) and the
+  command subscription simply never receives anything — breadsearch's
   overlay and breadmill's indexing/query path are entirely unaffected.
+- If breadd restarts, the command subscription reconnects automatically
+  (`BreadClient::subscribe`'s background thread has its own backoff
+  loop); no restart of `breadsearch listen` is needed.
+- If `breadsearch listen` is not running, commands are a graceful no-op at
+  the bus (no subscriber). The overlay CLI still works.