file_watch + builtins + config: richer watch semantics, new builtins, config docs

1 files changed, 54 insertions, 11 deletions

diff --git a/docs/config.md b/docs/config.md
index 6485d46a..14854ccf 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -1,17 +1,19 @@
 # Startup configuration
 
-Native pardes builds read a per-user `pardes` file before the first frame:
+Native pardes builds use a per-user `pardes` configuration directory. Its
+main command file is named `init`:
 
-- Unix: `$XDG_CONFIG_HOME/pardes`, falling back to `~/.config/pardes`.
-- macOS: `$XDG_CONFIG_HOME/pardes` when that variable is set, otherwise
-  `~/Library/Application Support/pardes`.
-- Windows: `%LOCALAPPDATA%\pardes`, with `%USERPROFILE%\AppData\Local\pardes`
-  as the fallback.
+- Unix: `$XDG_CONFIG_HOME/pardes/init`, falling back to
+  `~/.config/pardes/init`.
+- macOS: `$XDG_CONFIG_HOME/pardes/init` when that variable is set, otherwise
+  `~/Library/Application Support/pardes/init`.
+- Windows: `%LOCALAPPDATA%\pardes\init`, with
+  `%USERPROFILE%\AppData\Local\pardes\init` as the fallback.
 
 On the two unixes `XDG_CONFIG_HOME` counts only when it is ABSOLUTE, as the
 XDG base-directory specification requires; an empty or relative value falls
-back to the home-directory form. Windows never consults it. A file of 1 MiB or
-more, or one that cannot be read, is treated as no file at all — the path
+back to the home-directory form. Windows never consults it. An `init` of 1 MiB
+or more, or one that cannot be read, is treated as no file at all — the path
 still resolves, because "nothing is there yet" is the answer `Config` exists
 to give. There is one case with no path at all: a native launch with no `HOME`
 set, which `Config` reports as such.
@@ -63,9 +65,9 @@ Wrap
 
 A line matches a builtin whose name takes NO argument only as that whole word:
 `Kill` runs, `Kill something` does not. Builtins that take one (`Theme`,
-`Font`, `TaglineSize`, `Shell`, `Restore`, `Find`, `Grep`, `Rename`,
-`WsSymbols`, `Look`, `Exec`, `EffectCode`) take everything after the name as
-the argument.
+`ThemeFile`, `Font`, `TaglineSize`, `Shell`, `Restore`, `Find`, `Grep`,
+`Rename`, `WsSymbols`, `Look`, `Exec`, `EffectCode`) take everything after the
+name as the argument.
 
 `Theme <name>` wants one of the 228 names in the ring. Do not derive the
 spelling — read it off `ThemeSel` (`SPC t t`), which lists every one as the
@@ -76,6 +78,47 @@ that came from zed with `_zed` so it cannot collide with a helix theme of the
 same name (zed's "Ayu Mirage" is `ayu_mirage_zed`; `ayu_mirage` is helix's).
 A name that is not in the ring is ignored.
 
+## Runtime theme files
+
+`ThemeFile <path>` loads one complete theme from a `.zon` file. An absolute
+path is used as written; a relative path is resolved from the `pardes`
+configuration directory, not from the process working directory. A typical
+layout is:
+
+```text
+~/.config/pardes/
+├── init
+└── themes/
+    └── mine.zon
+```
+
+and the corresponding init line is:
+
+```text
+ThemeFile themes/mine.zon
+```
+
+After a successful load, hosts with document live reload watch the path with
+the same parent-directory mechanism, so in-place writes and editor-style
+rename-over saves reload the theme live. A malformed or incomplete save does
+not replace the last valid theme; fixing and saving the file applies the next
+valid snapshot. Selecting a compiled theme with `Theme <name>` or `NextColor`
+stops the custom-file watch.
+
+Execute `DumpThemes` to write every theme compiled into the executable to:
+
+```text
+<config directory>/themes/builtin/<name>.zon
+```
+
+The command replaces those generated reference files but leaves unrelated
+files alone. Copy one into `themes/`, rename it, change its `.name`, and use it
+as the starting point for a custom theme. The dumped file is also the complete
+format: one ZON struct with the theme name, the fifteen RGB roles, nullable
+`bg`/`fg`, and either a 16-color RGB `palette` or `null`. RGB values are
+three-byte arrays, and hex literals are accepted. There is no inheritance or
+partial override layer.
+
 `Shell <name>` sets the binary that the NEXT terminal pane execs; panes
 already open keep the shell they are running. A bare name is resolved against
 the handful of directories a shell actually lives in, not `$PATH`.