Emit bread.help.opened when the main window is shown

Fail-silent via bread-utils BreadClient (ecosystem v0.7.1, bread-client).
No command verbs. Silent autostart and screenshot mode do not emit.

.gitignore

@@ -40,4 +40,3 @@ logs/
 .claude/
 
 # Local hygiene notes (not for commit)
-CLAUDE.md

AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.md — Repo hygiene
+
+Scope: this file covers *repo hygiene* — branching, remotes, CI, cleanup. It is not project documentation.
+
+## Identity
+- breadhelp is a **bakery** product (`bakery.toml` + bakery CI + BOS ISO bake). It is not pacman-packaged.
+
+## Branch model
+- One long-lived branch: **`main`**. There is no separate `dev` or `beta` branch — those are bakery tracks, published from `main` and from tags. Follow `CONTRIBUTING.md`.
+- Short-lived work: `feature/<name>` or `fix/<name>` off `main`.
+
+## Remotes
+- `origin` — Forgejo on Hestia only (`ssh://git@100.66.238.26:2222/Breadway/breadhelp.git`), via Tailscale. No GitHub mirror, unlike most bread-ecosystem repos.
+
+## CI
+- `.forgejo/workflows/dev-release.yml` — push to `main` (bakery dev track).
+- `.forgejo/workflows/rc-release.yml` — `vX.Y.Z-rc.N` tags (bakery beta track).
+- `.forgejo/workflows/release.yml` — other `v*` tags (signed bakery stable).
+- There is no `package.yml` / pacman publish workflow.
+
+## Don't
+- Don't embed credentials in remote URLs — this repo already uses SSH, keep it that way.
+- Don't start a Tauri port — this stays GTK4.

Cargo.lock

