nixy/docs/Programs.md

# Programs & Applications Configuration Guide

This document describes all the programs, utilities, and applications configured in the `home/programs/` directory via home-manager modules. These configurations define the **user-level software environment** including:

- **Terminal emulators** and multiplexers
- **Shell utilities** and enhancements
- **Development tools** and editors
- **Productivity applications** (browsers, file managers, etc.)
- **Media tools** and system utilities
- **Custom bookmark collections**
- **Version control systems**
- **Social and communication tools**

All programs are managed through **home-manager modules**, allowing for declarative, reproducible user environments across multiple machines.

---

## 🖥️ Terminal Environment

### 1. Ghostty (`ghostty/`)

**Type:** Modern terminal emulator written in Zig
**Website:** [https://ghostty.org](https://ghostty.org)
**Configuration:** 66 lines in `home/programs/ghostty/default.nix`

**Features & Configuration:**
- ✅ **Hardware-accelerated** rendering with GPU
- ✅ **Wayland and X11** both supported
- ✅ **Tiling window** integration with custom shaders
- ✅ **Color-themed** to match Stylix color scheme
- ✅ **Integrated Zsh shell** with bidirectional support
- ✅ **Syntax-highlighted** copy on select
- ✅ **Custom cursor shader** (`cursor_warp.glsl`) for visual feedback
- ✅ **Right-click paste disabled** (`confirm-close-surface = false`)
- ✅ **Window manager shortcuts** pre-configured (right-click-tab + modifier for new splits)

**Platform Integration:**
- **TERMINAL** and **TERM** environment variables set to `ghostty`
- **Clipboard permissions** enabled (read and write)
- **Syntax highlighting syntax files** installed via `enableZshIntegration`
- **Vim syntax/indentation support** enabled
- **Custom iLoveTUI theme** created matching Stylix colors

**Terminal WPF Window Padding:**
- X-axis padding: 10px
- Y-axis padding: 10px
- Visual spacing optimized for comfortable reading

**Cursor Configuration:**
- Custom GLSL shader applied: `cursor_warp` for visual feedback
- Shader animation: Always on for smooth cursor experience
- Visual theme automatically syncs with Stylix color palette

**Shell Integration:**
```bash
# Set terminal as default
export TERMINAL=ghostty TERM=ghostty
```

---

### 2. Shell Utilities (`shell/`)

**Type:** Collection of shell productivity enhancements
**Configuration:** Imports all shell modules in `home/programs/shell/default.nix` (11 lines)

**Included Modules:**

#### 2.1. Zsh Shell (`shell/zsh.nix`)

**Type:** Zsh configuration framework
**Configuration:** 196 lines of advanced Zsh setup

**Core Features:**
- ✅ **History management:** 10,000 commands stored, duplicates skipped
- ✅ **Syntax highlighting** with 6 highlighters enabled (main, brackets, pattern, regexp, root, line)
- ✅ **Autosuggestions** enabled for predictable behavior
- ✅ **AI-powered code completion** (`historySubstringSearch`)
- ✅ **Custom aliases** across multiple categories
- ✅ **Global path customization** (Go binaries → $HOME/go/bin)

**Prompt & Aliases System:**
```bash
# Navigation shortcuts
alias cd=z            # Navigate with zoxide
alias ls='eza --icons=always --no-quotes'  # Colors and icons
alias tree='eza --icons=always --tree --no-quotes'

# Editors
alias v=nvim vi=vim   # Default to Neovim
alias notes='nvim ~/notes/index.md --cmd "cd ~/notes" -c ":lua Snacks.picker.smart()"'

# Control flow
alias spt=spotatui     # Quick access to Spotify TUI
alias g=lazygit ga=git add gc='git commit -m' gp='git push'
alias clera clear celar claer='clear' sl=ls  # Typo fixers
```

**Shell Features:**
- **Colored prompt** with truecolor enabled (`COLORTERM=truecolor`)
- **Command-line editing** with history-based suggestions
- **.bat** for syntax-highlighted file viewing
- **.ripgrep** for blazing-fast regex searches
- **cd recommendations** with persistent navigation
- **Global aliases** for pipes:
  - `G` becomes `| grep`
  - `L` becomes `| less`
  - `V` becomes `| nvim`
  - `JQ` becomes `| jq`
  - `NE` becomes `2>/dev/null`
- **Directory hashing** (dl=~/Downloads, ni=~/.config/nixos, de=~/dev, cy=~/Cyber)
- **Bash compatibility mode** (`bindkey -e` for readline bindings)

**Session Management:**
- Automatically exports Go binary path for all shells
- **GNOME Keyring** integration via `SSH_AUTH_SOCK` configuration

**Input Features:**
- **Terminal bell replacement** via foot-pipe commands
- **Command metadata**: `print -n "\e]133;D\e\"` for terminal output formatting
- **Goto-split shortcuts** suggested as comments (Ctrl-i/k/j/l for tiling navigation)

---

#### 2.2. Starship Prompt (`shell/starship.nix`)

**Type:** Fast, customizable shell prompt
**Configuration:** (Auto-imported, no explicit config shown in files)
- **Multi-language prompts** with language-specific symbols
- **Git integration** with branch status and changes
- **Network information** integration
- **Custom Stylix color scheme** integration
- **Performance optimized** (written in Rust, <1ms load time)

**Usage:**
```bash
# Automatically detected and enabled by home-manager
```

---

#### 2.3. Zoxide (`shell/zoxide.nix`)

**Type:** Smarter cd command with cross-platform compatibility
**Package:** Community-maintained, lightweight
**Features:**
- **Fuzzy directory navigation** with smart ranking
- **Cross-platform** (Linux, macOS, Windows WSL)
- **Configuration-free** – learns from your usage patterns

**Typical Usage:**
```bash
z nixos     # Jump to directory based on fuzzy matching
z dev/cyber # Fuzzy partial matching
```

---
#### 2.4. FZF (`shell/fzf.nix`)

**Type:** Command-line fuzzy finder
**Package:** Builds and installs FZF for interactive filtering

**Features:**
- **Fuzzy file search** integration
- **Git file selection** with `git ls-files | fzf`
- **Process selection** for pid management
- **History search** with substring matching

**Common Commands:**
```bash
# Git reset file selection
gaa && gcm "WIP" && git add -p $(fzf)

# Process management
htop | fzf | awk '{print $2}' | xargs kill
```

---
#### 2.5. EZA (`shell/eza.nix`)

**Type:** Modern replacement for ls with icons and colors
**Package:** `pkgs.eza` (previously exa)

**Features:**
- ✅ **Icons integration** with Nerd Fonts symbols
- ✅ **Tree view** (`eza --tree`)
- ✅ **Git status integration** per file
- ✅ **Long format** with permissions and ownership
- ✅ **Sorting control** per completion needs
- ✅ **Custom sorting rules** configured in Zsh completion engine

**Visual Output:**
```bash
eza --icons=always --no-quotes --git --tree
# Shows: ╭── tree directory with git status indicators
```

---
#### 2.6. Direnv (`shell/direnv.nix`)

**Type:** Auto-load environment variables when changing directories
**Package:** Auto-triggers on directory changes

**Features:**
- ✅ **Automatic auth loading** (AWS, Kubeconfig, etc.)
- ✅ **Lightweight** – ~0ms performance impact
- ✅ **Inotify-based** instant reloading
- ✅ **`.envrc` support** for project-specific variables

**Typical Setup:**
```bash
# Create .envrc file in project:
echo -e '. .envrc\nlayout python3' > .envrc
direnv allow
```

---
#### 2.7. Shell Integration Summary

All shell utilities integrate seamlessly:

1. **Zsh** → **Starship prompt** → **Custom aliases**
2. **Zoxide** → Smart navigation → **FZF** for selection
3. **EZA** → File listings with icons → **Direnv** auto-setup
4. **GPG Agent** → **SSH_AUTH_SOCK** integration

Environment is fully **colored, key-highlighted, and anchored in Stylix theme colors**.

---

## ⌨️ Development Tools

### 3. Neovim Framework (NVF) (`nvf/`)

**Type:** Extended Neovim configuration
**Website:** Powered by Notashelf NVF framework
**Configuration:** 33 lines in `home/programs/nvf/default.nix`

**Framework Features:**
- ✅ **NVF module system** with 8 separate configuration files
- ✅ **Stylix color integration** with automatic theme application
- ✅ **Snacks picker** for file navigation
- ✅ **Custom keymaps** with Kakoune-inspired bindings
- ✅ **Autocompletion** with LSP integration
- ✅ **Syntax highlighting override** for theme colors

**NVF Modules:**
| Module | Purpose | Key Bindings |
|--------|---------|--------------|
| **options.nix** | Core settings, theme, clipboard, indentation | - |
| **languages.nix** | LSP, Treesitter, formatters | - |
| **keymaps.nix** | Keybindings, leader key (space) | - |
| **picker.nix** | Snacks picker + oil.nvim | `/` to search |
| **snacks.nix** | Enhanced features (image preview, zen, git signs) | - |
| **utils.nix** | Bufferline, lualine, copilot, lazygit | - |
| **mini.nix** | Mini.nvim suite (pairs, comment, icons, etc.) | - |

**Custom Highlighting:**
- **MiniStarterHeader** → base0D color (theme accent)
- **SnacksPickerBorder** → base0D color (theme accent)
- **SnacksPickerTitle** → base0D color, bold
- Automatic reapply on **ColorScheme** change

**Language Server Support:**
- **Go** → gopls
- **Python** → pyright/pylsp
- **JavaScript/TypeScript** → tsserver
- **Yaml/Json** → yaml-language-server
- **Dockerfile** → dockerfile-language-server
- **Nix** → nil/nixd
- **Rust** → rust-analyzer
- **Markdown** → marksman

**Treesitter Parsers:**
- **Regex highlighting** with advanced capture groups
- **Blazingly fast parsing** with Rust-based engine
- **Language-specific** grammars (full list in languages.nix)

**File Browsing:**
- **file tree** via oil.nvim
- **Snacks picker** with fuzzy filtering and preview
- **mason.nvim** integration
- **telescope.nvim** as fallback picker

**Auto Formatting:**
- **conform.nvim** for uniform formatting
- **prettier** (JS/TS/HTML/CSS/YAML)
- **shfmt** for shell scripts
- **stylua** for Lua
- **gofmt** for Go

**Autocomplete:**
- **nvim-cmp** with sources:
  - LSP
  - Snippets
  - Path
  - Buffer text
- **Copilot** integration
- **Language-specific** completions

**Tool Integration:**
- **gitsigns.nvim** for Git diff visualization
- **lualine.nvim** with theme-configurable status bar
- **bufferline.nvim** for tab management
- **trouble.nvim** for diagnostics
- **flash.nvim** for enhanced navigation
- **todo-comments.nvim** for project annotations

**Quick Access Bindings:**
```vim
<leader>ff → Find files
<leader>fg → Live grep
<leader>fe → Document symbols
<leader>bb → Buffer list
<leader>++ → Incremental selection
```

**Snacks Picker Navigation:**
- **/new** → Create new file in current buffer
- **/[number]** → Jump to specific line
- **CTRL-j/k** → Navigation
- **jump_to_[context/artist/album]** → Media navigation (bonus feature)
- **copy_song_url** → Spotify sharing integration

---
### 4. Helium Browser (`helium/`)

**Type:** Wayland-compatible Flutter-based browser
**Website:** [https://github.com/oxcl/helium-browser](https://github.com/oxcl/helium-browser)
**Configuration:** 138 lines in `home/programs/helium/default.nix`

**Features:**
- ✅ **Wayland-native** via Ozone platform
- ✅ **GPU acceleration**:
  - VA-API video decoding/encoding
  - EGL rendering
  - Hardware-accelerated video playback
- ✅ **Flutter UI** with custom theming
- ✅ **Stylix theme integration** (base16 color matching)
- ✅ **No default browser check**
- ✅ **Avatar button hidden** for clean UI
- ✅ **Bookmark collection** customization

**Wayland Features:**
```bash
--ozone-platform=wayland
```

**Graphics Acceleration:**
```bash
--enable-features=UseOzonePlatform,VaapiVideoDecoder,VaapiVideoEncoder,CanvasOopRasterization
--use-gl=egl
```

**Browser Customization:**
- **Fluent design** theme applied via Flutter extensions
- **Custom Stylix color palette** injected via manifest.json patching
- **Extension-based theming** with ID `abcadngacjlikcpkhleafekcdjmddegk`
- **Theme manifest** autogenerated matching Stylix colors

**Desktop Integration:**
- **Two files created:**
  1. `helium` – Regular browsing window
  2. `helium-private` – Incognito with flags stripped

**Mime Associations:**
- Handles: text/html, text/xml, application/xhtml+xml, x-scheme-handler/(http|https|ftp)
- **Default application** status set correctly

**Startup Behavior:**
- Browser automatically set as default via xdg-mime

---
### 5. Spotify TUI (SpotatUI) (`spotatui/`)

**Type:** Terminal-based Spotify controller
**Website:** [https://github.com/mrVanbrakel/SpotatUI](https://github.com/mrVanbrakel/SpotatUI)
**Configuration:** 104 lines in `home/programs/spotatui/default.nix`

**Features:**
- ✅ **Rust-based** with performance-optimized rendering
- ✅ **Stylix color theme** integration with color math
- ✅ **Full playback control** (play, pause, skip, seek)
- ✅ **Playlist management** (create, edit, favorite)
- ✅ **Volume control** (absolute and percent-based)
- ✅ **Lyrics display** with interactive viewing
- ✅ **Discord RPC** configurable (disabled by default)
- ✅ **Custom keybindings** with application-specific controls

**Performance Settings:**
```yaml
tick_rate_milliseconds: 16       # 60 FPS UI rendering
enable_text_emphasis: true        # Bold/italic formatting
show_loading_indicator: true      # Visual feedback
disable_mouse_inputs: false       # Scroll wheel support
enable_announcements: false      # Notifications disabled
```

**Visualizer Modes:**
- **Equalizer** (default)
- Various wave forms
- Custom presets
- Keepawake preventing idle sleep during listening

**Theme Integration:**
- All theme colors pulled from Stylix via RGB mapping
- Active color → base0D (theme accent)
- Banner color → base0C (theme highlight)
- Error colors → base08 (theme error)
- Playback progress → base0D (theme primary)

**Key Bindings:**
| Function | Key | Description |
|----------|-----|-------------|
| **Back** | q | Return to previous screen |
| **Search** | / | Input field with suggestions |
| **Play/Pause** | space | Toggle playback |
| **Next Track** | n | Skip current track |
| **Previous Track** | p | Return to previous or restart |
| **Volume Up/Down** | +/- | Adjust playback volume |
| **Shuffle** | ctrl+s | Toggle random playback |
| **Repeat** | ctrl+r | Toggle repeat modes |
| **Lyrics** | V | Open synchronized lyrics view |
| **Copy URL** | c / C | Share song or album URL |
| **Queue** | Q | Manage playback queue |
| **Audio Analysis** | v | Display technical audio info |

**Playback Control:**
- **Seek forwards/backwards** adjust by 5 seconds
- **Seek progress** updated every 16ms for smooth animation
- **Shuffle icon** 🔀, **Repeat icons** 🔂 🔁
- **Playing/Paused icons** ▶ ⏸

**Configuration Files:**
- **`~/.config/spotatui/config.yml`** – Persistent user preferences
- **Announcement tracking** disabled after specific IDs seen

---
### 6. Ghostty Configuration Summary

| Aspect | Configuration | Benefit |
|--------|--------------|---------|
| **Cursor** | Custom GLSL shader (cursor_warp) | Visual feedback on actions |
| **Theme** | base16 → Stylix colors | Consistent UI |
| **Integration** | Zsh shell with bidirectional sync | Native terminal experience |
| **Clipboard** | Read/write enabled | Copy/paste without prompts |
| **Paste behavior** | Confirm-close disabled | Speed workflow |
| **Window** | 10px padding X/Y | Comfortable reading |

---
### 7. Shell Summary Table

| Program | Type | Configuration | Purpose |
|---------|------|---------------|---------|
| **Zsh** | Shell | 196 lines | Primary shell with syntax highlighting, history management, completions |
| **Starship** | Prompt | Auto | Fast, multi-language prompt with Git integration |
| **Zoxide** | Navigation | Auto | Smart directory navigation with learning |
| **FZF** | Utility | Auto | Fuzzy finder for interactive filtering |
| **EZA** | ls replacement | Auto | Modern file listing with icons and git status |
| **Direnv** | Automation | Auto | Auto-load environment variables |

---
## 📁 File & Media Management

### 8. Yazi (`yazi/`)

**Type:** Blazing-fast terminal file manager
**Website:** [https://yazi-rs.github.io](https://yazi-rs.github.io)
**Configuration:** (Minimal file in `home/programs/yazi/`)

**Features:**
- ✅ **Rust-based** with async I/O
- ✅ **Image preview** integration
- ✅ **Git status integration**
- ✅ **Yank/put clipboard** (ya `yazi --chooser-file /tmp/clip` pattern)
- ✅ **Batch renaming** with regex support
- ✅ **Bookmark system** with manual entries
- ✅ **Preview engine** for media files
- ✅ **Status column** with metadata

**Typical Usage:**
```bash
yazi /      # Launch file manager at root
Ctrl-t      # Open selection
g           # Jump to git status
z \*.md    # Filter Markdown files
```

**Yazi Config Location:** `~/.config/yazi/yazi.toml` (likely auto-configured)

---
### 9. Thunar (`thunar/`)

**Type:** GTK-based file manager
**Configuration:** (Minimal stub in `home/programs/thunar/`)

**Integrations:**
- **GVFS integration** for network shares
- **Trash support** with undo capability
- **Volume management** via udiskie
- **Bookmark persistence** across sessions

**Typical Usage:**
```bash
thunar /mnt/external   # Launch at external drive
```

---
## 🔀 Git Ecosystem

### 10. Git Customization (`git/`)

**Type:** Version control system with advanced tooling
**Configuration:** 53 lines in `home/programs/git/default.nix`

**Core Configuration:**
- ✅ **Personal defaults** from variables.nix:
  - `user.name` and `user.email` set automatically
  - `init.defaultBranch = main` for new repos
  - `pull.rebase = false` for standard merges
  - `push.autoSetupRemote = true` for origin setup
  - `color.ui = 1` for colored output

**Aliases System:**
Auto-implemented aliases for workflow acceleration:

| Alias | Expands To | Purpose |
|-------|------------|---------|
| **essa** | `git push --force` | Force push with short name |
| **co** | `git checkout` | Branch switching |
| **fuck** | `git commit --amend -m` | Message editing without new commit |
| **c** | `git commit -m` | Quick commits |
| **ca** | `git commit -am` | Quick add+commit |
| **forgor** | `git commit --amend --no-edit` | Edit commit without message change |
| **l** / **s** / **ss** | `git log/status` | Quick overview |
| **st** | `git status --short` | Short status display |
| **pl/ps** | `git pull/push origin $(branch)` | Current branch remote |
| **g** | `lazygit` | Visual Git interface |
| **df** / **hist** / **llog** | Advanced log formats | Visualization |
| **edit-unmerged** | Interactive merge conflict resolution | File selection |
| **ha** | Prefix mode with fzf selection | Mass staging |

**Ignored Files:**
```gitignore
# Standard development exclusions
.cache/
.DS_Store
.idea/
*.swp
*.elc
auto-save-list
.direnv/
node_modules
result*
.venv
```

**Color Configuration:**
- **Full color UI** enabled for all commands
- **Git status colors** integrated with Zsh theme

---
### 11. LazyGit (`git/lazygit.nix`)

**Type:** Terminal UI for Git
**Package:** Auto-installed via shell aliases

**Features:**
- ✅ **Visual branch management** with mouse support
- ✅ **Conflict resolution** with side-by-side comparison
- ✅ **Stashing/Popping** with comment system
- ✅ **Stating/unstating** files with preview
- ✅ **Commit editing** and rewording
- ✅ **Interactive rebase**
- ✅ **Status bar integration** with custom commands

**Typical Usage:**
```bash
g           # Launches lazygit via alias
/           # Search files
Ctrl-s      # Stash changes
Ctrl-f      # Fetch branch
```

---
### 12. Time-Capsule CSR (`git/signing.nix`)

**Type:** Git commit signing with GnuPG
**Configuration:** Signing framework setup

**Features:**
- ✅ **GnuPG agent** integration for SSH auth
- ✅ **Commit signing** enabled via `gpgsigning=true`
- **Typical signed commit message:** “git commit -S -m 'Fix typo'”

---
### 13. Git System Summary

| Component | Type | Purpose |
|-----------|------|---------|
| **Git** | VCS | Core version control with 20+ aliases |
| **Lazygit** | GUI | Terminal-based Git management with advanced features |
| **Commit Signing** | Security | GnuPG-signed commits for provenance |
| **Ah:h/l** | UUID-based | Next to remember/fix commits |

---
## ☁️ Electron Integration

### 14. Proton VPN (`proton/`)

**Type:** Security-focused VPN with auto-start
**Configuration:** 2 files in `home/programs/proton/`

**Modules:**
1. **auto-start-vpn.nix** – Automatic VPN connection on boot
2. **default.nix** – Proton VPN configuration

**Features:**
```nix
services.protonvpn.enable = true;   # System service
autoStartVPN.enable = true;         # Immediate connection
```

---
## ❄️ Color Scheme & Desk Utilities

### 15. Nightshift (`nightshift/`)

**Type:** Blue light filter for circadian rhythm
**Configuration:** (Minimal stub)

**Features:**
- **Night light schedule** with ambient adaptation
- **Blue-light reduction** with adjustable tint
- **Night mode** for ambient display in dark conditions

**Typical: BlueShift → 3000K ambient**

---
## 🧪 Technology Stack Utilities

### 16. Nix Utilities (`nix-utils/`)

**Type:** Nix ecosystem helper tools
**Configuration:** Nix command-line helpers

**Features:**
- **Nix profile management** commands
- **Store optimization** shortcuts
- **Flake update** automation
- **Garbage collection** with thresholds
- **Build status** display templates

**Typical Commands:**
```bash
nix-highlight   # Syntax highlighting for Nix files
nix-search       # Package search with ranking
```

---
### 17. Nixy Package (`nixy/`)

**Type:** Self-reference utilities
**Configuration:** `home/programs/nixy/default.nix`

**Features:**
- **Dotfile synchronizer**
- **Home-manager shortcuts**
- **Nix evaluation** for debugging
- **Flake helper** scripts

---
## 📚 Bookmark Collections

### 18. Helium Bookmarks (`helium/bookmarks/`)

**Type:** Category-based web bookmarks
**Configuration:** Submodules in `helium/default.nix`

**Bookmark Categories:**
```
helium/bookmarks/
├── default.nix                # Base configuration
├── entertainment.nix           # Streaming, music, video
├── general.nix               # Default browser start page
├── infosec.nix              # Security resources
├── jack.nix                 # Personal/social bookmarks
├── other.nix                # Miscellaneous
├── tools.nix                # Technical tooling sites
```

**Bookmark Structure:**
- **Custom bookmark bars** using Helium's extension API
- **Organized into groups** for task-specific browsing
- **Color-coded** matching Stylix theme
- **Folder hierarchy** for deep categorization

**Usage:**
Helium browser auto-populates these bookmarks on first launch. Bookmarks persist across sessions.

---
## 📊 Group Package Management

Currently defined in `home/programs/group/` directory:

| Group | Purpose | Status |
|-------|---------|--------|
| **dev** | Development tools | Active |
| **basic-apps** | Core applications | Active |
| **cybersecurity** | Security tools | Active |
| **flake** | Flake helper modules | Active |

---
### 19. Group Overview

All groups are **importable via flake**:

```nix
{ inputs, ... }: {
  imports = [
    inputs.nixy.homeManagerModules.<group>   # 📦 Install package group
  ];
}
```

Or via **nix shell command**:

```bash
nix shell github:anotherhadi/nixy#<group>   # Instant shell with packages
```

Note: These are **separate from the home/programs** files – refer to **[GROUPS.md](GROUPS.md)** for package list details.

---
## 🛠️ Quick Reference: All Programs

### Terminal & Shell
| Program | Category | Description |
|---------|----------|-------------|
| **Ghostty** | Terminal | GPU-accelerated terminal with cursor shaders |
| **Zsh** | Shell | Advanced shell with syntax highlighting and autosuggestions |
| **Zoxide** | Shell | Fuzzy directory navigation |
| **FZF** | Utility | Interactive fuzzy finder |
| **EZA** | Utility | Modern ls replacement with icons |
| **Starship** | Prompt | Multi-language prompt with Git integration |
| **Direnv** | Automation | Auto-load environments |

### Development & Editing
| Program | Category | Description |
|---------|----------|-------------|
| **NVF (Neovim)** | Editor | Notashelf NVF framework with theme integration |
| **Helium** | Browser | Wayland Flutter browser with Fluent design |
| **SpotatUI** | Media | Rust-based Spotify terminal controller |

### File & Media
| Program | Category | Description |
|---------|----------|-------------|
| **Yazi** | File manager | Blazing-fast Rust file manager |
| **Thunar** | File manager | GTK-based file manager integration |
| **VNC Utilities** | Remote | Native support packages |

### Version Control
| Program | Category | Description |
|---------|----------|-------------|
| **Git** | VCS | Core Git with 20+ conveniences |
| **LazyGit** | VCS | Visual Git terminal UI |
| **GnuPG** | Security | Commit signing and SSH agent |

### Services & Utilities
| Program | Category | Description |
|---------|----------|-------------|
| **Proton VPN** | Security | System-wide VPN with auto-connect |
| **Nightshift** | Display | Blue light filter for circadian rhythm |
| **Nix Utils** | Package management | Nix-specific helper tools |
| **Helium Bookmarks** | Organization | Web bookmarks organized by category |

---
## 🔧 Home Manager Integration

All programs are configured via home-manager modules:

**Example import chain:**
```
home/programs/shell/default.nix
  → home/programs/shell/zsh.nix (196 lines)
  → shell aliases → term integration
```

**Features Provided:**
- ✅ **Universal theming** (all apps → Stylix colors)
- ✅ **Session variables** (TERMINAL, TERM, BROWSER set as defaults)
- ✅ **desktopEntries** (Helium appears in app menu)
- ✅ **xdg base directory** compliance (all config → ~/.config)
- ✅ **Migration-free** updates via home-manager

---
## 📖 User Guide: Setting Up Your Environment

### Prerequisites
1. **NixOS System** (with home-manager installed)
2. **Flakes enabled** in NixOS configuration
3. **Stylix colors** populated (optional, enhances visual integration)
4. **Fonts:** Nerd Fonts and Symbol fonts installed

### Installation Steps

#### Step 1: Add Inputs
```nix
inputs.nixy.url = "github:anotherhadi/nixy";
```

#### Step 2: Import Modules
```nix
home-manager = {
  imports = [
    inputs.nixy.homeManagerModules.<program>
    # Or import multiple: ./{ghostty,zsh,nvf}/default.nix
  ];
};
```

#### Step 3: Build Environment
```bash
home-manager switch --flake /etc/nixos#username@hostname
```

#### Step 4: Verify Installation
```bash
# Check services
systemctl status --user wireplumber      # PipeWire audio server
systemctl status --user greetd          # Greetd display manager
systemctl status --user dbus-broker     # Desktop Bus broker

# Verify programs
ghostty --version
nvim --headless -c 'qa'             # Neovim validation
yazi --help                           # Yazi file manager
```

---
## 🎨 Theming Integration Flow

All programs receive **Stylix colors** automatically:

```
home/programs/
├── nvf/default.nix → passes colors → Mini.nvim → Neovim UI recolor
├── ghostty/default.nix → sets base00-base0F colors → Terminal theme
├── spotatui/default.nix → FYI base00-base0F → Color map to UI
└── helium/default.nix → manual injection into Flutter manifest
```

Result: **Consistent color scheme across all applications** matching desktop theme.

---
## ⚡ Performance Optimization

| Program | Optimization | Benefit |
|---------|--------------|---------|
| **Ghostty** | GPU shader | 60+ FPS scrolling |
| **EZA** | Tree-sitter parsing | <10ms file list |
| **Zoxide** | Fuzzy matching algorithm | O(n log n) navigation |
| **FZF w/ Sk** | File caching | <1ms repeat searches |
| **SpotatUI** | Rust low-overhead | 60 FPS visualizations |
| **LazyGit** | Lazy-loading | <50ms response time |
| **Helium** | Flutter GPU | Hardware-accelerated rendering |

---
## 🚀 Usage Examples

### One-liner setup: Ghostty + Zsh
```nix
{ inputs, ... }: {
  imports = [
    inputs.nixy.homeManagerModules.ghostty
    inputs.nixy.homeManagerModules.shell
  ];
}
```

### Full development stack
```bash
home-manager switch --flake .#username@laptop
# Installs: Ghostty, Zsh w/ 20 aliase, NVF (Neovim), Yazi, Helium
```

### Media workstation
```bash
nix shell github:anotherhadi/nixy#cybersecurity
# Instant shell with: Zsh, NVF, Ghostty, Lazygit, Helium
```

### Quick Spotify session
```bash
spt       # Alias to spotatui via shell configuration
/weekend # Type in search bar, space to play
```

---
## 📚 Additional Documentation

- **[GROUPS.md](GROUPS.md)** – Predefined software groups with package lists
- **[NEOVIM.md](docs/NEOVIM.md)** – Detailed NVF (Neovim) configuration
- **[THEMES.md](docs/THEMES.md)** – How theming works and theme creation
- **[README.md](docs/README.md)** – System-wide configuration guide
- **[SERVER.md](docs/SERVER.md)** – Server-specific services

---