docs(terminal): clarify color override timing and heuristic claim resolution
- commit
- 7ac2f1bf360d40ebb0fd418c264a6b383afdea4a
- author
- brice · · 2026-10-03 14:02 UTC
- committer
- brice · · 2026-10-03 14:14 UTC
- parent
- 30ad963
- signature
- GPG Verified
CD88F9E564E0102646FB6077A1A07C7C7C3E349D· arch-gpg Verified for the committer email
2 files · +5 -3
M docs/protocol.md +3 -1
| @@ -94,7 +94,9 @@ closed enum (`TRUE_COLOR`, `ANSI256`, `ANSI16`, `MONOCHROME`) and a missing | |||
| 94 | 94 | message, an `UNSPECIFIED` mode, or any unknown enum value is a malformed Hello | |
| 95 | 95 | (`sessionwire` rejects it before any mutation). `source` `UNSPECIFIED` means | |
| 96 | 96 | "unknown": the daemon then ignores the claimed mode and re-detects from | |
| 97 | - | `Hello.Env`; `DECLARED` and `FORCED` claims are used verbatim. | |
| 97 | + | `Hello.Env`; `DECLARED` and `FORCED` claims are used verbatim. A `HEURISTIC` truecolor claim | |
| 98 | + | upgrades a weaker daemon-side detection; any other `HEURISTIC` claim falls back | |
| 99 | + | to detection. | |
| 98 | 100 | (`internal/domain/terminalcap.Resolve`; wire tests in | |
| 99 | 101 | `sessionwire/proto_convert_test.go:TestProtoHelloColorWire`.) | |
| 100 | 102 | ||
| @@ -94,7 +94,9 @@ closed enum (`TRUE_COLOR`, `ANSI256`, `ANSI16`, `MONOCHROME`) and a missing | |||||
| 94 | message, an `UNSPECIFIED` mode, or any unknown enum value is a malformed Hello | 94 | message, an `UNSPECIFIED` mode, or any unknown enum value is a malformed Hello | ||
| 95 | (`sessionwire` rejects it before any mutation). `source` `UNSPECIFIED` means | 95 | (`sessionwire` rejects it before any mutation). `source` `UNSPECIFIED` means | ||
| 96 | "unknown": the daemon then ignores the claimed mode and re-detects from | 96 | "unknown": the daemon then ignores the claimed mode and re-detects from | ||
| 97 | - | `Hello.Env`; `DECLARED` and `FORCED` claims are used verbatim. | 97 | + | `Hello.Env`; `DECLARED` and `FORCED` claims are used verbatim. A `HEURISTIC` truecolor claim |
| 98 | + | upgrades a weaker daemon-side detection; any other `HEURISTIC` claim falls back | |||
| 99 | + | to detection. | |||
| 98 | (`internal/domain/terminalcap.Resolve`; wire tests in | 100 | (`internal/domain/terminalcap.Resolve`; wire tests in | ||
| 99 | `sessionwire/proto_convert_test.go:TestProtoHelloColorWire`.) | 101 | `sessionwire/proto_convert_test.go:TestProtoHelloColorWire`.) | ||
| 100 | 102 | ||||
M docs/terminal.md +2 -2
| @@ -26,7 +26,7 @@ Detection reads the client's `TERM` and `COLORTERM`. The first matching row wins | |||
| 26 | 26 | | 2 | `TERM=xterm-kitty` inside kitty | truecolor | | |
| 27 | 27 | | 3 | `TERM` is `dumb`, `vt52`, `vt100`, `vt102`, `vt220`, or ends in `-m` or `-mono` | monochrome | | |
| 28 | 28 | | 4 | `TERM` contains `256color` | 256 | | |
| 29 | - | | 5 | `TERM` is `linux`, `ansi`, `cons25`, or ends in `-16color` or `-color` | 16 | | |
| 29 | + | | 5 | `TERM` is `linux`, `ansi`, `cons25`, or ends in `-16color` or `-color` | 16 (8-color terminals use the first 8) | | |
| 30 | 30 | | 6 | anything else | 256 (unverified guess) | | |
| 31 | 31 | ||
| 32 | 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. | |
| @@ -40,7 +40,7 @@ When detection finds a terminal with fewer than truecolor colors, vev shows a on | |||
| 40 | 40 | ||
| 41 | 41 | Values: `auto`, `truecolor`, `256`, `16`, `mono`. `auto` (or an empty value) means detection. A forced mode never shows the notice. | |
| 42 | 42 | ||
| 43 | - | The override is read when a client attaches or reconnects. A config reload in the running daemon does not change attached clients. | |
| 43 | + | `VEV_COLORS` and `terminal.colors` are read when the client starts; restart the client to apply a change. A config reload in the running daemon does not change attached clients. | |
| 44 | 44 | ||
| 45 | 45 | ### What each mode changes | |
| 46 | 46 | ||
| @@ -26,7 +26,7 @@ Detection reads the client's `TERM` and `COLORTERM`. The first matching row wins | |||||
| 26 | | 2 | `TERM=xterm-kitty` inside kitty | 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 | | 27 | | 3 | `TERM` is `dumb`, `vt52`, `vt100`, `vt102`, `vt220`, or ends in `-m` or `-mono` | monochrome | | ||
| 28 | | 4 | `TERM` contains `256color` | 256 | | 28 | | 4 | `TERM` contains `256color` | 256 | | ||
| 29 | - | | 5 | `TERM` is `linux`, `ansi`, `cons25`, or ends in `-16color` or `-color` | 16 | | 29 | + | | 5 | `TERM` is `linux`, `ansi`, `cons25`, or ends in `-16color` or `-color` | 16 (8-color terminals use the first 8) | |
| 30 | | 6 | anything else | 256 (unverified guess) | | 30 | | 6 | anything else | 256 (unverified guess) | | ||
| 31 | 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. | 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. | ||
| @@ -40,7 +40,7 @@ When detection finds a terminal with fewer than truecolor colors, vev shows a on | |||||
| 40 | 40 | ||||
| 41 | Values: `auto`, `truecolor`, `256`, `16`, `mono`. `auto` (or an empty value) means detection. A forced mode never shows the notice. | 41 | Values: `auto`, `truecolor`, `256`, `16`, `mono`. `auto` (or an empty value) means detection. A forced mode never shows the notice. | ||
| 42 | 42 | ||||
| 43 | - | The override is read when a client attaches or reconnects. A config reload in the running daemon does not change attached clients. | 43 | + | `VEV_COLORS` and `terminal.colors` are read when the client starts; restart the client to apply a change. A config reload in the running daemon does not change attached clients. |
| 44 | 44 | ||||
| 45 | ### What each mode changes | 45 | ### What each mode changes | ||
| 46 | 46 | ||||