docs(terminal): document color modes, detection and overrides

commit: 3703ae2082c7eb5375b1fbe37fcbce837001abbe
author: brice · 19d ago · 2026-10-03 13:40 UTC
committer: brice · 19d ago · 2026-10-03 14:14 UTC
parent: da6f075
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

3 files · +56 -5

M docs/architecture.md +2 -2

@@ -1,6 +1,6 @@
1	1		# Architecture
2	2
3		-	vev uses a hexagonal core with typed session messages at the client and daemon boundary. Binary framing and carriage selection stay outside the use cases. The current strict protocol version is 59.
	3	+	vev uses a hexagonal core with typed session messages at the client and daemon boundary. Binary framing and carriage selection stay outside the use cases. The current strict protocol version is 65.
4	4
5	5		`CommandResult` has a closed explicit outcome contract:
6	6

@@ -132,7 +132,7 @@ Use cases exchange `protocol.ClientMessage` and `protocol.ServerMessage` values.
132	132		`go tool buf generate`, and handle the new variant in `sessionwire`.
133	133		Never edit generated `*.pb.go`; never add manual IDs or dispatch tables.
134	134		- Implement I/O, queues, workers, environment integration, or technology selection in an adapter or `internal/app`.
135		-	- Bump `internal/protocol.Version` for negotiated wire layout changes (currently `64`). The preamble epoch (`wire.ProtocolEpoch`, QUIC ALPN `vev/1`) bumps only for an intentional clean break.
	135	+	- Bump `internal/protocol.Version` for negotiated wire layout changes (currently `65`). The preamble epoch (`wire.ProtocolEpoch`, QUIC ALPN `vev/1`) bumps only for an intentional clean break.
136	136
137	137		## Broker
138	138

@@ -1,6 +1,6 @@
1		# Architecture	1		# Architecture
2			2
3	-	vev uses a hexagonal core with typed session messages at the client and daemon boundary. Binary framing and carriage selection stay outside the use cases. The current strict protocol version is 59.	3	+	vev uses a hexagonal core with typed session messages at the client and daemon boundary. Binary framing and carriage selection stay outside the use cases. The current strict protocol version is 65.
4			4
5		`CommandResult` has a closed explicit outcome contract:	5		`CommandResult` has a closed explicit outcome contract:
6			6

@@ -132,7 +132,7 @@ Use cases exchange `protocol.ClientMessage` and `protocol.ServerMessage` values.
132		`go tool buf generate`, and handle the new variant in `sessionwire`.	132		`go tool buf generate`, and handle the new variant in `sessionwire`.
133		Never edit generated `*.pb.go`; never add manual IDs or dispatch tables.	133		Never edit generated `*.pb.go`; never add manual IDs or dispatch tables.
134		- Implement I/O, queues, workers, environment integration, or technology selection in an adapter or `internal/app`.	134		- Implement I/O, queues, workers, environment integration, or technology selection in an adapter or `internal/app`.
135	-	- Bump `internal/protocol.Version` for negotiated wire layout changes (currently `64`). The preamble epoch (`wire.ProtocolEpoch`, QUIC ALPN `vev/1`) bumps only for an intentional clean break.	135	+	- Bump `internal/protocol.Version` for negotiated wire layout changes (currently `65`). The preamble epoch (`wire.ProtocolEpoch`, QUIC ALPN `vev/1`) bumps only for an intentional clean break.
136			136
137		## Broker	137		## Broker
138			138

M docs/configuration.md +5 -1


@@ -43,6 +43,9 @@ ephemeral.close-on-exit = on
43	43		# Use the kitty keyboard protocol when the terminal supports it (enables Ctrl+1..9).
44	44		keyboard.kitty-protocol = on
45	45
	46	+	# Outer terminal colors: auto (detect), truecolor, 256, 16, or mono.
	47	+	terminal.colors = auto
	48	+
46	49		# Rebindable actions. Leave a line out to keep its built-in binding.
47	50		open-palette = alt+space
48	51		toggle-floating-pane = alt+f

