docs: the sbbuilder settings pages

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2 files changed, 35 insertions, 0 deletions

diff --git a/desktop/README.md b/desktop/README.md
index bffd9b1..555095e 100644
--- a/desktop/README.md
+++ b/desktop/README.md
@@ -96,6 +96,7 @@ and flashes it, so a page needs no highlight code of its own.
     modules/autostart/   Hyprland's autostart.lua, in the settings window
     modules/assistant/   desktop-assistant's config, tools, and Ask presets
     modules/qtmaildir/   qtmaildir.conf: general, compose, accounts, tags and keys
+    modules/sbbuilder/   sb-builder's GUI config and the build VM helper's config
 
 Sound, mail, vm, network, bluetooth, kdeconnect and ai each carry their own README.
 So does appearance, for its five settings pages.
diff --git a/desktop/modules/sbbuilder/README.md b/desktop/modules/sbbuilder/README.md
new file mode 100644
index 0000000..73bfe51
--- /dev/null
+++ b/desktop/modules/sbbuilder/README.md
@@ -0,0 +1,34 @@
+# sbbuilder
+
+Two settings pages, under SB Builder, for sb-builder's two configs:
+
+- **Desktop**: the GUI's `$XDG_CONFIG_HOME/sb-builder/config.toml`, edited
+  in place. sb-builder watches the file, so a save applies to a running GUI
+  (if the file existed when the GUI started; otherwise File, Reload config
+  once). VM control is a switch: sb-builder spells "no VM control" as
+  `domain = ""`, and an emptied field means the default instead.
+- **Build VM**: the helper's `/etc/sb-builder/config.toml`, read with
+  `ssh <target> sbb-remote config-get` and written with `config-set`, the
+  draft on stdin. The helper validates it and keeps the old file as `.bak`;
+  the page never writes it over ssh by hand. `<target>` and the ssh options
+  come from the desktop config as saved. With the VM down the page is
+  read-only until Reload gets an answer. One ssh runs at a time, and a save
+  first re-reads the file, refusing if it changed on the VM meanwhile.
+
+Both follow the settings window's draft rules (`desktop/README.md`). A field
+is typed after its default: lists are words split on spaces (a list entry
+holding a space is a `ponytail:` ceiling: edit the file), numbers are
+range-checked. An emptied manifest URL holds Save back rather than unsetting
+the key, which would remove the row being typed in. The desktop defaults are
+copied from sb-builder's `config.py`, a `ponytail:` ceiling in `Sbb.qml`;
+the VM ones come from the helper.
+
+`Toml.js` edits a line at a time so comments survive, as qtmaildir's
+`Ini.js` does: unset comments a key out with `#`, set reactivates it. It
+handles one-line values only and refuses to edit a value with anything but a
+comment after it, multi-line strings and arrays included, rather than write
+a duplicate key. Not recognised: CRLF line endings, `[ spaced ]` and
+`[[array]]` headers, 'literal' keys; neither file uses them. The fields are
+qtmaildir's `Setting` and `BoolSetting`, given a `store`.
+
+Check: `node desktop/modules/sbbuilder/test_toml.js`.