Add configuration for Librewolf and Zen browser with privacy-focused policies

- Created Librewolf configuration in `home/programs/librewolf/system.nix` with telemetry disabled, enhanced security settings, and enforced extensions. - Added Zen browser configuration in `home/programs/zen/default.nix` and `home/programs/zen/system.nix`, including similar privacy policies and default search engine settings. - Introduced `hosts/home-pc/configuration.nix` for system-wide settings, including USBGuard rules and firewall configurations. - Established `hosts/home-pc/flake.nix` to manage NixOS modules and configurations. - Generated `hosts/home-pc/hardware-configuration.nix` for hardware-specific settings. - Created `hosts/home-pc/home.nix` to import various user-specific applications and settings. - Added profile picture in `hosts/home-pc/profile_picture.jpg`. - Implemented secrets management in `hosts/home-pc/secrets/default.nix` and `hosts/home-pc/secrets/secrets.yaml` using SOPS for encryption. - Defined user-specific variables in `hosts/home-pc/variables.nix`, including hostname, username, and locale settings. - Added profile picture for laptop in `hosts/laptop/profile_picture.jpg`.
2026-06-22 23:11:52 +02:00
parent a45e7a2c9b
commit 7ea20554a6
24 changed files with 2305 additions and 8 deletions
@@ -0,0 +1,908 @@
+# 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
+
+---