From aaf1be0bcb55c63d33808f0254dc713a12195a1a Mon Sep 17 00:00:00 2001
From: pi <pi@pi-devbox>
Date: Sun, 12 Jul 2026 23:19:19 +0200
Subject: [PATCH] base: readable Neovim colours out of the box (termguicolors +
 kitty-terminfo)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Vanilla Neovim fell back to a 256-colour palette over ssh/kitty and rendered
strings/comments in a muddy, low-contrast colour. Fix, all base-affecting:

- rootfs/etc/xdg/nvim/sysinit.vim: system vimrc enabling termguicolors. Loads
  for every user before any personal ~/.config/nvim; overridable per-user.
- Dockerfile.base: install kitty-terminfo (TERM=xterm-kitty understood; lets
  Neovim auto-detect true colour) and set ENV COLORTERM=truecolor.
- smoke-test.sh: assert xterm-kitty terminfo present and nvim tgc default on.
- CHANGELOG (Unreleased/Added) + README editor note.

No tag — lands on the next base-<hash> rebuild.
---
 CHANGELOG.md                    |  9 +++++++++
 Dockerfile.base                 | 19 +++++++++++++++++++
 README.md                       |  6 ++++++
 rootfs/etc/xdg/nvim/sysinit.vim | 18 ++++++++++++++++++
 scripts/smoke-test.sh           |  2 ++
 5 files changed, 54 insertions(+)
 create mode 100644 rootfs/etc/xdg/nvim/sysinit.vim

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0088e34..b4b5917 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -24,6 +24,15 @@ Pre-v1.0.0 tags followed the pi npm version (`v{pi_version}[letter]`).
   `~/.gitignore_global` is absent); their file can be updated by hand. Base-
   affecting (`Dockerfile.base` COPY of the seed), rebuilds `base-<hash>`.
 
+- **Readable Neovim colours out of the box.** The base now ships a system-wide
+  Neovim config (`/etc/xdg/nvim/sysinit.vim`) that enables `termguicolors`,
+  plus the `kitty-terminfo` package. Vanilla Neovim otherwise fell back to a
+  256-colour palette over ssh/kitty and rendered strings and comments in a
+  muddy, low-contrast dark colour. `sysinit.vim` is Neovim's system vimrc: it
+  loads for every user before any personal `~/.config/nvim` and can still be
+  overridden per-user (`:set notermguicolors`, or your own init). Base-affecting
+  (`Dockerfile.base` apt package + COPY), rebuilds `base-<hash>`.
+
 ### Fixed
 
 - **`pandoc --pdf-engine=typst` now works without `-V mainfont`.** pandoc's
diff --git a/Dockerfile.base b/Dockerfile.base
index 1da872c..1c5ceb9 100644
--- a/Dockerfile.base
+++ b/Dockerfile.base
@@ -70,6 +70,12 @@ ENV DEBIAN_FRONTEND=noninteractive
 #                  htop/tmux, so it adds no extra packages. Companion to nvim
 #                  and the `micro` binary installed further down. EDITOR stays
 #                  nvim; users opt in via `export EDITOR=nano`.
+#   kitty-terminfo — terminfo entry for the kitty terminal (TERM=xterm-kitty).
+#                  ~77 KB, terminfo file only (no kitty binary). Without it,
+#                  ncurses apps fall back and Neovim can't reliably detect
+#                  true-colour from kitty over ssh; installing it makes
+#                  TERM=xterm-kitty understood. Pairs with the system-wide
+#                  Neovim termguicolors default (etc/xdg/nvim/sysinit.vim).
 RUN apt-get update && \
     apt-get upgrade -y --no-install-recommends && \
     apt-get install -y --no-install-recommends \
@@ -107,6 +113,7 @@ RUN apt-get update && \
     imagemagick \
     socat \
     nano \
