Fix wording, docs and style inconsistencies per audit of 0139564

docs/antigravity-protocol.md

@@ -22,7 +22,7 @@ There is no flag for a system prompt or MCP servers, so byre hands them over as
 - `plugin.json`: `{"name": "byre"}`.
 - `rules/AGENTS.md`: always-on guidance. `rules/notes.md` uses `trigger: always_on` frontmatter. The CLI cuts each rule file at 24,000 bytes, so longer guidance or notes must be refused before launch.
 - `mcp_config.json`: one entry per server, with a Streamable HTTP `url` or a stdio `command` and `args`. The CLI namespaces plugin servers as `<plugin>_<server>`, so byre's own server is `byre_byre`.
-- `hooks.json`: handlers keyed by hook event, each a command that reads the hook's JSON from stdin and prints its reply, with a `timeout` in seconds (default 30). Flat events (`SessionStart`, `PreInvocation`, `PostInvocation`, `Stop`) list handlers directly; tool events (`PreToolUse`, `PostToolUse`) wrap them in groups, `[{"matcher": "*", "hooks": [...]}]`, where `matcher` is a regex on the tool name.
+- `hooks.json`: one top-level object named `byre`, holding handlers keyed by hook event, each a command that reads the hook's JSON from stdin and prints its reply, with a `timeout` in seconds (default 30). Flat events (`SessionStart`, `PreInvocation`, `PostInvocation`, `Stop`) list handlers directly; tool events (`PreToolUse`, `PostToolUse`) wrap them in groups, `[{"matcher": "*", "hooks": [...]}]`, where `matcher` is a regex on the tool name.
 
 ## The session's listener
 

docs/claude-protocol.md

@@ -10,7 +10,7 @@ claude --output-format stream-json --input-format stream-json --verbose \
   --permission-mode bypassPermissions --allow-dangerously-skip-permissions \
   --settings '{"attribution":{"commit":"","pr":""}}' \
   --mcp-config '{"mcpServers":{"byre":{"type":"sdk","name":"byre","alwaysLoad":true}}}' \
