1 files changed, 39 insertions, 0 deletions
diff --git a/desktop/modules/autostart/README.md b/desktop/modules/autostart/README.md
new file mode 100644
index 0000000..eea0c53
--- /dev/null
+++ b/desktop/modules/autostart/README.md
@@ -0,0 +1,39 @@
+# autostart
+
+What Hyprland launches at login: hypr-theme's `sections/autostart.lua`, which
+this page owns. It lives in the settings window, not the drawer, because it is
+set once and left alone.
+
+Adding is guided, because a wrong entry only shows at the next login. Pick
+an installed app (the launcher's `.desktop` entries, Exec line minus its
+`%U`-style field codes; terminal apps are left out and go through Command), or
+type a command. Either way the program is looked up on PATH as it changes, past
+`VAR=value`, `env`, `exec` and into `sh -c '...'`, and Add stays disabled until
+it resolves. A workspace (the scratchpad, 1 to 8, or any name in use) and
+silent become a `[workspace <name> silent]` rule. Try starts the composed line
+through `hyprctl dispatch hl.dsp.exec_cmd(...)`, so the rule applies as at
+login. Existing rows show their rule and a red mark when their program is no
+longer found. They have no Try: they already ran at login, and a second start
+stacks a second instance. Arguments are not checked, only the program.
+
+The file is walked line by line. A line that is exactly `hl.exec_cmd("...")`
+is an entry, the same line behind `-- ` is a disabled entry, and every other
+line passes through untouched. The switch comments a line in and out, Remove
+asks once and deletes it, and the field at the bottom adds an enabled line
+before the hook's closing `end)`. The file therefore carries no comments,
+since deleting an entry would orphan the one above it; the reason behind each
+line lives in the launched project's own docs.
+
+Every edit is made on the text as last read and refused if its line is no
+longer what was parsed, so an edit in an editor meanwhile is never
+overwritten blind: the page reloads and asks to try again. Writes are atomic,
+because Hyprland reloads its config on every change and must never see a
+half-written file.
+
+`hyprland.start` fires once per session, so a change applies at next login.
+
+Not handled: a command spread over several lines or written as a `[[...]]`
+long string is not an entry and is left alone, and only the `\"` and `\\`
+escapes are decoded.
+
+Check: `node desktop/modules/autostart/test_autostart.js`.