From 4a356333d1db0a407302ee6b68e90b313de21b81 Mon Sep 17 00:00:00 2001 From: Breadway Date: Sat, 15 Aug 2026 21:39:24 +0800 Subject: [PATCH 1/3] Ecosystem platform pass: bakery identity, v0.7.1 pins, BOS keybinds README and packaging/ now describe bakery (CI + ISO bake) as canonical instead of the old pacman package.yml flow. Pin bread-theme and bread-utils to bread-ecosystem v0.7.1; rev-pin bread-screenshots because that crate is not in the tag. Update the essential-keybinds guide to match the BOS skel (nautilus, lock, breadshot). --- Cargo.lock | 14 +++++++------- Cargo.toml | 15 +++++++-------- README.md | 4 ++-- .../02-essential-keybinds/content.md | 9 ++++++++- packaging/README.md | 9 +++++++++ 5 files changed, 33 insertions(+), 18 deletions(-) create mode 100644 packaging/README.md diff --git a/Cargo.lock b/Cargo.lock index 184cc74..e376161 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -35,17 +35,17 @@ 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-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,8 +55,8 @@ 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 = [ "dirs", "serde", @@ -67,7 +67,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 +82,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", diff --git a/Cargo.toml b/Cargo.toml index c6a6b5f..4e7ddf7 100644 --- a/Cargo.toml +++ b/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"] } +# 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" diff --git a/README.md b/README.md index 0938dd0..2e54855 100644 --- a/README.md +++ b/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,4 @@ 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`). diff --git a/content/getting-started/02-essential-keybinds/content.md b/content/getting-started/02-essential-keybinds/content.md index b5955ba..7063367 100644 --- a/content/getting-started/02-essential-keybinds/content.md +++ b/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 diff --git a/packaging/README.md b/packaging/README.md new file mode 100644 index 0000000..2c69413 --- /dev/null +++ b/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. From 3634edef0dc48fb9482f3cc258c8af27e59c0d26 Mon Sep 17 00:00:00 2001 From: Breadway Date: Sat, 15 Aug 2026 22:03:30 +0800 Subject: [PATCH 2/3] Track AGENTS.md --- .gitignore | 1 - AGENTS.md | 23 +++++++++++++++++++++++ 2 files changed, 23 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md diff --git a/.gitignore b/.gitignore index 8e81b3f..7379fb9 100644 --- a/.gitignore +++ b/.gitignore @@ -40,4 +40,3 @@ logs/ .claude/ # Local hygiene notes (not for commit) -CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..ee1101f --- /dev/null +++ b/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/` or `fix/` 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. From c9445fadccf4bc523a6fd3fed6da104f3588fc2d Mon Sep 17 00:00:00 2001 From: Breadway Date: Sat, 15 Aug 2026 22:16:30 +0800 Subject: [PATCH 3/3] 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. --- Cargo.lock | 12 ++++++++++++ Cargo.toml | 2 +- EVENTS.md | 42 ++++++++++++++++++++++++++++++++++++++++++ README.md | 5 +++++ src/services/breadd.rs | 23 ++++++++++++++++++++--- src/ui/window.rs | 12 ++++++++++-- 6 files changed, 90 insertions(+), 6 deletions(-) create mode 100644 EVENTS.md diff --git a/Cargo.lock b/Cargo.lock index e376161..454a88a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -42,6 +42,17 @@ dependencies = [ "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" @@ -58,6 +69,7 @@ name = "bread-utils" 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", diff --git a/Cargo.toml b/Cargo.toml index 4e7ddf7..d94305b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -17,7 +17,7 @@ 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.7.1", features = ["toml"] } +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. diff --git a/EVENTS.md b/EVENTS.md new file mode 100644 index 0000000..6bdd1c8 --- /dev/null +++ b/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. diff --git a/README.md b/README.md index 2e54855..dd4a036 100644 --- a/README.md +++ b/README.md @@ -13,3 +13,8 @@ cargo build --release ## Packaging / releasing 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). diff --git a/src/services/breadd.rs b/src/services/breadd.rs index a7c06d0..d6f51df 100644 --- a/src/services/breadd.rs +++ b/src/services/breadd.rs @@ -1,6 +1,23 @@ -//! Maps a `--suggest ` 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, diff --git a/src/ui/window.rs b/src/ui/window.rs index dc6fb12..10a7839 100644 --- a/src/ui/window.rs +++ b/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