ThemeSel in sections: acme and lapis with the current themes, helix and dark as legacy, a section per ported family

The picker's headings come from colors.theme_groups instead of one split at
native_theme_count, so acme (current, matched to plan9port acme's source)
no longer sits under a legacy heading. Ring order follows the sections:
the fifteen pardes palettes, acme, lapis, the faithful ports a family at a
time, then helix and dark, then the imports. An imported theme whose name a
port takes gets _helix, as zed's carry _zed.

1 files changed, 28 insertions, 4 deletions

diff --git a/docs/themes.md b/docs/themes.md
index 38596819..9c8e91a5 100644
--- a/docs/themes.md
+++ b/docs/themes.md
@@ -6,9 +6,10 @@ terminals together. `orchard` is the initial theme.
 Execute `Theme <name>` anywhere, or open `ThemeSel` with `SPC t t` and select
 a theme's command. Put the same command in your [startup configuration](config.md)
 to keep a preference. `NextColor` cycles through the native themes first,
-then the retained `helix`, `dark` and `acme` themes and imported palettes.
-`ThemeSel` groups the new palettes under `Pardes themes`, followed by
-`Legacy and imported themes`; its navigation skips the section headings.
+then `acme` and `lapis`, the [faithful ports](#faithful-ports), the legacy
+`helix` and `dark`, and the imported palettes. `ThemeSel` shows the same
+order in sections: `Pardes themes`, one per ported family, `Legacy themes`
+and `Imported themes (helix, zed)`; its navigation skips the section headings.
 See the [Agave visual review](ui-review.md) for the original six-palette gallery.
 
 | Theme | Character | Page | Accent |
@@ -58,7 +59,8 @@ Their local references are `vendor/themes/dark_plus.toml`,
 `material_oceanic.toml` (and its `material_deep_ocean.toml` parent),
 `solarized_dark.toml`, `monokai_pro.toml`, `autumn.toml`, and the Gruvbox Dark
 entry in `gruvbox.json`. The original imported themes remain selectable under
-their existing names; the adaptations have distinct Pardes names and do not
+their existing names (one a [faithful port](#faithful-ports) now holds gains
+`_helix`, as in `dracula_helix`); the adaptations have distinct Pardes names and do not
 claim upstream affiliation. Existing vendor provenance and licenses remain
 with those sources.
 
@@ -81,6 +83,28 @@ no more than 1.6:1, keeping focus changes quiet. ANSI black is exempt because ap
 also use it as a background. These are palette checks, not a guarantee about
 arbitrary terminal escape sequences, reversed colors or shader effects.
 
+## Faithful ports
+
+These are well-known themes taken as close to their originals as pardes can
+draw them: every colour the original has (page, text, selection, syntax, line
+numbers, diagnostics, terminal ANSI) is its own, read out of the original's
+files, and each theme file cites the file and line of every value. The loose
+adaptations above (`forge`, `solarium`, `spectrum`, ...) stay as they are.
+
+pardes has one colour each for keywords, strings, numbers and comments, so a
+theme that splits a kind (VS Code's control-flow keywords) keeps its main
+one. A pane's tag is the original's window bar (vim's `StatusLine` and
+`StatusLineNC`, emacs's `mode-line` and `mode-line-inactive`) or, in a tabbed
+editor, its tab. What the original lacks (grips, a scroll column) comes from
+its own palette. Where a chrome colour misses one of pardes's floors (rules
+1.5:1 off the page, the focused tag 1.5:1 off the unfocused one on a dark
+page and 1.25:1 on a light one, tag text 4.5:1), only that chrome colour
+moves, just far enough, and the file's header says so. Text, syntax and ANSI
+are never adjusted.
+
+| Family | Themes | Source |
+| --- | --- | --- |
+
 ## Make a theme your own
 
 Run `DumpThemes` to export complete `.zon` files below the configuration