-  [--model M] [--effort E] [--session-id=ID] [--resume=SESSION_ID] [--resume-session-at=UUID] [--fork-session]
+  [--model M] [--effort E] [--append-system-prompt GUIDANCE] [--session-id=ID] [--resume=SESSION_ID] [--resume-session-at=UUID] [--fork-session]
 ```
 
 - No `--print`; stream-json input implies non-interactive.
@@ -39,7 +39,7 @@ Either side sends `{"type":"control_request","request_id":ID,"request":{"subtype
 
 Host → CLI:
 
-- `initialize` must be first. It carries hook registrations: `{"hooks":{"Stop":[{"matcher":null,"hookCallbackIds":["hook_0"],"timeout":<seconds>}],...}}`. Without `timeout` the CLI abandons a hook callback after its default; the timer is a JavaScript `setTimeout`, so values past about 24 days (2^31 ms) fire at once.
+- `initialize` must be first. It carries hook registrations: `{"hooks":{"Stop":[{"matcher":"","hookCallbackIds":["hook_0"],"timeout":<seconds>}],...}}`. Without `timeout` the CLI abandons a hook callback after its default; the timer is a JavaScript `setTimeout`, so values past about 24 days (2^31 ms) fire at once.
 - `interrupt` ends the current turn; the turn's `result` follows almost immediately and a running Bash tool is killed. The session stays usable.
 - `set_model` (`{"subtype":"set_model","model":M}`) switches the running process's model for later turns.
 - `apply_flag_settings` (`{"subtype":"apply_flag_settings","settings":{"effortLevel":E}}`) switches its effort; `null` returns to the default. It answers success for any value, an unknown level included.

docs/operations.md

@@ -125,7 +125,7 @@ byre never signs with a key on the Mac it runs on: every git command it runs the
 - **Orion.** Orion ignores key events that carry only a Unicode string, so typing posts each ASCII character as its key code. Some apps list `confirm` but ignore it, Orion's address bar among them; send Return instead. `do JavaScript` needs Orion's Develop → "Allow JavaScript from Apple Events".
 - **Chrome.** Chrome refuses remote debugging on its default profile, so byre's Chrome is its own profile (`~/Library/Application Support/byre/chrome`), a separate Chrome beside any the human runs, and it keeps its logins: the human signs in there once. Chrome comes from `brew install --cask google-chrome`; macOS's "downloaded from the Internet" prompt on its first launch must be answered Open (or `osascript -e 'tell application "System Events" to tell process "CoreServicesUIAgent" to click button "Open" of window 1'`), and until it is, Chrome cannot accept debugging commands.
 - **Chrome's trust boundary.** Use Chrome's loopback debugging port with byre's separate persistent profile and Chrome's default browser-origin checks; never add `--remote-allow-origins=*`. Other local OS accounts can reach that debugger and control its logged-in sessions. This is an accepted risk on the personal Macs byre runs on, as is access to the app's local preview forwards; do not add account-isolating brokers for these listeners. Chrome must be launched with `--remote-debugging-port=0` so it records its port and browser WebSocket path in the profile’s `DevToolsActivePort` file. After switching from the pipe or fixed-port transport, quit the old byre-profile Chrome once so the next tool call can start it with that discovery file. The saved profile and logins stay in place.
-- **Permissions.** Agents' processes run as byre's descendants, so macOS privacy controls (TCC) hold byre responsible for them: the Screen Recording, Device Control and Data Access (macOS 27's name for Accessibility) and Automation grants in System Settings → Privacy & Security are byre's, made by clicking at the Mac's screen, and each app scripted for the first time asks for its own Automation grant. Without Device Control and Data Access an untrusted process just sees no windows and no menu bar. A Mac running a server lists byre twice: the server's helper, a bare executable shown by its file name `byre` with a terminal icon, and the app, `Byre` with its icon; `byre-hands` names the app when the app is among its ancestor processes, and the server otherwise. Device Control and Data Access can list byre switched off; only its switch being on counts. TCC keys grants on the signing identifier and team, and every build is signed with Developer ID, so grants carry over from build to build. On a client Mac the grants belong to byre's app; `NSAppleEventsUsageDescription` in `mac/Info.plist` is what lets macOS ask for the Automation grant. The Desktop, Documents, Downloads and iCloud Drive folders each ask for their own Files & Folders grant the first time a process byre is responsible for reads them. `byre-hands check` prints the grants of the process that runs it, listing each of those folders so their prompts come up during the check rather than mid-turn; the Server and Settings tabs run it.
+- **Permissions.** Agents' processes run as byre's descendants, so macOS privacy controls (TCC) hold byre responsible for them: the Screen Recording, Device Control and Data Access (macOS 27's name for Accessibility) and Automation grants in System Settings → Privacy & Security are byre's, made by clicking at the Mac's screen, and each app scripted for the first time asks for its own Automation grant. Without Device Control and Data Access an untrusted process just sees no windows and no menu bar. A Mac running a server lists byre twice in Device Control and Data Access and in Automation: the server's helper, a bare executable shown by its file name `byre` with a terminal icon, and the app, `Byre` with its icon; Screen Recording lists only `Byre`, and switching it on covers the server too. `byre-hands` names the app when the app is among its ancestor processes, and the server otherwise. Device Control and Data Access can list byre switched off; only its switch being on counts. TCC keys grants on the signing identifier and team, and every build is signed with Developer ID, so grants carry over from build to build. On a client Mac the grants belong to byre's app; `NSAppleEventsUsageDescription` in `mac/Info.plist` is what lets macOS ask for the Automation grant. The Desktop, Documents, Downloads and iCloud Drive folders each ask for their own Files & Folders grant the first time a process byre is responsible for reads them. `byre-hands check` prints the grants of the process that runs it, listing each of those folders so their prompts come up during the check rather than mid-turn; the Server and Settings tabs run it.
 
 ## Terminals