diff --git a/README.md b/README.md
index eb706d6..9b48f5f 100644
--- a/README.md
+++ b/README.md
@@ -237,6 +237,12 @@ bread modules audit <name>            # Scan a module's Lua source and suggest a
 # Hooks
 bread hooks install-shell [shell]     # Install precmd/preexec/chpwd shell hooks (auto-detects $SHELL)
 bread hooks install-git               # Install git hooks (post-commit/checkout/merge) in the current repo
+
+# Compositor integration
+bread init                            # Install breadbar's Hyprland layer-rule integration (shows a diff, asks to confirm)
+bread init --dry-run                  # Print the proposed diff only, change nothing
+bread init --yes                      # Skip the confirmation prompt (scripted/image builds)
+bread init --undo                     # Remove the previously installed integration
 ```
 
 ---
diff --git a/api-schema.toml b/api-schema.toml
index 8179c29..09b138d 100644
--- a/api-schema.toml
+++ b/api-schema.toml
@@ -608,3 +608,8 @@ since = "0.7"
 name = "doctor"
 kind = "cli_command"
 since = "0.7"
+
+[[entry]]
+name = "init"
+kind = "cli_command"
+since = "0.8"
diff --git a/bread-cli/src/hooks_shell.rs b/bread-cli/src/hooks_shell.rs
index 63b692a..4272c79 100644
--- a/bread-cli/src/hooks_shell.rs
+++ b/bread-cli/src/hooks_shell.rs
@@ -13,6 +13,20 @@
 //! user later doesn't want it, an rc-file edit is much harder to notice and
 //! undo than a printed snippet they chose to paste in.
 //!
+//! `bread init` (`init.rs`) looks like it breaks this rule — it does
+//! propose an edit to a user's own `hyprland.lua` — but it's a narrower,
+//! consent-gated exception, not a reversal of it. The difference is what's
+//! silent about the failure mode: a missing shell hook is invisible
+//! enrichment (no telemetry, nothing looks wrong), so leaving it to the
+//! user to paste in at their own pace is the right default. A missing
+//! compositor layer rule is not invisible — breadbar renders unblurred and
+//! with the wrong opacity, which reads as "this app is broken," not
+//! "optional feature not enabled," and there's no snippet a user could be
+//! expected to reverse-engineer for that. `init.rs` earns the edit by
+//! showing the exact diff, requiring explicit consent (prompt, `--yes`, or
+//! nothing at all without a TTY), backing up the file first, and shipping
+//! a real `--undo`. See `init.rs`'s module docs for the full rationale.
+//!
 //! # Why bread-emit, not `bread emit`
 //!
 //! The generated hooks shell out to the separate `bread-emit` binary