Handoff — 2026-08-31 — Cappuccino, Cobalt, Monochrome

State

Ticket 0012 is implemented and uncommitted, on branch feature/theme-cappucino (the user created it; HEAD was 9505d1d). Six themes now ship: the three that existed plus cappuccino (espresso brown), cobalt (the recognised palette) and monochrome (no hue at all).

No Go code changed. Themes are embedded with //go:embed themes/*.toml, so a theme is a file. What did change is the tests: three new ones, and the five that already iterated theme.Available() now cover six themes instead of three.

Full suite green, green under -race. Quality gate PASS — 0/0/0, complexity 1592, unchanged. Docs in both languages, internal/theme/README.md and the root README in sync.

Also uncommitted, and not mine: .tickets/issues/0010 at state: closed.

In flight

Nothing.

Next steps

Review and commit. A commit message was proposed at the end of the session.
Close ticket 0012 — the user's call.
Nobody has looked at these three themes on a real screen. The tests hold them to contrast and distinctness, and the VT emulator confirms they render, but taste is not testable. Expect to want to nudge a colour or two.

Open questions / blockers

None.

Watch out for

A blanket readability rule is wrong, and I nearly shipped one. The faintest colours in every theme — scrollbar trough at 20, desktop, shadow, inactive frame, disabled entry, line-number gutter — are faint on purpose. readKeys in internal/editor/view_test.go lists what must be read and deliberately excludes the furniture. If you add a style key, decide which side it is on; do not add it to readKeys reflexively.
The 64 floor is a floor, not a target. The dimmest reading colour any theme actually uses is 80. Do not raise the constant to "tighten" it — you would be pinning the threshold to today's palettes, and the next legitimate tweak would trip it.
Adding a theme changes the tutorial. docs/*/tutorials/getting-started.md counts arrow presses in the Theme dialog to reach turbo-dark, which is last alphabetically. A seventh theme sorting before it makes that count wrong, and a tutorial that miscounts is the one kind of documentation that must never be approximate.
Defines is satisfied by inheritance. That is why TestEveryEmbeddedThemeParsesAndCoversEveryKey passed for a theme missing a key, and why TestEveryEmbeddedThemeSetsEveryKeyItself exists. It applies to embedded themes only — a user theme inheriting is correct and documented.
Falsify a new theme test before trusting it. All three of these passed the moment they were written, which proves nothing. Each was made to fail on purpose first; the handoffs of this project record more than one test that passed because it tested nothing.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


# Handoff — 2026-08-31 — Cappuccino, Cobalt, Monochrome

## State

Ticket 0012 is implemented and **uncommitted**, on branch `feature/theme-cappucino` (the user created it; HEAD was `9505d1d`). Six themes now ship: the three that existed plus `cappuccino` (espresso brown), `cobalt` (the recognised palette) and `monochrome` (no hue at all).

No Go code changed. Themes are embedded with `//go:embed themes/*.toml`, so a theme is a file. What did change is the tests: three new ones, and the five that already iterated `theme.Available()` now cover six themes instead of three.

Full suite green, green under `-race`. Quality gate PASS — 0/0/0, complexity 1592, unchanged. Docs in both languages, `internal/theme/README.md` and the root README in sync.

Also uncommitted, and **not mine**: `.tickets/issues/0010` at `state: closed`.

## In flight

Nothing.

## Next steps

1. **Review and commit.** A commit message was proposed at the end of the session.
2. **Close ticket 0012** — the user's call.
3. Nobody has looked at these three themes on a real screen. The tests hold them to contrast and distinctness, and the VT emulator confirms they render, but *taste* is not testable. Expect to want to nudge a colour or two.

## Open questions / blockers

None.

## Watch out for

- **A blanket readability rule is wrong, and I nearly shipped one.** The faintest colours in every theme — scrollbar trough at 20, desktop, shadow, inactive frame, disabled entry, line-number gutter — are faint *on purpose*. `readKeys` in `internal/editor/view_test.go` lists what must be read and deliberately excludes the furniture. If you add a style key, decide which side it is on; do not add it to `readKeys` reflexively.
- **The 64 floor is a floor, not a target.** The dimmest reading colour any theme actually uses is 80. Do not raise the constant to "tighten" it — you would be pinning the threshold to today's palettes, and the next legitimate tweak would trip it.
- **Adding a theme changes the tutorial.** `docs/*/tutorials/getting-started.md` counts arrow presses in the Theme dialog to reach `turbo-dark`, which is last alphabetically. A seventh theme sorting before it makes that count wrong, and a tutorial that miscounts is the one kind of documentation that must never be approximate.
- **`Defines` is satisfied by inheritance.** That is why `TestEveryEmbeddedThemeParsesAndCoversEveryKey` passed for a theme missing a key, and why `TestEveryEmbeddedThemeSetsEveryKeyItself` exists. It applies to **embedded** themes only — a user theme inheriting is correct and documented.
- **Falsify a new theme test before trusting it.** All three of these passed the moment they were written, which proves nothing. Each was made to fail on purpose first; the handoffs of this project record more than one test that passed because it tested nothing.