+    kitty-terminfo \
     && ln -s /usr/bin/fdfind /usr/local/bin/fd \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/*
@@ -429,6 +436,11 @@ ENV LANG=en_US.UTF-8
 ENV LANGUAGE=en_US:en
 ENV LC_ALL=en_US.UTF-8
 ENV EDITOR=nvim
+# Advertise 24-bit colour so colour-aware tools (Neovim's own auto-detect, bat,
+# delta, ...) use true colour instead of a 256-colour fallback. Safe for the
+# modern terminals this devbox targets; override by exporting `COLORTERM=`
+# (empty) from a terminal that lacks true-colour support.
+ENV COLORTERM=truecolor
 ENV PATH="/home/developer/.local/bin:/home/developer/.cargo/bin:${PATH}"
 
 # ── Node.js (required for pi + MCP servers + tldr) ──
@@ -558,6 +570,13 @@ COPY rootfs/home/developer/.bash_aliases     /etc/skel-devbox/.bash_aliases
 COPY rootfs/home/developer/.inputrc          /etc/skel-devbox/.inputrc
 COPY rootfs/home/developer/.gitignore_global /etc/skel-devbox/.gitignore_global
 
+# ── Editor defaults: system-wide Neovim true-colour ──────────────────
+# /etc/xdg/nvim/sysinit.vim is Neovim's system vimrc: it loads for every user
+# (before any personal ~/.config/nvim) and can still be overridden per-user.
+# Enables termguicolors so the default theme renders in 24-bit colour instead
+# of a muddy 256-colour fallback. Pairs with kitty-terminfo (installed above).
+COPY rootfs/etc/xdg/nvim/sysinit.vim /etc/xdg/nvim/sysinit.vim
+
 # ── Entrypoint ────────────────────────────────────────────────────────
 COPY rootfs/usr/local/lib/pi-devbox/ /usr/local/lib/pi-devbox/
 # Image-baked skills + the global-AGENTS append snippet. Under /usr/local so a
diff --git a/README.md b/README.md
index b2bfae6..9f8ccf9 100644
--- a/README.md
+++ b/README.md
@@ -59,6 +59,12 @@ comfort level — if you'd rather not use a vi-style editor, `nano` and `micro`
 are both non-modal. Set your preference with `export EDITOR=micro` (or `nano`)
 in your shell profile, and/or `git config --global core.editor micro`.
 
+Neovim ships with a system-wide default (`/etc/xdg/nvim/sysinit.vim`) that turns
+on `termguicolors`, so its colours render in 24-bit instead of a muddy
+256-colour fallback over ssh/kitty. The `kitty-terminfo` entry is also bundled
+so `TERM=xterm-kitty` is understood. Override either in your own
+`~/.config/nvim`.
+
 ### Document and image tooling
 
 - `pandoc` — universal Markdown↔HTML/Org/RST/etc. converter
diff --git a/rootfs/etc/xdg/nvim/sysinit.vim b/rootfs/etc/xdg/nvim/sysinit.vim
new file mode 100644
index 0000000..85c7281
--- /dev/null
+++ b/rootfs/etc/xdg/nvim/sysinit.vim
@@ -0,0 +1,18 @@
+" pi-devbox — system-wide Neovim defaults.
+"
+" This is Neovim's *system vimrc*: it loads for every user before any personal
+" ~/.config/nvim, and personal configs can still override it.
+"
+" Enable 24-bit ("true") colour. Without it, Neovim's default theme is squeezed
+" into a 256-colour palette where strings/comments become a muddy, low-contrast
+" dark colour — a common complaint over ssh/kitty where COLORTERM often isn't
+" propagated into the container. Modern terminals (kitty, WezTerm, iTerm2,
+" Alacritty, ...) all support true colour; the bundled kitty-terminfo also lets
+" Neovim auto-detect it, but forcing it here guarantees readable colour
+" regardless of how the terminal type / COLORTERM reach the container.
+"
+"   Opt out for a session:  :set notermguicolors
+"   Override permanently:   set your own value in ~/.config/nvim/init.lua
+if has('termguicolors')
+  set termguicolors
+endif
diff --git a/scripts/smoke-test.sh b/scripts/smoke-test.sh
index 174b2bd..28b7d88 100755
--- a/scripts/smoke-test.sh
+++ b/scripts/smoke-test.sh
@@ -76,6 +76,8 @@ run "uv"              "uv --version"
 run "nvim"            "nvim --version"
 run "nano"            "nano --version"
 run "micro"           "micro --version"
+run "kitty-terminfo"  "infocmp -x xterm-kitty >/dev/null 2>&1"
+run "nvim true-colour default (sysinit.vim)" "nvim --headless -c 'lua os.exit(vim.o.termguicolors and 0 or 1)'"
 run "mempalace-mcp"   "mempalace-mcp --help"
 # v1.0.0 base additions — verify presence and basic functionality.
 run "pandoc"          "pandoc --version"