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