bernardo/Nomarchy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: implement component-based architecture for enhanced maintainability

Browse Source 
- Reorganize directory structure into core/, features/, and themes/
- Colocate application Nix logic, configs, scripts, and theme overrides
- Implement 'Inversion of Control' for theming: apps now pull theme-specific layouts
- Update flake.nix and shared library paths to match the new structure
- Document the new Feature-Centric architecture in README.md
This commit is contained in:
Bernardo Magri
2026-04-12 14:51:15 +01:00
parent a9ee79a5ce
commit bbdf34ced8
535 changed files with 119 additions and 127 deletions
Download Patch File Download Diff File Expand all files Collapse all files

366
core/home/config/nomarchy-skill/SKILL.md Normal file
View File

@@ -0,0 +1,366 @@
---
name: nomarchy
description: >
REQUIRED for end-user customization of Linux desktop, window manager, or system config.
Use when editing ~/.config/hypr/, ~/.config/waybar/, ~/.config/walker/,
~/.config/alacritty/, ~/.config/kitty/, ~/.config/ghostty/, ~/.config/mako/,
or ~/.config/nomarchy/. Triggers: Hyprland, window rules, animations, keybindings,
monitors, gaps, borders, blur, opacity, waybar, walker, terminal config, themes,
wallpaper, night light, idle, lock screen, screenshots, layer rules, workspace
settings, display config, and user-facing nomarchy commands. Excludes Nomarchy
source development in ~/.local/share/nomarchy/ and nomarchy-dev-* workflows.
---
# Nomarchy Skill
Manage [Nomarchy](https://nomarchy.org/) Linux systems - a beautiful, modern, opinionated Arch Linux distribution with Hyprland.
This skill is for end-user customization on installed systems.
It is not for contributing to Nomarchy source code.
## When This Skill MUST Be Used
**ALWAYS invoke this skill for end-user requests involving ANY of these:**
- Editing ANY file in `~/.config/hypr/` (window rules, animations, keybindings, monitors, etc.)
- Editing ANY file in `~/.config/waybar/`, `~/.config/walker/`, `~/.config/mako/`
- Editing terminal configs (alacritty, kitty, ghostty)
- Editing ANY file in `~/.config/nomarchy/`
- Window behavior, animations, opacity, blur, gaps, borders
- Layer rules, workspace settings, display/monitor configuration
- Themes, wallpapers, fonts, appearance changes
- User-facing `nomarchy-*` commands (`nomarchy-theme-*`, `nomarchy-refresh-*`, `nomarchy-restart-*`, etc.)
- Screenshots, screen recording, night light, idle behavior, lock screen
**If you're about to edit a config file in ~/.config/ on this system, STOP and use this skill first.**
**Do NOT use this skill for Nomarchy development tasks** (editing files in `~/.local/share/nomarchy/`, creating migrations, or running `nomarchy-dev-*` workflows).
## Critical Safety Rules
**For end-user customization tasks, NEVER modify anything in `~/.local/share/nomarchy/`** - but READING is safe and encouraged.
This directory contains Nomarchy's source files managed by git. Any changes will be:
- Lost on next `nomarchy-update`
- Cause conflicts with upstream
- Break the system's update mechanism
```
~/.local/share/nomarchy/ # READ-ONLY - NEVER EDIT (reading is OK)
├── bin/ # Source scripts (symlinked to PATH)
├── config/ # Default config templates
├── themes/ # Stock themes
├── default/ # System defaults
├── migrations/ # Update migrations
└── install/ # Installation scripts
```
**Reading `~/.local/share/nomarchy/` is SAFE and useful** - do it freely to:
- Understand how nomarchy commands work: `cat $(which nomarchy-theme-set)`
- See default configs before customizing: `cat ~/.local/share/nomarchy/config/waybar/config.jsonc`
- Check stock theme files to copy for customization
- Reference default hyprland settings: `cat ~/.config/nomarchy/default/hypr/*`
**Always use these safe locations instead:**
- `~/.config/` - User configuration (safe to edit)
- `~/.config/nomarchy/themes/<custom-name>/` - Custom themes (must be real directories)
- `~/.config/nomarchy/hooks/` - Custom automation hooks
If the request is to develop Nomarchy itself, this skill is out of scope. Follow repository development instructions instead of this skill.
## System Architecture
Nomarchy is built on:
| Component | Purpose | Config Location |
|-----------|---------|-----------------|
| **Arch Linux** | Base OS | `/etc/`, `~/.config/` |
| **Hyprland** | Wayland compositor/WM | `~/.config/hypr/` |
| **Waybar** | Status bar | `~/.config/waybar/` |
| **Walker** | App launcher | `~/.config/walker/` |
| **Alacritty/Kitty/Ghostty** | Terminals | `~/.config/<terminal>/` |
| **Mako** | Notifications | `~/.config/mako/` |
| **SwayOSD** | On-screen display | `~/.config/swayosd/` |
## Command Discovery
Nomarchy provides ~145 commands following `nomarchy-<category>-<action>` pattern.
```bash
# List all nomarchy commands
compgen -c | grep -E '^nomarchy-' | sort -u
# Find commands by category
compgen -c | grep -E '^nomarchy-theme'
compgen -c | grep -E '^nomarchy-restart'
# Read a command's source to understand it
cat $(which nomarchy-theme-set)
```
### Command Categories
| Prefix | Purpose | Example |
|--------|---------|---------|
| `nomarchy-refresh-*` | Reset config to defaults (backs up first) | `nomarchy-refresh-waybar` |
| `nomarchy-restart-*` | Restart a service/app | `nomarchy-restart-waybar` |
| `nomarchy-toggle-*` | Toggle feature on/off | `nomarchy-toggle-nightlight` |
| `nomarchy-theme-*` | Theme management | `nomarchy-theme-set <name>` |
| `nomarchy-install-*` | Install optional software | `nomarchy-install-docker-dbs` |
| `nomarchy-launch-*` | Launch apps | `nomarchy-launch-browser` |
| `nomarchy-cmd-*` | System commands | `nomarchy-cmd-screenshot` |
| `nomarchy-pkg-*` | Package management | `nomarchy-pkg-install <pkg>` |
| `nomarchy-setup-*` | Initial setup tasks | `nomarchy-setup-fingerprint` |
| `nomarchy-update-*` | System updates | `nomarchy-update` |
## Configuration Locations
### Hyprland (Window Manager)
```
~/.config/hypr/
├── hyprland.conf # Main config (sources others)
├── bindings.conf # Keybindings
├── monitors.conf # Display configuration
├── input.conf # Keyboard/mouse settings
├── looknfeel.conf # Appearance (gaps, borders, animations)
├── envs.conf # Environment variables
├── autostart.conf # Startup applications
├── hypridle.conf # Idle behavior (screen off, lock, suspend)
├── hyprlock.conf # Lock screen appearance
└── hyprsunset.conf # Night light / blue light filter
```
**Key behaviors:**
- Hyprland auto-reloads on config save (no restart needed for most changes)
- Use `hyprctl reload` to force reload
- Use `nomarchy-refresh-hyprland` to reset to defaults
### Waybar (Status Bar)
```
~/.config/waybar/
├── config.jsonc # Bar layout and modules (JSONC format)
└── style.css # Styling
```
**Waybar does NOT auto-reload.** You MUST run `nomarchy-restart-waybar` after any config changes.
**Commands:** `nomarchy-restart-waybar`, `nomarchy-refresh-waybar`, `nomarchy-toggle-waybar`
### Terminals
```
~/.config/alacritty/alacritty.toml
~/.config/kitty/kitty.conf
~/.config/ghostty/config
```
**Command:** `nomarchy-restart-terminal`
### Other Configs
| App | Location |
|-----|----------|
| btop | `~/.config/btop/btop.conf` |
| fastfetch | `~/.config/fastfetch/config.jsonc` |
| lazygit | `~/.config/lazygit/config.yml` |
| starship | `~/.config/starship.toml` |
| git | `~/.config/git/config` |
| walker | `~/.config/walker/config.toml` |
## Safe Customization Patterns
### Pattern 1: Edit User Config Directly
For simple changes, edit files in `~/.config/`:
```bash
# 1. Read current config
cat ~/.config/hypr/bindings.conf
# 2. Backup before changes
cp ~/.config/hypr/bindings.conf ~/.config/hypr/bindings.conf.bak.$(date +%s)
# 3. Make changes with Edit tool
# 4. Apply changes
# - Hyprland: auto-reloads on save (no restart needed)
# - Waybar: MUST restart with nomarchy-restart-waybar
# - Walker: MUST restart with nomarchy-restart-walker
# - Terminals: MUST restart with nomarchy-restart-terminal
```
### Pattern 2: Make a new theme
1. Create a directory under ~/.config/nomarchy/themes.
2. See how an existing theme is done via ~/.local/share/nomarchy/themes/catppuccin.
3. Download a matching background (or several) from the internet and put them in ~/.config/nomarchy/themes/[name-of-new-theme]
4. When done with the theme, run nomarchy-theme-set "Name of new theme"
### Pattern 3: Use Hooks for Automation
Create scripts in `~/.config/nomarchy/hooks/` to run automatically on events:
```bash
# Available hooks (see samples in ~/.config/nomarchy/hooks/):
~/.config/nomarchy/hooks/
├── theme-set # Runs after theme change (receives theme name as $1)
├── font-set # Runs after font change
└── post-update # Runs after nomarchy-update
```
Example hook (`~/.config/nomarchy/hooks/theme-set`):
```bash
#!/bin/bash
THEME_NAME=$1
echo "Theme changed to: $THEME_NAME"
# Add custom actions here
```
### Pattern 4: Reset to Defaults -- ALWAYS SEEK USER CONFIRMATION BEFORE RUNNING
When customizations go wrong:
```bash
# Reset specific config (creates backup automatically)
nomarchy-refresh-waybar
nomarchy-refresh-hyprland
# The refresh command:
# 1. Backs up current config with timestamp
# 2. Copies default from ~/.local/share/nomarchy/config/
# 3. Restarts the component
```
## Common Tasks
### Themes
```bash
nomarchy-theme-list # Show available themes
nomarchy-theme-current # Show current theme
nomarchy-theme-set <name> # Apply theme (use "Tokyo Night" not "tokyo-night")
nomarchy-theme-next # Cycle to next theme
nomarchy-theme-bg-next # Cycle wallpaper
nomarchy-theme-install <url> # Install from git repo
```
### Keybindings
Edit `~/.config/hypr/bindings.conf`. Format:
```
bind = SUPER, Return, exec, xdg-terminal-exec
bind = SUPER, Q, killactive
bind = SUPER SHIFT, E, exit
```
View current bindings: `nomarchy-menu-keybindings --print`
**IMPORTANT: When re-binding an existing key:**
1. First check existing bindings: `nomarchy-menu-keybindings --print`
2. If the key is already bound, you MUST add an `unbind` directive BEFORE your new `bind`
3. Inform the user what the key was previously bound to
Example - rebinding SUPER+F (which is bound to fullscreen by default):
```
# Unbind existing SUPER+F (was: fullscreen)
unbind = SUPER, F
# New binding for file manager
bind = SUPER, F, exec, nautilus
```
Always tell the user: "Note: SUPER+F was previously bound to fullscreen. I've added an unbind directive to override it."
### Display/Monitors
Edit `~/.config/hypr/monitors.conf`. Format:
```
monitor = eDP-1, 1920x1080@60, 0x0, 1
monitor = HDMI-A-1, 2560x1440@144, 1920x0, 1
```
List monitors: `hyprctl monitors`
### Window Rules
**CRITICAL: Hyprland window rules syntax changes frequently between versions.**
Before writing ANY window rules, you MUST fetch the current documentation from the official Hyprland wiki:
- https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Window-Rules.md
DO NOT rely on cached or memorized window rule syntax. The format has changed multiple times and using outdated syntax will cause errors or unexpected behavior.
Window rules go in `~/.config/hypr/hyprland.conf` or a sourced file. Always verify the current syntax from the wiki first.
### Fonts
```bash
nomarchy-font-list # Available fonts
nomarchy-font-current # Current font
nomarchy-font-set <name> # Change font
```
### System
```bash
nomarchy-update # Full system update
nomarchy-version # Show Nomarchy version
nomarchy-debug --no-sudo --print # Debug info (ALWAYS use these flags)
nomarchy-lock-screen # Lock screen
nomarchy-system-shutdown # Shutdown
nomarchy-system-reboot # Reboot
```
**IMPORTANT:** Always run `nomarchy-debug` with `--no-sudo --print` flags to avoid interactive sudo prompts that will hang the terminal.
## Troubleshooting
```bash
# Get debug information (ALWAYS use these flags to avoid interactive prompts)
nomarchy-debug --no-sudo --print
# Upload logs for support
nomarchy-upload-log
# Reset specific config to defaults
nomarchy-refresh-<app>
# Refresh specific config file
# config-file path is relative to ~/.config/
# eg. nomarchy-refresh-config hypr/hyprlock.conf will refresh ~/.config/hypr/hyprlock.conf
nomarchy-refresh-config <config-file>
# Full reinstall of configs (nuclear option)
nomarchy-reinstall
```
## Decision Framework
When user requests system changes:
1. **Is it a stock nomarchy command?** Use it directly
2. **Is it a config edit?** Edit in `~/.config/`, never `~/.local/share/nomarchy/`
3. **Is it a theme customization?** Create a NEW custom theme directory
4. **Is it automation?** Use hooks in `~/.config/nomarchy/hooks/`
5. **Is it a package install?** Use `nomarchy-pkg-add` (or `nomarchy-pkg-aur-add` for AUR-only packages)
6. **Unsure if command exists?** Search with `compgen -c | grep nomarchy`
## Out of Scope
This skill intentionally does not cover Nomarchy source development. Do not use this skill for:
- Editing files in `~/.local/share/nomarchy/` (`bin/`, `config/`, `default/`, `themes/`, `migrations/`, etc.)
- Creating or editing migrations
- Running `nomarchy-dev-*` commands
## Example Requests
- "Change my theme to catppuccin" -> `nomarchy-theme-set catppuccin`
- "Add a keybinding for Super+E to open file manager" -> Check existing bindings first, add `unbind` if needed, then add `bind` in `~/.config/hypr/bindings.conf`
- "Configure my external monitor" -> Edit `~/.config/hypr/monitors.conf`
- "Make the window gaps smaller" -> Edit `~/.config/hypr/looknfeel.conf`
- "Set up night light to turn on at sunset" -> `nomarchy-toggle-nightlight` or edit `~/.config/hypr/hyprsunset.conf`
- "Customize the catppuccin theme colors" -> Create `~/.config/nomarchy/themes/catppuccin-custom/` by copying from stock, then edit
- "Run a script every time I change themes" -> Create `~/.config/nomarchy/hooks/theme-set`
- "Reset waybar to defaults" -> `nomarchy-refresh-waybar`