docs: add RUNTIME_HOOKS.md and link from README

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...]
+```