@@ -207,7 +210,8 @@ If the daemon refuses to start because its session data is broken, do not edit t
207	210		\| `theme.accent = 0`–`15` \| Use exactly that ANSI color as the accent. \|
208	211
209	212		- vev only colors its own UI (bars, borders, palette). Pane content is never recolored.
210		-	- Tinted backgrounds need a truecolor terminal. Otherwise the accent only colors text and borders.
	213	+	- Tinted backgrounds need a truecolor or 256-color terminal. On 16-color and monochrome terminals vev uses bold, reverse, and faint instead. See [terminal colors](terminal.md#colors).
	214	+	- `terminal.colors` forces the color mode of your terminal (`auto`, `truecolor`, `256`, `16`, `mono`). `VEV_COLORS` overrides it. See [terminal colors](terminal.md#colors).
211	215		- vev follows light/dark switches your terminal reports. It cannot see palette changes the terminal does not report.
212	216
213	217		## Bindings

 # Use the kitty keyboard protocol when the terminal supports it (enables Ctrl+1..9).
 keyboard.kitty-protocol = on
+# Outer terminal colors: auto (detect), truecolor, 256, 16, or mono.
+terminal.colors = auto
 # Rebindable actions. Leave a line out to keep its built-in binding.
 open-palette = alt+space
 toggle-floating-pane = alt+f
 | `theme.accent = 0`–`15` | Use exactly that ANSI color as the accent. |
 - vev only colors its own UI (bars, borders, palette). Pane content is never recolored.
-- Tinted backgrounds need a truecolor terminal. Otherwise the accent only colors text and borders.
+- Tinted backgrounds need a truecolor or 256-color terminal. On 16-color and monochrome terminals vev uses bold, reverse, and faint instead. See [terminal colors](terminal.md#colors).
+- `terminal.colors` forces the color mode of your terminal (`auto`, `truecolor`, `256`, `16`, `mono`). `VEV_COLORS` overrides it. See [terminal colors](terminal.md#colors).
 - vev follows light/dark switches your terminal reports. It cannot see palette changes the terminal does not report.
 ## Bindings

M docs/terminal.md +49 -2


@@ -13,8 +13,55 @@ Both set `COLORTERM=truecolor` and `TERM_PROGRAM=vev`.
13	13
14	14		- vev checks with `infocmp -x xterm-direct` before each new pane (1 second timeout). Existing panes keep their `TERM`.
15	15		- With `xterm-256color`, apps must read `COLORTERM` to use RGB colors.
16		-	- If your outer terminal does not support truecolor, vev converts colors to the terminal's palette (256, 16, or none) and shows a one-time notice unless the mode was forced with `terminal.colors` or `VEV_COLORS`.
17		-	- On 16-color terminals vev's own UI (bars, borders, pickers, overlays) drops tinted backgrounds and uses reverse video, bold, faint, and the terminal's own palette slots for its accent. On monochrome terminals it uses only bold, reverse, and faint. Pane content is never recolored by vev's UI.
	16	+
	17	+	### Outer terminal color modes
	18	+
	19	+	vev picks a color mode for each attachment, so several clients on one session can use different modes. Modes: `truecolor`, `256`, `16`, `monochrome`.
	20	+
	21	+	Detection reads the client's `TERM` and `COLORTERM`. The first matching row wins:
	22	+
	23	+	\| Order \| Signal \| Mode \|
	24	+	\|---\|---\|---\|
	25	+	\| 1 \| `COLORTERM` is `truecolor` or `24bit`, or `TERM` is `xterm-direct` or ends in `-direct` \| truecolor \|
	26	+	\| 2 \| `TERM=xterm-kitty` inside kitty \| truecolor \|
	27	+	\| 3 \| `TERM` is `dumb`, `vt52`, `vt100`, `vt102`, `vt220`, or ends in `-m` or `-mono` \| monochrome \|
	28	+	\| 4 \| `TERM` contains `256color` \| 256 \|
	29	+	\| 5 \| `TERM` is `linux`, `ansi`, `cons25`, or ends in `-16color` or `-color` \| 16 \|
	30	+	\| 6 \| anything else \| 256 (unverified guess) \|
	31	+
	32	+	When detection finds a terminal with fewer than truecolor colors, vev shows a one-time notice. The notice is not shown for the unverified guess or for a forced mode.
	33	+
	34	+	### Override the mode
	35	+
	36	+	\| Where \| Example \| Notes \|
	37	+	\|---\|---\|---\|
	38	+	\| `VEV_COLORS` environment variable \| `VEV_COLORS=16 vev` \| Wins over the config key. An invalid value is ignored and logged as a warning. \|
	39	+	\| `terminal.colors` in the [configuration](configuration.md) \| `terminal.colors = mono` \| Applies to every client that has no `VEV_COLORS`. \|
	40	+
	41	+	Values: `auto`, `truecolor`, `256`, `16`, `mono`. `auto` (or an empty value) means detection. A forced mode never shows the notice.
	42	+
	43	+	The override is read when a client attaches or reconnects. A config reload in the running daemon does not change attached clients.
	44	+
	45	+	### What each mode changes
	46	+
	47	+	Pane content:
	48	+
	49	+	\| Mode \| Pane colors \|
	50	+	\|---\|---\|
	51	+	\| truecolor \| Unchanged. \|
	52	+	\| 256 \| RGB colors map to the xterm 256-color palette. \|
	53	+	\| 16 \| RGB and indexed colors 16-255 map to the nearest of the 16 ANSI colors. Underline color is dropped. \|
	54	+	\| monochrome \| All colors are dropped. Attributes (bold, underline, reverse, and so on) stay. \|
	55	+
	56	+	vev's own UI (bars, borders, pickers, overlays):
	57	+
	58	+	\| Mode \| UI \|
	59	+	\|---\|---\|
	60	+	\| truecolor, 256 \| Full theme. \|
	61	+	\| 16 \| No tinted backgrounds. Active and selected items use bold and reverse, secondary text uses faint. The accent is a terminal palette slot. \|
	62	+	\| monochrome \| Same as 16 with no color at all. \|
	63	+
	64	+	The browser terminal and the headless `--ui-driver` always use truecolor, whatever `TERM`, `COLORTERM`, `VEV_COLORS`, or `terminal.colors` say.
18	65
19	66		### Install `xterm-direct`
20	67


@@ -13,8 +13,55 @@ Both set `COLORTERM=truecolor` and `TERM_PROGRAM=vev`.
13			13
14		- vev checks with `infocmp -x xterm-direct` before each new pane (1 second timeout). Existing panes keep their `TERM`.	14		- vev checks with `infocmp -x xterm-direct` before each new pane (1 second timeout). Existing panes keep their `TERM`.
15		- With `xterm-256color`, apps must read `COLORTERM` to use RGB colors.	15		- With `xterm-256color`, apps must read `COLORTERM` to use RGB colors.
16	-	- If your outer terminal does not support truecolor, vev converts colors to the terminal's palette (256, 16, or none) and shows a one-time notice unless the mode was forced with `terminal.colors` or `VEV_COLORS`.	16	+
17	-	- On 16-color terminals vev's own UI (bars, borders, pickers, overlays) drops tinted backgrounds and uses reverse video, bold, faint, and the terminal's own palette slots for its accent. On monochrome terminals it uses only bold, reverse, and faint. Pane content is never recolored by vev's UI.	17	+	### Outer terminal color modes
			18	+
			19	+	vev picks a color mode for each attachment, so several clients on one session can use different modes. Modes: `truecolor`, `256`, `16`, `monochrome`.
			20	+
			21	+	Detection reads the client's `TERM` and `COLORTERM`. The first matching row wins:
			22	+
			23	+	\| Order \| Signal \| Mode \|
			24	+	\|---\|---\|---\|
			25	+	\| 1 \| `COLORTERM` is `truecolor` or `24bit`, or `TERM` is `xterm-direct` or ends in `-direct` \| truecolor \|
			26	+	\| 2 \| `TERM=xterm-kitty` inside kitty \| truecolor \|
			27	+	\| 3 \| `TERM` is `dumb`, `vt52`, `vt100`, `vt102`, `vt220`, or ends in `-m` or `-mono` \| monochrome \|
			28	+	\| 4 \| `TERM` contains `256color` \| 256 \|
			29	+	\| 5 \| `TERM` is `linux`, `ansi`, `cons25`, or ends in `-16color` or `-color` \| 16 \|
			30	+	\| 6 \| anything else \| 256 (unverified guess) \|
			31	+
			32	+	When detection finds a terminal with fewer than truecolor colors, vev shows a one-time notice. The notice is not shown for the unverified guess or for a forced mode.
			33	+
			34	+	### Override the mode
			35	+
			36	+	\| Where \| Example \| Notes \|
			37	+	\|---\|---\|---\|
			38	+	\| `VEV_COLORS` environment variable \| `VEV_COLORS=16 vev` \| Wins over the config key. An invalid value is ignored and logged as a warning. \|
			39	+	\| `terminal.colors` in the [configuration](configuration.md) \| `terminal.colors = mono` \| Applies to every client that has no `VEV_COLORS`. \|
			40	+
			41	+	Values: `auto`, `truecolor`, `256`, `16`, `mono`. `auto` (or an empty value) means detection. A forced mode never shows the notice.
			42	+
			43	+	The override is read when a client attaches or reconnects. A config reload in the running daemon does not change attached clients.
			44	+
			45	+	### What each mode changes
			46	+
			47	+	Pane content:
			48	+
			49	+	\| Mode \| Pane colors \|
			50	+	\|---\|---\|
			51	+	\| truecolor \| Unchanged. \|
			52	+	\| 256 \| RGB colors map to the xterm 256-color palette. \|
			53	+	\| 16 \| RGB and indexed colors 16-255 map to the nearest of the 16 ANSI colors. Underline color is dropped. \|
			54	+	\| monochrome \| All colors are dropped. Attributes (bold, underline, reverse, and so on) stay. \|
			55	+
			56	+	vev's own UI (bars, borders, pickers, overlays):
			57	+
			58	+	\| Mode \| UI \|
			59	+	\|---\|---\|
			60	+	\| truecolor, 256 \| Full theme. \|
			61	+	\| 16 \| No tinted backgrounds. Active and selected items use bold and reverse, secondary text uses faint. The accent is a terminal palette slot. \|
			62	+	\| monochrome \| Same as 16 with no color at all. \|
			63	+
			64	+	The browser terminal and the headless `--ui-driver` always use truecolor, whatever `TERM`, `COLORTERM`, `VEV_COLORS`, or `terminal.colors` say.
18			65
19		### Install `xterm-direct`	66		### Install `xterm-direct`
20			67