breadsearch: emit bread.search.opened and bread.search.opened_result

Wire the GTK overlay to the bread event fabric via bread-utils
BreadClient (app id search). Fail-silent when breadd is down.
No command verbs — the overlay has no existing command surface.

.gitignore

@@ -29,6 +29,3 @@ logs/
 # Runtime files
 *.sock
 *.pid
-
-# Local hygiene notes (not for commit)
-CLAUDE.md

AGENTS.md

@@ -0,0 +1,50 @@
+# AGENTS.md — Repo hygiene
+
+Scope: this file covers *repo hygiene* — branching, remotes, CI — plus a
+short map of the binaries. It is not user-facing project documentation.
+
+This repo follows the branch/release workflow documented in `CONTRIBUTING.md`
+— read and follow it for any git, branch, or release work here (the
+single-trunk model, `feature/x`/`fix/x` branch naming, how RC tags work,
+etc). Don't improvise a different workflow. The short version: there is one
+long-lived branch, `main` — no `dev` or `beta` branch exists. `main`
+auto-publishes a dev-track build on every push. "Beta" and "stable" are both
+just tags, not branches: push a `vX.Y.Z-rc.N` tag to publish a beta-track
+build, push a plain `vX.Y.Z` tag to cut the signed stable release.
+"Freezing" for stabilization means pausing pushes to `main`, not moving a
+branch. This replaced an earlier three-branch (`dev`/`beta`/`main`) model
+after `main` was found to have silently rotted out of sync with `dev`/`beta`
+across most repos in this ecosystem.
+
+When starting work on a new feature, create branch `feature/<feature-name>`.
+When working on a bug or issue, create branch `fix/<issue you are fixing>`.
+
+## Remotes
+- `origin` — Forgejo (`git.breadway.dev` via Hestia, SSH) — authoritative.
+- `github` — GitHub mirror. Push both when publishing.
+
+## CI
+- `dev-release.yml` triggers on `push: branches: ['main']`.
+- `rc-release.yml` triggers on `vX.Y.Z-rc.N` tag pushes (beta track).
+- `release.yml` triggers on any other `v*` tag push (stable).
+  None of these run on plain commits or PRs beyond what's listed.
+
+## Architecture
+
+Two binaries + a shared lib:
+
+| Crate | Role |
+|---|---|
+| `breadsearch-shared` | XDG paths, config, IPC types, Unix-socket client |
+| `breadmill` | Daemon: walk → extract → chunk → embed → index; serves queries |
+| `breadsearch` | GTK4 layer-shell overlay: ranked document hits from breadmill |
+
+breadsearch is document/meaning search. breadbox is the app launcher. They
+are not the same overlay.
+
+`--screenshot` (`breadsearch/src/screenshot.rs`) captures the search panel
+through `bread-screenshots`; do not rewrite it just to retarget the crate pin.
+
+## Don't
+- Don't embed credentials in remote URLs — SSH or a credential helper only.
+- Don't rewrite `screenshot.rs` as part of pin/docs work.

Cargo.lock

