update docs

2026-04-04 08:40:17 -04:00
parent 081e4c587c
commit 0cff2069b7
18 changed files with 888 additions and 468 deletions
@@ -38,3 +38,17 @@ Run `theme list` in a Bare OS shell. Examples: `default`, `nord`, `dracula`, `gr
 ## Related session variables

 See [environment variables reference](../reference/environment-and-posix-appendix.md#14-environment-variables-complete-list): `BARE_OS_THEME`, `BARE_OS_COLOR_DEPTH`, `LS_COLORS`, `BARE_OS_DIRCOLORS`, and host passthrough `TERM` / `COLORTERM`.
+
+---
+
+## Matching host and guest colors
+
+Bare OS computes **`LS_COLORS`** from **`dircolors`** data and the active theme preset (**`bare-os-theme-presets.js`**). If the **guest** looks correct but your **host** terminal looks washed out, import the matching file from this directory (Alacritty, Warp, or iTerm). If the **guest** looks wrong, set **`BARE_OS_COLOR_DEPTH`** to **`256`** or **`truecolor`** to match what your emulator advertises via **`COLORTERM`**, then run **`theme set <name>`** inside the session. See [Handbook — Chapter 7: Themes, LS_COLORS, and real terminals](../../handbook/07-operations-and-development.md#themes-ls_colors-and-real-terminals).
+
+---
+
+## Contributing a new preset
+
+1. Add the preset object to [`packages/bare-os-booter/lib/bare-os-theme-presets.js`](../../packages/bare-os-booter/lib/bare-os-theme-presets.js) (colors for **`LS_COLORS`** / **`dircolors`** generation).
+2. Add host theme files here using the existing naming convention (`alacritty-<preset>.yml`, `warp-<preset>.yaml`, `iterm-<preset>.itermcolors`).
+3. Document the preset name in this README under **Preset names** so operators can discover it.