1 files changed, 43 insertions, 0 deletions
diff --git a/templates/terminal/README.md b/templates/terminal/README.md
new file mode 100644
index 0000000..6e33872
--- /dev/null
+++ b/templates/terminal/README.md
@@ -0,0 +1,43 @@
+# Kitty and Neovim
+
+Both were left alone through the earlier phases, because this is where the
+readability problem that shaped the whole design actually lived: wallpaper
+derived colours were being written into kitty's sixteen ANSI slots, and nothing
+in a wallpaper guarantees that `color4` stays legible against `color0`.
+
+They are now on Catppuccin Macchiato, which is safe for the opposite reason:
+the palette is hand tuned, so the ANSI slots have deliberate relationships
+rather than accidental ones.
+
+## What changed
+
+- `~/.config/kitty/current-theme.conf` was a symlink into `~/.cache/wal/`. It
+  is now a real file holding the upstream `catppuccin/kitty` macchiato theme.
+- `~/bin/wal.sh` no longer recreates that symlink. It did so on every wallpaper
+  change, which would have silently reverted the theme.
+- Neovim used `colorscheme pywal`, reading the same pywal output. It now uses
+  the `catppuccin/nvim` plugin at the macchiato flavour.
+- vim-airline was on `base16_dracula`, matching nothing. It is now `base16`,
+  which derives its colours from the active colorscheme. There is no Catppuccin
+  theme in vim-airline-themes, and adding a second status line plugin was not
+  worth it.
+
+## Contrast, measured
+
+Against each theme's own background, every ANSI slot clears 4.5:1 in both the
+old preset and Macchiato, except `color0`, which is the near background "black"
+slot in both and is meant to be low.
+
+The one real regression is `color8`, the bright black slot many colourschemes
+use for comments: 3.83:1 before, 2.38:1 now. It does not bite here because the
+Catppuccin neovim plugin sets its own comment colour instead of using ANSI 8,
+which was verified on screen. It would matter for a terminal program that
+insists on ANSI 8 for dim text.
+
+Foreground on background drops from 21:1 (pure white on pure black) to 9.92:1.
+Both are well clear of the threshold; Macchiato is softer by design.
+
+## Not changed
+
+Kitty's font is still `CommitMono Nerd Font Mono`. Terminal font choice is
+personal and was not part of the theming brief.