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

3 files changed, 62 insertions, 13 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`.
diff --git a/docs/design.typ b/docs/design.typ
index 1c50cfde..d49be3e6 100644
--- a/docs/design.typ
+++ b/docs/design.typ
@@ -479,7 +479,12 @@ output buffer whose rows are those very commands — execute a row (Tab, middle
 click) and the theme goes on; n/N select such a row WHOLE, since a command
 line holds no place to pick out of it — the third grain of that motion, the
 other two being one stop per ROW in a results list (the location at its head,
-never the matched text after it) and every look-able word in free text.
+never the matched text after it) and every look-able word in free text. Native
+shells also accept `ThemeFile <path>`: one complete ZON `Theme`, loaded at
+runtime and, where document watches are available, watched with the same
+parent-directory/rename-over semantics. `DumpThemes` materializes the compiled
+ring under `<config>/themes/builtin/`, providing the schema and a copyable
+starting point without adding inheritance or a second theme vocabulary.
 Colors toggles
 all recolor passes; Debug stats overlay; Dump writes state ZON.
 
diff --git a/docs/web.md b/docs/web.md
index a6e2e923..578654d3 100644
--- a/docs/web.md
+++ b/docs/web.md
@@ -59,7 +59,8 @@ real native TTY dump of that same selection; its top and bottom launcher
 snapshots jointly cover the complete list before opening `build.zig`.
 
 What is genuinely absent is narrower than "no IO". The module has no threads
-and no host filesystem, so there is no startup config file, LOOK resolves
+and no host filesystem, so there is no startup config directory, init file,
+ThemeFile, or DumpThemes; LOOK resolves
 against the build-generated source archive rather than disk, and no language
 BACKEND is compiled in (`zls_backend` is off for wasm — which also means
 `lsp.supports` is empty, so the core never even raises a language query there;