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