From 81fbc46e4ff8dfde697b1ade254fda545cd3e91e Mon Sep 17 00:00:00 2001 From: Breadway Date: Wed, 5 Aug 2026 09:28:27 +0800 Subject: [PATCH] Fix README CLI reference drift, correct stale module-sandboxing claim, document check-docs' current gaps README's CLI reference had drifted from Documentation.md exactly the way Workstream F exists to prevent: bread modules audit (Workstream D), bread hooks install-shell/install-git, and bread events --tree (Workstream B) were all documented in Documentation.md but missing here, since this section is hand-copied rather than generated or linked out. Also found and fixed while auditing: the Module system section still said modules "are not sandboxed" -- false since Workstreams D and G added opt-in capability-scoped, Landlock-sandboxed execution. Documented in CONTRIBUTING.md that check-docs (Workstream F, scoped down to a drift detector rather than a generator -- see api-schema.toml's header) is deliberately not yet wired into CI pending a separate review pass on the workflow-file change, and that its scope doesn't cover the CLI-reference-vs-README drift this commit just fixed by hand -- both previously tracked only in conversation history, not durably in the repo. --- CONTRIBUTING.md | 16 ++++++++++++++++ README.md | 22 ++++++++++++++++++---- 2 files changed, 34 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 754ff2c..2dac8b5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -85,6 +85,22 @@ Whenever you add, rename, or remove a `bread.*` Lua binding undocumented, stale in the schema, or missing a doc heading/row — if `api-schema.toml`, the code, and `Documentation.md` don't all agree. +`check-docs` is **not yet wired into CI** — it's a local, manually-run +check today, not an enforced gate. That's a deliberate, still-open gap +(not an oversight): CI pipeline changes get a separate review pass before +landing, same as any other workflow-file edit. Wiring `cargo run -p xtask +-- check-docs` into `dev-release.yml` (fail the build on drift) is the +natural next step whenever that review happens — until then, discipline +running it before committing is what keeps `api-schema.toml`, the code, +and `Documentation.md` in sync, not anything automatic. + +Also note `check-docs`'s scope: it covers `bread.*` Lua bindings and IPC +methods against `Documentation.md` only. It does not cover the `bread` +CLI's subcommands against `README.md`'s hand-written CLI reference — +that's a separate, currently-unguarded copy of information (see +`README.md`'s "CLI reference" section) and has drifted before for exactly +the same reason `Documentation.md` used to. + ## CI - `dev-release.yml` — triggered on push to `main`. diff --git a/README.md b/README.md index ebf18b4..4b9b267 100644 --- a/README.md +++ b/README.md @@ -215,6 +215,7 @@ bread events bread.device.* # Stream filtered events bread events --since 60 # Replay events from the last 60 seconds bread events --fields event,data # Limit output to specific fields bread events --json # Output raw JSON +bread events --tree # Render as a causality tree (caused_by) instead of a flat stream bread emit # Manually fire an event (for testing) # Profiles @@ -226,6 +227,11 @@ bread modules list # List installed modules and daemon status bread modules install /local/path # Install from a local module directory bread modules remove # Remove an installed module (--yes skips confirmation) bread modules info # Show full manifest and daemon status +bread modules audit # Scan a module's Lua source and suggest a [[permissions]] block + +# 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 ``` --- @@ -236,10 +242,18 @@ Modules are Lua files (or directories) installed to `~/.config/bread/modules/`. ### Installing modules -Modules install from a local directory only. Modules run with full -`bread.exec()` privileges and are **not** sandboxed, so to use a module -published on a git host, clone it yourself and review the Lua before -installing from the local checkout: +Modules install from a local directory only. By default a module runs +in-process with full, ungated `bread.exec()` privileges — the same trust +model as before — so to use a module published on a git host, clone it +yourself and review the Lua before installing from the local checkout. +A module can opt into a smaller, enforced footprint by declaring +`[[permissions]]` in its manifest: it then runs out-of-process under an +OS-level (Landlock) sandbox limited to exactly what it declared, with a +`bread` table that only exposes the granted namespaces. See +[Capability-scoped modules](Documentation.md#capability-scoped-modules-since-v15) and +[Out-of-process module sandboxing](Documentation.md#out-of-process-module-sandboxing-since-v16) +for the full permission taxonomy and what's enforced at the kernel level +versus what isn't yet. ```bash git clone https://github.com/someuser/bread-wifi ~/src/bread-wifi