@@ -181,11 +181,11 @@ dependencies = [
 
 [[package]]
 name = "bread-onnx"
-version = "0.3.0"
-source = "git+https://git.breadway.dev/Breadway/bread-ecosystem?tag=v0.3.0#8e82d2d833e992ce939a5b836f910ee109f2e939"
+version = "0.3.1"
+source = "git+https://git.breadway.dev/Breadway/bread-ecosystem?tag=v0.7.1#db2fa3c4b4c1e6933bc5cf62a236d05972fdc886"
 dependencies = [
  "anyhow",
- "bread-utils 0.3.0",
+ "bread-utils 0.3.1 (git+https://git.breadway.dev/Breadway/bread-ecosystem?tag=v0.7.1)",
  "hex",
  "ort",
  "sha2 0.10.9",
@@ -197,17 +197,28 @@ dependencies = [
 [[package]]
 name = "bread-screenshots"
 version = "0.3.1"
-source = "git+https://git.breadway.dev/Breadway/bread-ecosystem?branch=main#f86e299f4a0ea73ff485cd84923b986ddcc8242e"
+source = "git+https://git.breadway.dev/Breadway/bread-ecosystem?rev=69ce2d67a8de8a09c064aa9d7ff99b46656f0b1d#69ce2d67a8de8a09c064aa9d7ff99b46656f0b1d"
 dependencies = [
  "anyhow",
- "bread-utils 0.3.1",
+ "bread-utils 0.3.1 (git+https://git.breadway.dev/Breadway/bread-ecosystem?rev=69ce2d67a8de8a09c064aa9d7ff99b46656f0b1d)",
  "tracing",
 ]
 
+[[package]]
+name = "bread-shared"
+version = "0.7.0"
+source = "git+https://git.breadway.dev/Breadway/bread?tag=v0.7.0#22e34e2cf2202305d7960759dfccb54dc79f948b"
+dependencies = [
+ "dirs",
+ "serde",
+ "serde_json",
+ "toml 0.8.23",
+]
+
 [[package]]
 name = "bread-theme"
-version = "0.2.3"
-source = "git+https://github.com/Breadway/bread-ecosystem?tag=v0.2.10#17d1bb85801b9a8c195b64c02d288cd662c9c780"
+version = "0.3.1"
+source = "git+https://git.breadway.dev/Breadway/bread-ecosystem?tag=v0.7.1#db2fa3c4b4c1e6933bc5cf62a236d05972fdc886"
 dependencies = [
  "dirs",
  "gtk4",
@@ -217,9 +228,10 @@ dependencies = [
 
 [[package]]
 name = "bread-utils"
-version = "0.3.0"
-source = "git+https://git.breadway.dev/Breadway/bread-ecosystem?tag=v0.3.0#8e82d2d833e992ce939a5b836f910ee109f2e939"
+version = "0.3.1"
+source = "git+https://git.breadway.dev/Breadway/bread-ecosystem?tag=v0.7.1#db2fa3c4b4c1e6933bc5cf62a236d05972fdc886"
 dependencies = [
+ "bread-shared",
  "dirs",
  "serde",
  "serde_json",
@@ -228,7 +240,7 @@ dependencies = [
 [[package]]
 name = "bread-utils"
 version = "0.3.1"
-source = "git+https://git.breadway.dev/Breadway/bread-ecosystem?branch=main#f86e299f4a0ea73ff485cd84923b986ddcc8242e"
+source = "git+https://git.breadway.dev/Breadway/bread-ecosystem?rev=69ce2d67a8de8a09c064aa9d7ff99b46656f0b1d#69ce2d67a8de8a09c064aa9d7ff99b46656f0b1d"
 dependencies = [
  "dirs",
  "serde",
@@ -265,6 +277,7 @@ dependencies = [
  "anyhow",
  "bread-screenshots",
  "bread-theme",
+ "bread-utils 0.3.1 (git+https://git.breadway.dev/Breadway/bread-ecosystem?tag=v0.7.1)",
  "breadsearch-shared",
  "clap",
  "gtk4",

EVENTS.md

@@ -0,0 +1,36 @@
+# breadsearch — bread event integration
+
+breadsearch is a standalone document-search overlay: it works exactly the
+same with or without `breadd` running. When breadd *is* present, the
+`breadsearch` GTK overlay publishes events into the shared bread automation
+fabric. 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: **`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.
+
+## Events published (`bread.search.*`)
+
+| Event | Data | When |
+|-------|------|------|
+| `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. |
+
+## 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.
+
+## 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
+  overlay and breadmill's indexing/query path are entirely unaffected.

README.md

@@ -2,6 +2,8 @@
 
 Semantic document search for Bread OS. Type a concept — not a keyword — and get ranked hits from your documents.
 
+This is **not** [breadbox](https://git.breadway.dev/Breadway/breadbox). breadsearch is document/meaning search over your files; breadbox is the app launcher (fuzzy `.desktop` launch). They are separate overlays with separate binaries, sockets, and keybinds — even though the search panel was originally forked from breadbox's launcher UI.
+
 Two binaries in one Cargo workspace:
 
 - **breadmill** — background daemon. Walks configured directories, extracts text, chunks and embeds documents with [nomic-embed-text-v1.5](https://huggingface.co/nomic-ai/nomic-embed-text-v1.5) (768-dim ONNX), stores vectors in an HNSW index (usearch) backed by SQLite metadata, and serves queries over a Unix socket. Watches for filesystem changes and re-indexes incrementally.

breadmill/Cargo.toml

@@ -42,7 +42,7 @@ breadsearch-shared = { path = "../breadsearch-shared" }
 #   needed for the plain CPU path even in the npu build.
 ort = { version = "2.0.0-rc.12", default-features = false, features = ["std", "tracing", "download-binaries", "tls-native", "copy-dylibs", "api-23"] }
 tokenizers = "0"
-bread-onnx = { git = "https://git.breadway.dev/Breadway/bread-ecosystem", tag = "v0.3.0" }
+bread-onnx = { git = "https://git.breadway.dev/Breadway/bread-ecosystem", tag = "v0.7.1" }
 
 # Surfaces ort's own EP-registration tracing (e.g. a GPU EP silently failing to
 # register and falling back to CPU) as visible log output instead of nowhere.

breadsearch/Cargo.toml

@@ -10,9 +10,13 @@ path = "src/main.rs"
 
 [dependencies]
 breadsearch-shared = { path = "../breadsearch-shared" }
-bread-theme = { git = "https://github.com/Breadway/bread-ecosystem", tag = "v0.2.10", features = ["gtk"] }
+bread-theme = { git = "https://git.breadway.dev/Breadway/bread-ecosystem", tag = "v0.7.1", features = ["gtk"] }
+# Bread event fabric client — emit bread.search.* (fail-silent if breadd is down).
+bread-utils = { git = "https://git.breadway.dev/Breadway/bread-ecosystem", tag = "v0.7.1", features = ["bread-client"] }
 # Capture primitives for `--screenshot` mode — see src/screenshot.rs.
-bread-screenshots = { git = "https://git.breadway.dev/Breadway/bread-ecosystem", branch = "main" }
+# Not on tag v0.7.1 (crate landed after that tag). Rev, not branch=main.
+# v0.7.1 predates this crate; same rev siblings use.
+bread-screenshots = { git = "https://git.breadway.dev/Breadway/bread-ecosystem", rev = "69ce2d67a8de8a09c064aa9d7ff99b46656f0b1d" }
 gtk4 = { version = "0.11", features = ["v4_12"] }
 gtk4-layer-shell = "0.8"
 serde_json = "1"

breadsearch/src/bread_events.rs

@@ -0,0 +1,26 @@
+//! `bread.search.*` event integration — optional, non-blocking. See
+//! `EVENTS.md` at the repo root for the full contract. breadsearch works
+//! identically with or without breadd running; every call here is
+//! fire-and-forget (`BreadClient::emit` never blocks or errors this
+//! process) so a missing or restarting breadd never affects the overlay.
+
+use bread_utils::bread_client::BreadClient;
+
+/// This app's id in bread's sibling-app namespace registry
+/// (`bread_shared::apps::KNOWN_APPS`) — events publish as `bread.search.*`.
+pub const APP_ID: &str = "search";
+
+fn client() -> BreadClient {
+    BreadClient::connect(APP_ID)
+}
+
+pub fn emit_opened() {
+    client().emit("bread.search.opened", serde_json::json!({}));
+}
+
+pub fn emit_opened_result(path: &str) {
+    client().emit(
+        "bread.search.opened_result",
+        serde_json::json!({ "path": path }),
+    );
+}

breadsearch/src/main.rs

@@ -18,6 +18,7 @@ use gtk4::{
 };
 use gtk4_layer_shell::{Edge, KeyboardMode, Layer, LayerShell};
 
+mod bread_events;
 mod screenshot;
 
 // ---- Theming ----------------------------------------------------------------
@@ -193,6 +194,7 @@ fn open_file(path: &str) {
         .stdout(std::process::Stdio::null())
         .stderr(std::process::Stdio::null())
         .spawn();
+    bread_events::emit_opened_result(path);
 }
 
 fn open_folder(path: &str) {
@@ -206,6 +208,7 @@ fn open_folder(path: &str) {
         .stdout(std::process::Stdio::null())
         .stderr(std::process::Stdio::null())
         .spawn();
+    bread_events::emit_opened_result(path);
 }
 
 // ---- UI ---------------------------------------------------------------------
@@ -433,6 +436,7 @@ fn run_ui(screenshot_req: Option<screenshot::ScreenshotRequest>) {
             screenshot::dispatch(&window, req);
         }
 
+        window.connect_map(|_| bread_events::emit_opened());
         window.present();
         search.grab_focus();
     });