diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..3c0ac3f
--- /dev/null
+++ b/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.
diff --git a/Cargo.lock b/Cargo.lock
index e679363..b911012 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -197,10 +197,10 @@ dependencies = [
 [[package]]
 name = "bread-screenshots"
 version = "0.3.1"
-source = "git+https://git.breadway.dev/Breadway/bread-ecosystem?rev=f86e299f4a0ea73ff485cd84923b986ddcc8242e#f86e299f4a0ea73ff485cd84923b986ddcc8242e"
+source = "git+https://git.breadway.dev/Breadway/bread-ecosystem?rev=69ce2d67a8de8a09c064aa9d7ff99b46656f0b1d#69ce2d67a8de8a09c064aa9d7ff99b46656f0b1d"
 dependencies = [
  "anyhow",
- "bread-utils 0.3.1 (git+https://git.breadway.dev/Breadway/bread-ecosystem?rev=f86e299f4a0ea73ff485cd84923b986ddcc8242e)",
+ "bread-utils 0.3.1 (git+https://git.breadway.dev/Breadway/bread-ecosystem?rev=69ce2d67a8de8a09c064aa9d7ff99b46656f0b1d)",
  "tracing",
 ]
 
@@ -228,7 +228,7 @@ dependencies = [
 [[package]]
 name = "bread-utils"
 version = "0.3.1"
-source = "git+https://git.breadway.dev/Breadway/bread-ecosystem?rev=f86e299f4a0ea73ff485cd84923b986ddcc8242e#f86e299f4a0ea73ff485cd84923b986ddcc8242e"
+source = "git+https://git.breadway.dev/Breadway/bread-ecosystem?rev=69ce2d67a8de8a09c064aa9d7ff99b46656f0b1d#69ce2d67a8de8a09c064aa9d7ff99b46656f0b1d"
 dependencies = [
  "dirs",
  "serde",
diff --git a/breadsearch/Cargo.toml b/breadsearch/Cargo.toml
index 1d2cb0b..0d2e114 100644
--- a/breadsearch/Cargo.toml
+++ b/breadsearch/Cargo.toml
@@ -13,7 +13,8 @@ breadsearch-shared = { path = "../breadsearch-shared" }
 bread-theme = { git = "https://git.breadway.dev/Breadway/bread-ecosystem", tag = "v0.7.1", features = ["gtk"] }
 # Capture primitives for `--screenshot` mode — see src/screenshot.rs.
 # Not on tag v0.7.1 (crate landed after that tag). Rev, not branch=main.
-bread-screenshots = { git = "https://git.breadway.dev/Breadway/bread-ecosystem", rev = "f86e299f4a0ea73ff485cd84923b986ddcc8242e" }
+# 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"