docs: simplify sidebar and tasked-phases guidance

commit: 071b7987a95c3be4b88cf8ffa3df3ef23a76726a
author: brice · 2mo ago · 2026-08-05 13:34 UTC
parent: 545e6c1
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

5 files · +18 -64

M README.md +1 -1


@@ -888,7 +888,7 @@ Slash commands also work while the agent is busy. Non-destructive ones (`/help`,
888	888		\| `esc` \| Cancel the current turn (while busy); clear input (while idle). Two parsed bare `Esc` presses within 500 ms open `/session tree` only when the editor is idle and empty; dialogs, busy/queued work, and modified keys keep their existing precedence. \|
889	889		\| `ctrl+c` \| Clear the input and queue (while idle) or arm the exit hint (while busy). Press again within 2s to exit. Use `esc` to cancel a running turn. \|
890	890		\| `ctrl+d` \| Exit on empty input. \|
891		-	\| `ctrl+b` \| Toggle the right sidebar; hidden/narrow right-bar widgets fall back above the input within a bounded area and show an ellipsis when truncated. \|
	891	+	\| `ctrl+b` \| Toggle the right sidebar; hidden or narrow widgets use a bounded above-input fallback. \|
892	892		\| `ctrl+l` \| Redraw the screen. \|
893	893		\| `ctrl+v` \| Paste clipboard text into the focused chat, side chat, dialog, filter, or credential input. In the main chat, image clipboard content is attached to the next prompt when the platform exposes it (macOS pasteboard, Wayland `wl-paste`, or X11 `xclip`). On Linux, text uses `wl-paste`, `xclip`, or `xsel`; terminal-native bracketed paste remains available without those commands. \|
894	894		\| `ctrl+o` \| Expand or collapse long tool results (read, write, edit, bash, and lsp outputs over ~12 lines). \|


@@ -888,7 +888,7 @@ Slash commands also work while the agent is busy. Non-destructive ones (`/help`,
888		\| `esc` \| Cancel the current turn (while busy); clear input (while idle). Two parsed bare `Esc` presses within 500 ms open `/session tree` only when the editor is idle and empty; dialogs, busy/queued work, and modified keys keep their existing precedence. \|	888		\| `esc` \| Cancel the current turn (while busy); clear input (while idle). Two parsed bare `Esc` presses within 500 ms open `/session tree` only when the editor is idle and empty; dialogs, busy/queued work, and modified keys keep their existing precedence. \|
889		\| `ctrl+c` \| Clear the input and queue (while idle) or arm the exit hint (while busy). Press again within 2s to exit. Use `esc` to cancel a running turn. \|	889		\| `ctrl+c` \| Clear the input and queue (while idle) or arm the exit hint (while busy). Press again within 2s to exit. Use `esc` to cancel a running turn. \|
890		\| `ctrl+d` \| Exit on empty input. \|	890		\| `ctrl+d` \| Exit on empty input. \|
891	-	\| `ctrl+b` \| Toggle the right sidebar; hidden/narrow right-bar widgets fall back above the input within a bounded area and show an ellipsis when truncated. \|	891	+	\| `ctrl+b` \| Toggle the right sidebar; hidden or narrow widgets use a bounded above-input fallback. \|
892		\| `ctrl+l` \| Redraw the screen. \|	892		\| `ctrl+l` \| Redraw the screen. \|
893		\| `ctrl+v` \| Paste clipboard text into the focused chat, side chat, dialog, filter, or credential input. In the main chat, image clipboard content is attached to the next prompt when the platform exposes it (macOS pasteboard, Wayland `wl-paste`, or X11 `xclip`). On Linux, text uses `wl-paste`, `xclip`, or `xsel`; terminal-native bracketed paste remains available without those commands. \|	893		\| `ctrl+v` \| Paste clipboard text into the focused chat, side chat, dialog, filter, or credential input. In the main chat, image clipboard content is attached to the next prompt when the platform exposes it (macOS pasteboard, Wayland `wl-paste`, or X11 `xclip`). On Linux, text uses `wl-paste`, `xclip`, or `xsel`; terminal-native bracketed paste remains available without those commands. \|
894		\| `ctrl+o` \| Expand or collapse long tool results (read, write, edit, bash, and lsp outputs over ~12 lines). \|	894		\| `ctrl+o` \| Expand or collapse long tool results (read, write, edit, bash, and lsp outputs over ~12 lines). \|

M docs/extensions.md +4 -16


@@ -426,14 +426,10 @@ hint with these interactive-zot values:
426	426		- `"right_bar"` keeps the widget in a display-only side rail beside the
427	427		transcript when the terminal is wide enough.
428	428
429		-	The right bar is host-owned: it bounds width and height, orders widgets by
430		-	extension and ID, and truncates content that does not fit. On narrow terminals
431		-	it falls back automatically to `above_input`. In interactive zot, `Ctrl+B`
432		-	toggles the sidebar; while hidden, right-bar widgets use the same bounded
433		-	`above_input` fallback and show a truncation marker when the shared chrome
434		-	budget is exceeded. Empty or unknown positions retain the historical
435		-	`above_input` behavior so older extensions remain compatible. Use `open_panel`
436		-	when a widget needs interaction or navigation.
	429	+	The host owns right-bar layout: it orders widgets, bounds width and height,
	430	+	and truncates content. Narrow terminals and `Ctrl+B` use a bounded
	431	+	`above_input` fallback. Empty or unknown positions keep the historical
	432	+	`above_input` behavior. Use `open_panel` for interaction or navigation.
437	433
438	434		```json
439	435		{"type":"widget","id":"plan","position":"right_bar",

@@ -726,14 +722,6 @@ e.SetWidget("plan", ext.WidgetPositionRightBar, "Tasked phases", lines)
726	722		e.ClearWidget("plan")
727	723		```
728	724
729		-	`right_bar` widgets are display-only in the first version. The host renders
730		-	one muted separator beside the main pane, leaves one blank row below each
731		-	widget title, and does not add a second widget frame or top/bottom rules. In
732		-	interactive zot, `Ctrl+B` toggles the rail; hidden or narrow right-bar widgets
733		-	use a bounded `above_input` fallback with a truncation marker. Open an
734		-	extension panel for editing or keyboard navigation; clearing the last
735		-	right-bar widget removes the rail.
736		-
737	725		The SDK has four interceptor hooks, all optional:
738	726
739	727		```go

 - `"right_bar"` keeps the widget in a display-only side rail beside the
   transcript when the terminal is wide enough.
-The right bar is host-owned: it bounds width and height, orders widgets by
+The host owns right-bar layout: it orders widgets, bounds width and height,
-extension and ID, and truncates content that does not fit. On narrow terminals
+and truncates content. Narrow terminals and `Ctrl+B` use a bounded
-it falls back automatically to `above_input`. In interactive zot, `Ctrl+B`
+`above_input` fallback. Empty or unknown positions keep the historical
-toggles the sidebar; while hidden, right-bar widgets use the same bounded
+`above_input` behavior. Use `open_panel` for interaction or navigation.
-`above_input` fallback and show a truncation marker when the shared chrome
-budget is exceeded. Empty or unknown positions retain the historical
-`above_input` behavior so older extensions remain compatible. Use `open_panel`
-when a widget needs interaction or navigation.
 ```json
 {"type":"widget","id":"plan","position":"right_bar",
 e.ClearWidget("plan")
 ```
-`right_bar` widgets are display-only in the first version. The host renders
-one muted separator beside the main pane, leaves one blank row below each
-widget title, and does not add a second widget frame or top/bottom rules. In
-interactive zot, `Ctrl+B` toggles the rail; hidden or narrow right-bar widgets
-use a bounded `above_input` fallback with a truncation marker. Open an
-extension panel for editing or keyboard navigation; clearing the last
-right-bar widget removes the rail.
 The SDK has four interceptor hooks, all optional:
 ```go

M examples/extensions/tasked-phases/README.md +7 -21


@@ -18,12 +18,9 @@ set_current_phase set_task_checked set_phase_checked
18	18		clear
19	19		```
20	20
21		-	Successful mutations return one concise line such as `Checked task task-4
22		-	(p 1/2 \| t 3/4)`. `get_status` and `replace_plan` remain detailed when the
23		-	full state is useful. `set_task_checked` changes one task; `set_phase_checked`
24		-	intentionally changes every task in the selected phase. Repeated individual
25		-	checks in one model turn are sequential tool calls, not an automatic bulk
26		-	update.
	21	+	Successful mutations return one progress line; use `get_status` or
	22	+	`replace_plan` for details. `set_task_checked` changes one task;
	23	+	`set_phase_checked` changes every task in a phase.
27	24
28	25		## Build and run
29	26

@@ -70,18 +67,7 @@ as it is completed, and advance the current phase when work moves forward.
70	67		Completed phases and future phases are not repeated in every provider request;
71	68		use `get_status` or `/phases` when the full checklist is needed.
72	69
73		-	When a plan is stored, the extension automatically publishes a compact summary
74		-	through the host's generic `right_bar` widget position. Both the right-bar title
75		-	and the status bar use the short form `p done/total \| t done/total`; active plans
76		-	also show their phase and task checklist rows below the title, with one blank
77		-	row after the title. Phase rows use one leading space and bold phase names;
78		-	task rows use two leading spaces, and wrapped task text hangs under its task
79		-	label. The summary and rows are refreshed after every plan mutation and session
80		-	restore. Checklist markers use `[x]`, `[ ]`, and `[>]`; the host dims rows
81		-	outside the current phase.
82		-	Once every phase and task is complete, the persistent status and right-bar widget
83		-	are cleared. Use `get_status` or `/phases` for the complete checklist and current
84		-	task details. Spec text is deliberately excluded from persistent chrome. zot
85		-	keeps the summary beside the transcript on wide
86		-	terminals and automatically falls back to the normal above-input widget on
87		-	narrow terminals. The extension does not implement any terminal layout code.
	70	+	Active plans publish `p done/total \| t done/total` and checklist rows through
	71	+	`right_bar`. The host dims inactive phases, uses a bounded above-input fallback
	72	+	on narrow terminals or when `Ctrl+B` hides the rail, and clears the chrome when
	73	+	the plan is complete. Use `get_status` or `/phases` for full details.

 clear
 ```
-Successful mutations return one concise line such as `Checked task task-4
+Successful mutations return one progress line; use `get_status` or
-(p 1/2 | t 3/4)`. `get_status` and `replace_plan` remain detailed when the
+`replace_plan` for details. `set_task_checked` changes one task;
-full state is useful. `set_task_checked` changes one task; `set_phase_checked`
+`set_phase_checked` changes every task in a phase.
-intentionally changes every task in the selected phase. Repeated individual
-checks in one model turn are sequential tool calls, not an automatic bulk
-update.
 ## Build and run
 Completed phases and future phases are not repeated in every provider request;
 use `get_status` or `/phases` when the full checklist is needed.
-When a plan is stored, the extension automatically publishes a compact summary
+Active plans publish `p done/total | t done/total` and checklist rows through
-through the host's generic `right_bar` widget position. Both the right-bar title
+`right_bar`. The host dims inactive phases, uses a bounded above-input fallback
-and the status bar use the short form `p done/total | t done/total`; active plans
+on narrow terminals or when `Ctrl+B` hides the rail, and clears the chrome when
-also show their phase and task checklist rows below the title, with one blank
+the plan is complete. Use `get_status` or `/phases` for full details.
-row after the title. Phase rows use one leading space and bold phase names;
-task rows use two leading spaces, and wrapped task text hangs under its task
-label. The summary and rows are refreshed after every plan mutation and session
-restore. Checklist markers use `[x]`, `[ ]`, and `[>]`; the host dims rows
-outside the current phase.
-Once every phase and task is complete, the persistent status and right-bar widget
-are cleared. Use `get_status` or `/phases` for the complete checklist and current
-task details. Spec text is deliberately excluded from persistent chrome. zot
-keeps the summary beside the transcript on wide
-terminals and automatically falls back to the normal above-input widget on
-narrow terminals. The extension does not implement any terminal layout code.

M examples/extensions/tasked-phases/skills/tasked-phases/SKILL.md +3 -13


@@ -18,19 +18,9 @@ Use the `tasked_phases` tool as the source of truth for the spec, phases, curren
18	18		7. Use `set_phase_checked` to complete or reopen every task in a phase. The phase must already contain at least one task.
19	19		8. When every task is checked, treat the plan as closed. For unrelated work, call `clear` to discard the plan, or call `set_spec` immediately followed by `replace_plan` to record a new spec and a new set of phases.
20	20
21		-	The right-bar summary and status bar are the persistent UI: both refresh after
22		-	each successful mutation and session restore and use `p done/total \| t done/total`.
23		-	Active plans also publish their phase and task rows below the compact title; the
24		-	host dims rows outside the current phase. Use `[x]`, `[ ]`, and `[>]` markers.
25		-	Use `get_status` or `/phases` when the complete checklist is needed. Persistent
26		-	chrome is cleared automatically once every phase and task is complete. Keep
27		-	phase titles to 32 characters or fewer and task text to 64 characters or fewer
28		-	in plans and detailed views. Routine successful mutations return one concise
29		-	progress line; use `get_status` or `replace_plan` when detailed output is needed.
30		-	`set_task_checked` changes one task. `set_phase_checked` intentionally checks
31		-	or unchecks every task in one phase, so use it only for an intentional phase-wide
32		-	update. Multiple individual checks in one turn are sequential calls, not an
33		-	automatic bulk update.
	21	+	Successful mutations return one progress line; use `get_status` or
	22	+	`replace_plan` for details. `set_task_checked` changes one task;
	23	+	`set_phase_checked` changes every task in a phase.
34	24
35	25		## Planning rules
36	26


@@ -18,19 +18,9 @@ Use the `tasked_phases` tool as the source of truth for the spec, phases, curren
18		7. Use `set_phase_checked` to complete or reopen every task in a phase. The phase must already contain at least one task.	18		7. Use `set_phase_checked` to complete or reopen every task in a phase. The phase must already contain at least one task.
19		8. When every task is checked, treat the plan as closed. For unrelated work, call `clear` to discard the plan, or call `set_spec` immediately followed by `replace_plan` to record a new spec and a new set of phases.	19		8. When every task is checked, treat the plan as closed. For unrelated work, call `clear` to discard the plan, or call `set_spec` immediately followed by `replace_plan` to record a new spec and a new set of phases.
20			20
21	-	The right-bar summary and status bar are the persistent UI: both refresh after	21	+	Successful mutations return one progress line; use `get_status` or
22	-	each successful mutation and session restore and use `p done/total \| t done/total`.	22	+	`replace_plan` for details. `set_task_checked` changes one task;
23	-	Active plans also publish their phase and task rows below the compact title; the	23	+	`set_phase_checked` changes every task in a phase.
24	-	host dims rows outside the current phase. Use `[x]`, `[ ]`, and `[>]` markers.
25	-	Use `get_status` or `/phases` when the complete checklist is needed. Persistent
26	-	chrome is cleared automatically once every phase and task is complete. Keep
27	-	phase titles to 32 characters or fewer and task text to 64 characters or fewer
28	-	in plans and detailed views. Routine successful mutations return one concise
29	-	progress line; use `get_status` or `replace_plan` when detailed output is needed.
30	-	`set_task_checked` changes one task. `set_phase_checked` intentionally checks
31	-	or unchecks every task in one phase, so use it only for an intentional phase-wide
32	-	update. Multiple individual checks in one turn are sequential calls, not an
33	-	automatic bulk update.
34			24
35		## Planning rules	25		## Planning rules
36			26

M examples/skills/tasked-phases/SKILL.md +3 -13


@@ -18,19 +18,9 @@ Use the `tasked_phases` tool as the source of truth for the spec, phases, curren
18	18		7. Use `set_phase_checked` to complete or reopen every task in a phase. The phase must already contain at least one task.
19	19		8. When every task is checked, treat the plan as closed. For unrelated work, call `clear` to discard the plan, or call `set_spec` immediately followed by `replace_plan` to record a new spec and a new set of phases.
20	20
21		-	The right-bar summary and status bar are the persistent UI: both refresh after
22		-	each successful mutation and session restore and use `p done/total \| t done/total`.
23		-	Active plans also publish their phase and task rows below the compact title; the
24		-	host dims rows outside the current phase. Use `[x]`, `[ ]`, and `[>]` markers.
25		-	Use `get_status` or `/phases` when the complete checklist is needed. Persistent
26		-	chrome is cleared automatically once every phase and task is complete. Keep
27		-	phase titles to 32 characters or fewer and task text to 64 characters or fewer
28		-	in plans and detailed views. Routine successful mutations return one concise
29		-	progress line; use `get_status` or `replace_plan` when detailed output is needed.
30		-	`set_task_checked` changes one task. `set_phase_checked` intentionally checks
31		-	or unchecks every task in one phase, so use it only for an intentional phase-wide
32		-	update. Multiple individual checks in one turn are sequential calls, not an
33		-	automatic bulk update.
	21	+	Successful mutations return one progress line; use `get_status` or
	22	+	`replace_plan` for details. `set_task_checked` changes one task;
	23	+	`set_phase_checked` changes every task in a phase.
34	24
35	25		## Planning rules
36	26


@@ -18,19 +18,9 @@ Use the `tasked_phases` tool as the source of truth for the spec, phases, curren
18		7. Use `set_phase_checked` to complete or reopen every task in a phase. The phase must already contain at least one task.	18		7. Use `set_phase_checked` to complete or reopen every task in a phase. The phase must already contain at least one task.
19		8. When every task is checked, treat the plan as closed. For unrelated work, call `clear` to discard the plan, or call `set_spec` immediately followed by `replace_plan` to record a new spec and a new set of phases.	19		8. When every task is checked, treat the plan as closed. For unrelated work, call `clear` to discard the plan, or call `set_spec` immediately followed by `replace_plan` to record a new spec and a new set of phases.
20			20
21	-	The right-bar summary and status bar are the persistent UI: both refresh after	21	+	Successful mutations return one progress line; use `get_status` or
22	-	each successful mutation and session restore and use `p done/total \| t done/total`.	22	+	`replace_plan` for details. `set_task_checked` changes one task;
23	-	Active plans also publish their phase and task rows below the compact title; the	23	+	`set_phase_checked` changes every task in a phase.
24	-	host dims rows outside the current phase. Use `[x]`, `[ ]`, and `[>]` markers.
25	-	Use `get_status` or `/phases` when the complete checklist is needed. Persistent
26	-	chrome is cleared automatically once every phase and task is complete. Keep
27	-	phase titles to 32 characters or fewer and task text to 64 characters or fewer
28	-	in plans and detailed views. Routine successful mutations return one concise
29	-	progress line; use `get_status` or `replace_plan` when detailed output is needed.
30	-	`set_task_checked` changes one task. `set_phase_checked` intentionally checks
31	-	or unchecks every task in one phase, so use it only for an intentional phase-wide
32	-	update. Multiple individual checks in one turn are sequential calls, not an
33	-	automatic bulk update.
34			24
35		## Planning rules	25		## Planning rules
36			26