docs: add RUNTIME_HOOKS.md and link from README

README.md

@@ -84,7 +84,7 @@ Add user-level packages, aliases, and dotfiles here.
 nomarchy.home.terminal = "kitty";
 ```
 
-For the full list of `nomarchy.*` options you can set in `system.nix` and `home.nix`, see the [Options Reference](docs/OPTIONS.md). Hit a rebuild error? Check [Troubleshooting](docs/TROUBLESHOOTING.md). For where the project is heading next, see the [Roadmap](docs/ROADMAP.md).
+For the full list of `nomarchy.*` options you can set in `system.nix` and `home.nix`, see the [Options Reference](docs/OPTIONS.md). For custom automation, see [Runtime Hooks](docs/HOOKS.md). Hit a rebuild error? Check [Troubleshooting](docs/TROUBLESHOOTING.md). For where the project is heading next, see the [Roadmap](docs/ROADMAP.md).
 
 ### Applying Changes
 After editing your files, apply them instantly. **IMPORTANT:** Nomarchy requires the `--impure` flag for evaluation. You **MUST** use the following aliases rather than standard NixOS commands:

docs/HOOKS.md

@@ -0,0 +1,57 @@
+# Nomarchy Runtime Hooks
+
+Hooks allow you to run custom bash scripts when specific system events occur. They are the primary way to extend Nomarchy's behavior without modifying the core Nix configuration.
+
+## 1. How it works
+
+Hooks are simple bash scripts located in `~/.config/nomarchy/hooks/`. 
+
+When a supported event occurs, Nomarchy checks for a file with the corresponding name in that directory. If the file exists, it is executed.
+
+- **Location:** `~/.config/nomarchy/hooks/<hook-name>`
+- **Language:** Bash (or any executable script with a shebang).
+- **Execution:** Synchronous. The calling Nomarchy script waits for your hook to finish.
+
+## 2. Available Hooks
+
+| Hook Name | Triggered when... | Arguments |
+| --- | --- | --- |
+| `post-install` | The `nomarchy-welcome` wizard finishes. | None |
+| `post-update` | `nomarchy-env-update` finishes successfully. | None |
+| `theme-set` | A new system theme is applied. | `$1`: theme-id (e.g. `nord`) |
+| `font-set` | A new system font is applied. | `$1`: font name (e.g. `JetBrainsMono Nerd Font`) |
+| `battery-low` | Battery drops below 15% (laptop only). | `$1`: Current percentage |
+
+## 3. Examples
+
+### Auto-sync dotfiles after update
+Create `~/.config/nomarchy/hooks/post-update`:
+```bash
+#!/bin/bash
+notify-send "Nomarchy" "Syncing personal dotfiles..."
+git -C ~/Projects/dotfiles pull && git -C ~/Projects/dotfiles push
+```
+
+### Apply custom color overrides after theme change
+Create `~/.config/nomarchy/hooks/theme-set`:
+```bash
+#!/bin/bash
+# Re-apply a specific transparency hack that Stylix might have overwritten
+hyprctl keyword decoration:active_opacity 0.95
+```
+
+## 4. Samples
+
+Nomarchy ships sample hooks with the `.sample` extension. You can use these as a starting point by copying them:
+
+```bash
+cp ~/.config/nomarchy/hooks/post-install.sample ~/.config/nomarchy/hooks/post-install
+chmod +x ~/.config/nomarchy/hooks/post-install
+```
+
+## 5. Development
+
+If you want to trigger a hook manually for testing:
+```bash
+nomarchy-hook <name> [args...]
+```