docs: log Phase 33 (neutral theme-mapping wording)

CLAUDE.md

@@ -172,6 +172,7 @@ Before changing any interaction, consult the keybinding matrix and overlay specs
 - **Phase 30 — tailTUI theme schema, Omarchy template & live theme reload** — closed the one gap Phase 27 could not: some mappings are genuinely undecidable in code. `osaka-jade` defines `yellow = #459451` (a green), so mapping `yellow`→Warning makes exit-node markers nearly indistinguishable from the online green — but preferring `orange` breaks `retro-82`, where orange *is* the accent. **(1) tailTUI's own schema**: a third wire struct `tailtuiTheme` with one key per `Theme` field, tried **before** both Omarchy schemas, and probed as `tailtui.toml` **ahead of** `colors.toml` inside each theme directory. Keys are disjoint from the Omarchy vocabularies so detection stays key-based; `mode`/`background` are shared and therefore excluded from `hasMarkers()`. **(2) Omarchy template**: `contrib/tailtui.toml.tpl`, installed by the user into `~/.config/omarchy/themed/`. Omarchy's `omarchy-theme-set-templates` renders every `*.tpl` there into the **active theme directory** (`$NEXT_THEME_DIR/<name>`, which becomes `~/.local/state/omarchy/current/theme/`) on every theme switch — i.e. straight into the directory the loader already probes, so no new path was needed. Templates get the full palette (semantic slots, `color0`–`color15`, `mode`, `bright_`/`dark_`/`light_` variants) plus `_strip`/`_rgb` modifiers and a `{{ mix a b 30% }}` blend. **(3) Live reload**: `styles.ThemeStamp()` (path+mtime) plus `checkThemeCmd`, batched onto the **existing** `refreshInterval` tick — no fsnotify, no new dependency — so switching the desktop theme re-colors a running tailTUI within one tick. The critical constraint: the command **returns** the parsed `Theme` and never calls `styles.Apply` itself, because `Apply` rewrites package-level vars `View` reads; applying happens in `Update`, on the Elm goroutine. The handler records the stamp even on no-change (so a file appearing/vanishing is caught) and rebuilds viewport-backed overlays via `resizeOverlay()`, whose content would otherwise keep stale ANSI colors. Zero-config behavior is untouched: with no template installed, `colors.toml` is read exactly as before. **Tests**: own-schema mapping, light mode, three-way detection non-ambiguity, `tailtui.toml`-over-`colors.toml` precedence, fallback when no template exists, `ThemeStamp` change tracking and empty state (`theme_test.go`); palette applied + stamp recorded + logged, unchanged-is-quiet, overlay rebuilt (forcing TrueColor, since a TTY-less test strips every SGR and both renders would otherwise compare equal), and `New()` stamp seeding (`theme_reload_test.go`).
 - **Phase 31 — Release v1.3.0** — bumped `appVersion` `v1.2.0` → `v1.3.0` (still the single definition in `view.go`) for Phase 30's live theme switching + tailTUI theme schema. **Packaging gap closed**: the README told users to `cp contrib/tailtui.toml.tpl …`, which is wrong for anyone who installed from the AUR / `.deb` / `.rpm` — they have a binary package, not a checkout. The template is now installed to **`/usr/share/tailtui/tailtui.toml.tpl`** by the packaging, and the README gives both paths. Any future user-facing file added under `contrib/` needs the same treatment, or the docs silently break for package users. Also decoupled `version_test.go` from the real version string (it now asserts on an obviously-arbitrary literal), so a release bump no longer looks like it requires a test edit — the test exercises `SetVersion`'s normalization, not the current version. README gained a "What's New in v1.3.0" section; the theming docs and the Phase 30 entry shipped with the feature itself, which is the rule: **docs ride in the feature PR, and the release PR carries only version, changelog, and phase log**.
 - **Phase 32 — Install documentation for every distribution route** — the README's Installation section still offered only `go install` and a source build, despite v1.2.0/v1.3.0 publishing `.tar.gz`/`.deb`/`.rpm` for amd64+arm64 and an AUR package existing since v1.1.0 — the recommended path for most users was undocumented. Rewrote it into four routes (AUR, `.deb`/`.rpm`, prebuilt tarball, from source), leading with the packaged ones since they need no Go toolchain. **The rule this enforces**: every install route must be able to follow every other instruction in the README. The live-theme-switching section previously offered `/usr/share/tailtui/…` (packages) or `contrib/…` (clone), which strands anyone who ran `go install` — they have neither, so a third `curl` line fetching the template from `raw.githubusercontent.com` was added. Also documented the two `go install` caveats: the binary lands in `$GOBIN`/`$GOPATH/bin`, which is not necessarily on `PATH`, and a source build installs the binary alone. Docs-only — no Go, test, or packaging changes, and no version bump (nothing user-facing changed in the program itself).
+- **Phase 33 — Neutral wording for the theme-mapping rationale** — the README justified the `tailtui.toml` template in two places by naming one shipped Omarchy theme and addressing the reader in the second person: the v1.3.0 changelog bullet ("You decide the ambiguous mappings … `osaka-jade` defines its `yellow` as a green") and the Theming section's template paragraph ("… fixes it, for your themes, permanently"). On a public repo that reads as pointed at a specific theme and its author rather than as documentation of a general problem. Both passages now state the case generically — *some palettes define their `yellow` as a green, which leaves exit-node markers nearly indistinguishable from the online color* — while keeping the concrete `warning = "{{ orange }}"` fix, which is the part a reader actually needs in order to write their own template. **The rule this sets**: public-facing docs describe the *class* of problem, not a named third-party theme that fails at it; internal notes may stay specific — `CLAUDE.md`'s Phase 30 entry still names `osaka-jade` deliberately, because the mapping decision it records only makes sense against the concrete case. Docs-only — no Go, test, or packaging changes, and no version bump (nothing user-facing changed in the program itself).
 - **Upcoming (next major cycle — see the README Roadmap)** —
   - **Tailscale Serve & Funnel management**: visual port forwarding to securely expose local services to the tailnet (`tailscale serve`) or the public internet (`tailscale funnel`), driven from keyboard overlays in the existing modal style.
   - **Connection diagnostics**: deep-dive into peer connection health — DERP-relay vs. direct routing and the signals to debug a flaky link (likely from `tailscale status --json` endpoints + `tailscale ping`/`netcheck`).