Document bread init: api-schema, README CLI reference, hooks_shell note

Registers 'init' as a cli_command in api-schema.toml and adds its
lines to README.md's CLI reference, keeping xtask check-docs clean.
Also adds a note to hooks_shell.rs's module header explaining why the
compositor case earns a consent-gated config edit that the shell-hook
module deliberately avoids, so the two don't read as contradicting
each other.

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
 ```
 
 ---

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"

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

bread-cli/src/main.rs

@@ -1,3 +1,4 @@
+mod init;
 mod hooks_git;
 mod hooks_shell;
 mod modules_mgmt;
@@ -99,6 +100,22 @@ enum Commands {
         #[arg(long)]
         json: bool,
     },
+    /// Install bread's Hyprland compositor layer-rule integration
+    /// (breadbar/breadbox blur, ignore_alpha, animation) into
+    /// ~/.config/hypr/hyprland.lua, with consent, a backup, and full undo.
+    /// See bread-cli/src/init.rs for the design rationale.
+    Init {
+        /// Print the proposed diff and change nothing
+        #[arg(long)]
+        dry_run: bool,
+        /// Skip the confirmation prompt (for scripted/image builds)
+        #[arg(long)]
+        yes: bool,
+        /// Remove the previously installed marked block instead of
+        /// installing it
+        #[arg(long)]
+        undo: bool,
+    },
 }
 
 #[derive(Subcommand, Debug)]
@@ -224,6 +241,9 @@ async fn main() -> Result<()> {
                 print_doctor(&socket).await?;
             }
         }
+        Commands::Init { dry_run, yes, undo } => {
+            init::run(dry_run, yes, undo)?;
+        }
     }
 
     Ok(())
@@ -691,6 +711,7 @@ async fn print_doctor(socket: &Path) -> Result<()> {
         println!();
         println!("  start the daemon:   systemctl --user start breadd");
         println!("  view logs:          journalctl --user -u breadd -f");
+        print_compositor_doctor_section();
         return Ok(());
     }
 
@@ -775,6 +796,20 @@ fn render_doctor(health: &Value) {
             }
         }
     }
+
+    print_compositor_doctor_section();
+}
+
+/// Compositor integration status — pure filesystem check, independent of
+/// the daemon, so it prints the same whether breadd is up or not. Reports
+/// only; `bread doctor` never installs anything (that's `bread init`'s
+/// job).
+fn print_compositor_doctor_section() {
+    println!();
+    println!("compositor");
+    for line in init::doctor_report(&init::hypr_dir()) {
+        println!("{line}");
+    }
 }
 
 fn config_directory() -> PathBuf {