Add capability-scoped module API (Workstream D)

ModuleManifest gains a structured [[permissions]] field (bread-shared's
new ModulePermission/PermissionKind, shared between bread-cli and breadd
so the two never drift on what a permission "type" string means).

breadd now gives every third-party module's Lua chunk a scoped _ENV
instead of the shared global table: load_scoped_lua_file builds a fresh
`bread` table containing only baseline bindings (event subscription,
timers, json, module/store, logging, and the pure-Lua sugar built on top
of those) plus whatever the manifest's permissions grant, with a
metatable __index falling back to the real globals for everything else
(stdlib, require/package - so require("bread.devices") keeps working,
since builtins load unscoped and their closures capture that environment
lexically regardless of the caller's). _G is explicitly rebound to the
scoped table itself to close the obvious escape hatch. A module with no
manifest, or a manifest with no permissions key, keeps full ambient
access unchanged (today's behavior) but is now tracked as `ungated` in
module status and surfaced by `bread doctor`. An explicit `permissions =
[]` is scoped for real but not flagged, since that's a deliberate
declaration.

Adds `bread modules audit <name>`: a best-effort text scan of a module's
.lua files suggesting a [[permissions]] block to paste into its manifest.

Converts examples/modules/cpu-temp-widget.lua into a directory module
with a worked bread.module.toml (fs.read + widget) as the reference
example. Documentation.md gets a new "Capability-scoped modules" section
covering the taxonomy, the require()/closure mechanism, and an explicit
note that path/bin scoping is recorded but not yet enforced per-call -
that's the out-of-process module sandboxing workstream this manifest
schema is laid down for. API_VERSION bumped 1.4.0 -> 1.5.0.

examples/modules/README.md

@@ -14,6 +14,22 @@ cp low-battery-warning.lua ~/.config/bread/modules/
 bread reload
 ```
 
+`cpu-temp-widget/` is a directory (not a flat file) with a `bread.module.toml`
+manifest declaring its `[[permissions]]` — see
+[Capability-scoped modules](../../Documentation.md#capability-scoped-modules-since-v15).
+Either copy the whole directory into `~/.config/bread/modules/`, or install it
+properly so the manifest travels with it:
+
+```sh
+bread modules install ./cpu-temp-widget
+bread reload
+```
+
+The other modules here are flat files with no manifest — they load exactly
+like today, with full, ungated `bread.*` access (`bread doctor` will note
+that). Run `bread modules audit <name>` on an installed one any time to get a
+suggested `[[permissions]]` block for its own `bread.module.toml`.
+
 ## Modules
 
 | File | What it does | Config needed |
@@ -22,7 +38,7 @@ bread reload
 | `pause-media-on-headphone-unplug.lua` | Runs `playerctl pause` when a headphone/earbud device disconnects. | none (needs `playerctl`) |
 | `dock-monitors.lua` | Applies a multi-monitor layout when an external display connects, reverts when removed. | edit output names/resolutions |
 | `active-window-widget.lua` | Shows the focused window next to the workspace pills in breadbar, via `bread.widget` + `bread.state.watch`. | none |
-| `cpu-temp-widget.lua` | Live CPU temperature readout in breadbar's stats area, via `bread.widget` + `bread.fs.read` on a timer. | edit `TEMP_PATH` for your hwmon layout |
+| `cpu-temp-widget/` | Live CPU temperature readout in breadbar's stats area, via `bread.widget` + `bread.fs.read` on a timer. Directory module with a `bread.module.toml` declaring `fs.read` + `widget` — the permission-manifest worked example. | edit `TEMP_PATH` for your hwmon layout |
 | `bluetooth-toggle-widget.lua` | One-click Bluetooth power toggle in breadbar's tray, via `bread.widget` + a click handler. | none |
 | `focus-mode-widget.lua` | Click-to-toggle "Focus" profile that mutes audio; a widget as an action launcher, not just a readout, and stays in sync with profile changes triggered elsewhere. | none (needs `wpctl`) |
 | `workflow-status-widget.lua` | Surfaces `bread.workflow.list()` in breadbar's tray — shows whichever workflow (e.g. `dock-workflow.lua`, below) is currently running or failed, hidden otherwise. | none |

examples/modules/cpu-temp-widget/bread.module.toml

@@ -0,0 +1,21 @@
+name = "cpu-temp-widget"
+version = "1.0.0"
+description = "Live CPU package temperature widget, read from hwmon sysfs"
+author = "bread"
+source = "local"
+installed_at = ""
+
+# This module only ever calls bread.fs.read (never .write) and
+# bread.widget.register/update — declaring exactly that is what makes
+# bread.exec, bread.bluetooth, bread.hyprland, bread.machine, bread.notify,
+# and bread.state all genuinely absent (nil) from its `bread` table at
+# runtime, rather than merely unused. `source`/`installed_at` above get
+# overwritten by `bread modules install`; they're placeholders for the
+# drop-in/copy-paste path.
+
+[[permissions]]
+type = "fs.read"
+path = "/sys/class/hwmon"
+
+[[permissions]]
+type = "widget"

examples/modules/cpu-temp-widget/init.lua

@@ -9,11 +9,20 @@
 -- flags when something's hot — no CSS, no guessing which class names the
 -- rendering app happens to define.
 --
--- Drop-in: copy into ~/.config/bread/modules/. TEMP_PATH is specific to
--- this machine (AMD, k10temp) — find yours with:
+-- Drop-in: copy the whole cpu-temp-widget/ directory into
+-- ~/.config/bread/modules/ (or `bread modules install path/to/this/dir`).
+-- TEMP_PATH is specific to this machine (AMD, k10temp) — find yours with:
 --   grep -l k10temp /sys/class/hwmon/hwmon*/name
 -- and adjust below; a missing/unreadable path just shows "—" rather than
 -- erroring, since bread.fs.read returns nil (not an error) for that case.
+--
+-- This is also the worked example for the capability-manifest permission
+-- system (Documentation.md's "Capability-scoped modules" section): see the
+-- sibling bread.module.toml. It declares exactly the two permissions this
+-- module actually uses — `fs.read` (bread.fs.read, read-only) and `widget`
+-- (bread.widget.register/update) — nothing else. If you install it that
+-- way, bread.exec/bread.bluetooth/bread.hyprland/etc. are all genuinely
+-- absent (nil) from this module's `bread` table, not just unused.
 
 local M = bread.module({ name = "cpu-temp-widget", version = "1.0.0" })