@@ -35,17 +35,28 @@ checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
 [[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.3.1"
-source = "git+https://git.breadway.dev/Breadway/bread-ecosystem?branch=main#f86e299f4a0ea73ff485cd84923b986ddcc8242e"
+source = "git+https://git.breadway.dev/Breadway/bread-ecosystem?tag=v0.7.1#db2fa3c4b4c1e6933bc5cf62a236d05972fdc886"
 dependencies = [
  "dirs",
  "gtk4",
@@ -55,9 +66,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",
@@ -67,7 +79,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",
@@ -82,7 +94,7 @@ dependencies = [
  "async-channel",
  "bread-screenshots",
  "bread-theme",
- "bread-utils 0.3.0",
+ "bread-utils 0.3.1 (git+https://git.breadway.dev/Breadway/bread-ecosystem?tag=v0.7.1)",
  "gdk4",
  "glib",
  "gtk4",

Cargo.toml

@@ -9,18 +9,17 @@ gdk4 = "0.11"
 gtk4-layer-shell = "0.8"
 glib = "0.22"
 # Shared ecosystem theming — same generated stylesheet bos-settings/breadbar/
-# breadbox/breadpad load, so this looks like part of the same desktop. Pinned
-# to dev (not a tag) for the .title -> .page-title rename, which doesn't have
-# a tagged release yet.
-bread-theme = { git = "https://git.breadway.dev/Breadway/bread-ecosystem", branch = "main", features = ["gtk"] }
+# breadbox/breadpad load, so this looks like part of the same desktop.
+bread-theme = { git = "https://git.breadway.dev/Breadway/bread-ecosystem", tag = "v0.7.1", features = ["gtk"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 toml = "0.8"
 # Non-destructive state editing (mirrors bos-settings/src/config/mod.rs).
 toml_edit = "0.22"
 async-channel = "2"
-bread-utils = { git = "https://git.breadway.dev/Breadway/bread-ecosystem", tag = "v0.3.0", features = ["toml"] }
-# Capture primitives for `--screenshot` mode — see src/screenshot.rs. Not
-# tag-pinned like the deps above since it doesn't have a tagged release yet.
-bread-screenshots = { git = "https://git.breadway.dev/Breadway/bread-ecosystem", branch = "main" }
+bread-utils = { git = "https://git.breadway.dev/Breadway/bread-ecosystem", tag = "v0.7.1", features = ["toml", "bread-client"] }
+# Capture primitives for `--screenshot` mode — see src/screenshot.rs.
+# The crate is not in tag v0.7.1 (landed after that tag; no later
+# ecosystem tag includes it). Rev-pinned so this is not branch=main.
+bread-screenshots = { git = "https://git.breadway.dev/Breadway/bread-ecosystem", rev = "69ce2d67a8de8a09c064aa9d7ff99b46656f0b1d" }
 anyhow = "1"

EVENTS.md

@@ -0,0 +1,42 @@
+# 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. There is no long-running command
+subscription.
+
+## 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`. |
+
+Not emitted when:
+
+- every-login `--autostart` builds a hidden window because onboarding is
+  already done (silent autostart)
+- first-run `--autostart` starts the tour overlay without presenting the
+  main window
+- `--onboard` / `--tour-event` (tour only)
+- `--screenshot` (capture, not a user-visible open)
+
+## Commands honored (`bread.command.help.*`)
+
+None. Opening the help center, starting the tour, and applying one-click
+fixes already exist as local CLI / UI paths. There is no command
+subscription, and no verb is stubbed as a no-op. If breadhelp later grows
+a bus verb that maps to real behavior, add it then.
+
+## 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) — the help
+  center, tour, and screenshots are entirely unaffected.
+- There is no command subscription to reconnect.

README.md

@@ -2,7 +2,7 @@
 
 Onboarding and help center for [BOS (Bread Operating System)](https://git.breadway.dev/Breadway/bos) — GTK4, a searchable guide library, an interactive keybind viewer, a troubleshooting wizard with one-click fixes, and a live guided tour overlay that spotlights real on-screen bread\* apps (breadbar, breadbox, ...) instead of walking through a static wizard.
 
-Split out of the `bos` repo into its own repo so a breadhelp release doesn't require a BOS ISO release, and vice versa. Pacman-packaged (not bakery-managed) — see `packaging/README.md`.
+Split out of the `bos` repo into its own repo so a breadhelp release doesn't require a BOS ISO release, and vice versa. A [bakery](https://git.breadway.dev/Breadway/bread-ecosystem) product (`bakery.toml` + bakery CI) and baked into the BOS ISO — not pacman-packaged.
 
 ## Building
 
@@ -12,4 +12,9 @@ cargo build --release
 
 ## Packaging / releasing
 
-See `packaging/README.md`. In short: bump `Cargo.toml`'s version, tag `vX.Y.Z`, push the tag to `forgejo` — `.forgejo/workflows/package.yml` builds and publishes to the `[breadway]` pacman repo automatically.
+See `CONTRIBUTING.md` for the single-trunk + tag model. `main` publishes a bakery **dev** build; a `vX.Y.Z-rc.N` tag publishes **beta**; a `vX.Y.Z` tag publishes **stable**. The leftover `packaging/` tree is not a pacman source — bakery is canonical (see `packaging/README.md`).
+
+## bread event integration
+
+Works the same with or without `breadd`. When the main window is shown,
+breadhelp publishes `bread.help.opened`. See [EVENTS.md](EVENTS.md).

content/getting-started/02-essential-keybinds/content.md

@@ -13,9 +13,16 @@ nothing here is mandatory either, click around if you'd rather.
 ## Apps
 
 - [Show Keybind]super + space[/Show Keybind] opens the launcher (breadbox)
-- [Show Keybind]super + e[/Show Keybind] opens files
+- [Show Keybind]super + e[/Show Keybind] opens files (nautilus)
 - [Show Keybind]super + b[/Show Keybind] opens the browser
 - [Show Keybind]super + u[/Show Keybind] opens notes
+- [Show Keybind]super + l[/Show Keybind] locks the screen
+
+## Screenshots
+
+- [Show Keybind]super + shift + s[/Show Keybind] captures a region to a file (breadshot)
+- [Show Keybind]super + shift + c[/Show Keybind] captures a region to the clipboard (breadshot)
+- [Show Keybind]super + shift + p[/Show Keybind] captures the active screen to a file (breadshot)
 
 ## The full list
 

packaging/README.md

@@ -0,0 +1,9 @@
+# packaging/
+
+Leftover from the pacman era. breadhelp is bakery-managed now
+(`bakery.toml` plus `.forgejo/workflows/{dev-release,rc-release,release}.yml`)
+and is baked into the BOS ISO.
+
+`breadhelp.desktop` is still live: bakery CI copies it into the published
+artifact. There is no PKGBUILD and no `package.yml` — do not treat this
+directory as a pacman package source.

src/services/breadd.rs

@@ -1,6 +1,23 @@
-//! Maps a `--suggest <id>` payload (sent by a breadd Lua module, e.g.
-//! `breadhelp-suggest.lua` reacting to `bread.monitor.connected`) to Home
-//! tab banner text.
+//! Bread bus integration. `--suggest` banners stay local; `bread.help.*`
+//! emits are optional and fail-silent. See `EVENTS.md`.
+//!
+//! `BreadClient::emit` never blocks or errors this process — a missing or
+//! restarting breadd must not affect the help center itself.
+
+use bread_utils::bread_client::BreadClient;
+
+/// Sibling-app id in `bread_shared::apps::KNOWN_APPS`. Events publish as
+/// `bread.help.*`. There is no command subscription.
+pub const APP_ID: &str = "help";
+
+/// Fire-and-forget `bread.help.opened` after the main window is actually
+/// shown. Silent autostart (window built, not presented) does not call this.
+pub fn emit_opened(autostart: bool) {
+    BreadClient::connect(APP_ID).emit(
+        "bread.help.opened",
+        serde_json::json!({ "autostart": autostart }),
+    );
+}
 
 pub struct Suggestion {
     pub text: String,

src/ui/window.rs

@@ -63,7 +63,7 @@ pub fn present(app: &Application, action: Action) {
             // (i.e. breadhelp wasn't already running) — a background daemon
             // event shouldn't steal focus from whatever the user is doing.
             if just_built {
-                handle.window.present();
+                show_window(&handle.window, action.autostart);
             }
             return;
         }
@@ -77,11 +77,19 @@ pub fn present(app: &Application, action: Action) {
         }
         let silent_autostart = action.autostart && State::load().onboarding_completed();
         if !silent_autostart {
-            handle.window.present();
+            show_window(&handle.window, action.autostart);
         }
     });
 }
 
+/// Present the help window and publish `bread.help.opened`. Screenshot
+/// mode calls `window.present()` itself and must not go through here —
+/// that is capture, not a user-visible open.
+fn show_window(window: &ApplicationWindow, autostart: bool) {
+    window.present();
+    crate::services::breadd::emit_opened(autostart);
+}
+
 fn build(app: &Application) -> Handle {
     // First thing on every cold start: revert any keybind a previous,
     // crashed run may have left temporarily rebound mid tour-step (see