From 1011428cc7c06e5d9096382155363b2db45d1dc1 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 4 Jul 2026 11:50:57 +0200
Subject: [PATCH] docs(terminal-rendering): document plugin_install,
 commands_changed, compact_boundary rows
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The renderer dispatch section was missing entries for three system
subtypes that now have specific renderers (added in the preceding
commits on this branch). Update the row taxonomy table and the
numbered dispatch description to cover all four system-subtype
handlers (thinking_tokens was already documented; 1b–1e are new).
---
 docs/terminal-rendering.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/docs/terminal-rendering.md b/docs/terminal-rendering.md
index 6b060c76..6ad9da54 100644
--- a/docs/terminal-rendering.md
+++ b/docs/terminal-rendering.md
@@ -67,6 +67,10 @@ parent's negative pull.
 | `.tool-result-block.error` `<details>` | `Nl · headline` | red, body is text | long error `tool_result` (`is_error: true`); wrapper stripped | stream-json |
 | `.tool-use` | `⌁  task <id> started · <desc> [type]` | cyan | claude Task-tool subagent start (dead path — `Task` omitted from agent allow-list) | `renderTaskEvent` |
 | `.turn-end-ok` / `.turn-end-fail` / `.tool-result` | `⌁  task <id> ✓/✗/◌ <status> · <desc> · → <output_file>` | green / red / muted | claude Task-tool result (dead path for agents) | `renderTaskEvent` |
+| `.note` | `· ⚙ plugin install · loading…` or `✓ done` | muted | `system/plugin_install` (`status` = started/completed) | stream-json |
+| `.note` | `· ⚙ commands changed · N available` (expandable list of `/name` entries) | muted | `system/commands_changed` (slash-command set updated, usually post-plugin_install) | stream-json |
+| `.note` | `· ⚙ compact · <trigger> · <pre>→<post> tokens · <dur>` | muted | `system/compact_boundary` (compaction completed; metadata includes pre/post token counts, duration, trigger) | stream-json |
+| `.note` | `· ⚙ <subtype>` | muted | other `system` subtypes (context_window_exceeded, etc.) | stream-json catch-all |
 | `.note` | `· <text>` | muted | harness chatter | `LiveEvent::Note` |
 | `.note.stderr` | `! stderr: <line>` | amber/orange | stderr lines off claude | `LiveEvent::Note` (`text` starts `stderr:`) |
 | `.note.op` | `· operator: <text>` | mauve italic | operator-initiated notes (/cancel, /compact, /model, new-session) | `LiveEvent::Note` (`text` starts `operator:`) |
@@ -95,6 +99,19 @@ suffix, so the terminal degrades cleanly against older event shapes.
    while it's still the last one rendered (`nextElementSibling ==
    null`); any other event after it makes the next tick start a
    fresh row. Avoids a note-per-tick scrollback flood.
+1b. `system/plugin_install` → muted note `⚙ plugin install · loading…`
+   (on `started`) or `⚙ plugin install · ✓ done` (on `completed`).
+   Emitted in pairs: started fires before the plugin loads, completed
+   fires when it's ready. The `uuid` links the pair.
+1c. `system/commands_changed` → collapsible `.note` details row showing
+   the new slash-command count (`⚙ commands changed · N available`).
+   Expanding reveals each `/name` and its aliases. Fires after
+   `plugin_install` when a plugin registers new commands.
+1d. `system/compact_boundary` → muted note showing compaction summary:
+   `⚙ compact · <trigger> · <pre>→<post> tokens · <dur>`. Fields are
+   guarded individually — a missing field is silently omitted. Trigger
+   is `"manual"` (operator `/compact`) or `"auto"`.
+1e. Other `system/` subtypes → muted note `⚙ <subtype>`.
 2. `subtype == "task_started" | "task_notification"` →
    `renderTaskEvent` (subagent activity gets the `⌁` glyph).
 3. `type == "assistant"` → walk `message.content[]`: