docs: add package descriptions to README

draphy · draphy · commit e8f5075d2acf · 2026-03-15T06:00:19.000+05:30
diff --git a/README.md b/README.md
@@ -284,94 +284,188 @@ Every tool in draphyOS was chosen with a purpose. Here's why:
 
 ## 📦 Packages
 
+Every package in draphyOS was chosen for a reason. Here's the complete list with explanations:
+
+<details>
+<summary><strong>Fedora i3 Spin — Core (Pre-installed)</strong></summary>
+
+These come with Fedora i3 Spin. draphyOS builds on top of them.
+
+| Package | What it does | Why it's here |
+| ------- | ------------ | ------------- |
+| `i3` | Tiling window manager | The foundation — lightweight, keyboard-driven, tiling workflow |
+| `i3lock` | Screen locker | Security — locks screen with custom draphyOS logo |
+| `i3status` | Default status bar | Replaced by polybar, but kept for fallback |
+| `dmenu` | Default app launcher | Replaced by rofi, but kept for fallback |
+| `dunst` | Notification daemon | Lightweight, keyboard-friendly, highly configurable notifications |
+| `lightdm` | Display manager | Login screen — minimal, reliable, easy to theme |
+| `alacritty` | Terminal emulator | GPU-accelerated, fast, configurable via TOML |
+| `NetworkManager` | Network management | WiFi/Ethernet — auto-connect, easy switching |
+| `network-manager-applet` | Network tray icon | Quick network switching from system tray |
+| `firefox` | Web browser | Default browser — privacy-respecting, open source |
+| `pulseaudio-utils` | Audio tools (`pactl`) | Volume control from keybindings and polybar |
+| `pavucontrol` | Volume control GUI | Per-application volume, input/output device selection |
+| `brightnessctl` | Brightness control | Laptop screen brightness from keybindings |
+| `htop` | Process viewer | Quick system overview, kill processes |
+| `mousepad` | Text editor | Simple GUI editor for quick config edits |
+| `Thunar` | File manager | Lightweight GUI file manager (GTK-based) |
+
+</details>
+
+<details>
+<summary><strong>Fedora i3 Spin — Extended (Pre-installed)</strong></summary>
+
+Additional tools from i3 Spin that draphyOS uses or enhances.
+
+| Package | What it does | Why it's here |
+| ------- | ------------ | ------------- |
+| `rofi` | App launcher | Beautiful, themeable launcher — replaces dmenu |
+| `powertop` | Power analysis | Identify power-hungry processes, optimize battery |
+| `arandr` | Display config | Visual multi-monitor setup and arrangement |
+| `tmux` | Terminal multiplexer | Split terminal, persistent sessions, remote work |
+| `lxappearance` | GTK theme switcher | Change GTK themes, icons, fonts without editing files |
+
+</details>
+
+<details>
+<summary><strong>Desktop Environment — draphyOS Additions</strong></summary>
+
+Core packages that make draphyOS look and function the way it does.
+
+| Package | What it does | Why it's here |
+| ------- | ------------ | ------------- |
+| `polybar` | Status bar | Highly customizable bar — replaces i3status with icons, modules |
+| `picom` | Compositor | Window transparency, shadows, blur, rounded corners |
+| `fish` | Shell | Modern shell — syntax highlighting, autosuggestions out-of-box |
+| `feh` | Image viewer | Sets wallpaper on login, lightweight image viewing |
+| `flameshot` | Screenshots | Select area, annotate, blur, save/copy — full-featured screenshots |
+| `playerctl` | Media control | Control any media player (Spotify, Firefox, VLC) via keybindings |
+| `xss-lock` | Screen lock trigger | Auto-locks screen after idle timeout (15 min) |
+| `blueman` | Bluetooth manager | Easy Bluetooth pairing and device management |
+| `gammastep` | Blue light filter | Reduces eye strain at night — auto-adjusts by time/location |
+| `xfce-polkit` | Auth dialogs | Prompts for password when apps need root (package installs, etc.) |
+| `gnome-keyring` | Secret storage | Stores passwords, SSH keys — auto-unlocks on login |
+| `xfce4-settings` | Settings manager | Central place for appearance, keyboard, display settings |
+| `yad` | Dialog boxes | Powers the calendar popup when clicking date in polybar |
+| `qt5ct` | Qt5 theming | Makes Qt apps respect the GTK dark theme |
+| `ImageMagick` | Image processing | Creates the logo overlay for the lock screen |
+| `xdotool` | X11 automation | Executes keybindings from cheatsheet |
+| `xclip` | Clipboard | Copies commands from cheatsheet to clipboard |
+
+</details>
+
+<details>
+<summary><strong>Fonts & Theming</strong></summary>
+
+Visual consistency across the entire desktop.
+
+| Package | What it does | Why it's here |
+| ------- | ------------ | ------------- |
+| `fira-code-fonts` | Programming font | Ligatures (=> becomes arrow), excellent readability |
+| `google-noto-sans-mono-vf-fonts` | Fallback mono font | Unicode coverage for characters Fira Code doesn't have |
+| `fontawesome-6-free-fonts` | Icon font | All the icons in polybar (volume, wifi, battery, etc.) |
+| `fontawesome-6-brands-fonts` | Brand icons | Logos for Spotify, Discord, etc. in polybar |
+| `mint-y-icons` | Icon theme | Clean, modern folder/app icons — dark variant |
+| `adwaita-cursor-theme` | Cursor theme | System default cursor — works everywhere |
+
+</details>
+
 <details>
-<summary><strong>Fedora i3 Spin — Core</strong></summary>
-
-| Package                  | Description                             |
-| ------------------------ | --------------------------------------- |
-| `i3`                     | Tiling window manager                   |
-| `i3lock`                 | Screen locker                           |
-| `i3status`               | Status bar (replaced by polybar)        |
-| `dmenu`                  | Application launcher (replaced by rofi) |
-| `dunst`                  | Notification daemon                     |
-| `lightdm`                | Display manager (login screen)          |
-| `alacritty`              | Terminal emulator (GPU-accelerated)     |
-| `NetworkManager`         | Network management                      |
-| `network-manager-applet` | Network tray icon                       |
-| `firefox`                | Web browser                             |
-| `pulseaudio-utils`       | Audio control                           |
-| `pavucontrol`            | Volume control GUI                      |
-| `brightnessctl`          | Brightness control                      |
-| `htop`                   | Process viewer                          |
-| `mousepad`               | Text editor                             |
-| `Thunar`                 | File manager                            |
-
-</details>
-
-<details>
-<summary><strong>Fedora i3 Spin — Extended</strong></summary>
-
-| Package        | Description           |
-| -------------- | --------------------- |
-| `rofi`         | Application launcher  |
-| `powertop`     | Power management      |
-| `arandr`       | Display configuration |
-| `tmux`         | Terminal multiplexer  |
-| `lxappearance` | GTK theme switcher    |
-
-</details>
-
-<details>
-<summary><strong>draphyOS Additions</strong></summary>
-
-| Package                          | Description                         |
-| -------------------------------- | ----------------------------------- |
-| `polybar`                        | Status bar (replaces i3status)      |
-| `picom`                          | Compositor (transparency, shadows)  |
-| `fish`                           | Modern shell with auto-suggestions  |
-| `feh`                            | Wallpaper setter, image viewer      |
-| `flameshot`                      | Screenshot tool                     |
-| `playerctl`                      | Media player control                |
-| `xss-lock`                       | Automatic screen locker             |
-| `blueman`                        | Bluetooth manager                   |
-| `gammastep`                      | Night light / blue light filter     |
-| `xfce-polkit`                    | Authentication dialogs              |
-| `gnome-keyring`                  | Password/secret storage             |
-| `xfce4-settings`                 | Settings manager                    |
-| `yad`                            | Calendar popup (click date in bar)  |
-| `qt5ct`                          | Qt5 theme configuration             |
-| `ImageMagick`                    | Image processing (lock screen logo) |
-| `xdotool`                        | X11 automation (cheatsheet execute) |
-| `xclip`                          | Clipboard (cheatsheet copy)         |
-| `fira-code-fonts`                | Programming font with ligatures     |
-| `google-noto-sans-mono-vf-fonts` | Fallback mono font                  |
-| `fontawesome-6-free-fonts`       | Icon font (polybar icons)           |
-| `fontawesome-6-brands-fonts`     | Icon font (brand logos)             |
-| `mint-y-icons`                   | Icon theme                          |
-| `adwaita-cursor-theme`           | Cursor theme                        |
-| `yazi`                           | Terminal file manager               |
-| `ueberzugpp`                     | Image preview for yazi              |
-| `btop`                           | System monitor                      |
-| `zoxide`                         | Smarter cd command                  |
-| `mpv`                            | Video player                        |
-
-</details>
-
-<details>
-<summary><strong>Third-Party Applications (v10)</strong></summary>
-
-| Package | Description |
-| ------- | ----------- |
-| `brave-browser` | Privacy-focused browser |
-| `google-chrome-stable` | Chrome browser |
-| `code` | Visual Studio Code |
-| `proton-vpn-gnome-desktop` | ProtonVPN client |
-| `torbrowser-launcher` | Tor Browser |
-| `docker-ce` | Container runtime |
-| `postgresql-server` | Database server |
-| `obs-studio` | Screen recording |
-| `kdenlive` | Video editor |
-| `neovim` | Text editor |
+<summary><strong>Terminal File Manager — yazi</strong></summary>
+
+Modern terminal file manager with image preview support.
+
+| Package | What it does | Why it's here |
+| ------- | ------------ | ------------- |
+| `yazi` | File manager | Blazing fast, vim-style navigation, image/PDF preview |
+| `ueberzugpp` | Image preview | Displays images in terminal for yazi previews |
+| `ffmpegthumbnailer` | Video thumbnails | Generates video thumbnails for yazi preview |
+| `poppler-utils` | PDF tools | PDF preview in yazi (pdftotext, pdftoppm) |
+| `atool` | Archive helper | Preview archive contents (zip, tar, etc.) in yazi |
+
+</details>
+
+<details>
+<summary><strong>CLI Tools</strong></summary>
+
+Command-line utilities that improve daily workflows.
+
+| Package | What it does | Why it's here |
+| ------- | ------------ | ------------- |
+| `git` | Version control | Foundation for code management, draphyOS updates |
+| `btop` | System monitor | Beautiful resource monitor — replaces htop for detailed view |
+| `zoxide` | Smart cd | Remembers directories, jump with `z` instead of full path |
+| `fd-find` | File finder | Fast, user-friendly alternative to `find` |
+| `ripgrep` | Code search | Fast grep replacement — respects .gitignore |
+| `fzf` | Fuzzy finder | Interactive search for files, history, anything |
+| `jq` | JSON processor | Parse JSON in scripts (used for location detection) |
+| `ffmpeg` | Media converter | Video/audio conversion, used by other tools |
+| `p7zip` | Archive tool | Extract 7z, zip, rar, and other archive formats |
+| `neovim` | Text editor | Modern vim — better defaults, Lua config, plugins |
+
+</details>
+
+<details>
+<summary><strong>Media & Documents</strong></summary>
+
+Applications for viewing and creating content.
+
+| Package | What it does | Why it's here |
+| ------- | ------------ | ------------- |
+| `mpv` | Video player | Minimal, keyboard-driven, plays anything |
+| `audacious` | Music player | Lightweight audio player with playlists |
+| `zathura` | PDF viewer | Vim-style PDF reader — minimal, fast |
+| `zathura-pdf-poppler` | PDF backend | Enables PDF rendering in zathura |
+| `obs-studio` | Screen recording | Record screen, stream — industry standard |
+| `kdenlive` | Video editor | Full-featured video editing (KDE-based) |
+| `libreoffice-calc` | Spreadsheets | Excel-compatible spreadsheet editor |
+| `libreoffice-writer` | Documents | Word-compatible document editor |
+| `gparted` | Disk utility | Partition disks, format drives — GUI tool |
+
+</details>
+
+<details>
+<summary><strong>Browsers & Privacy</strong></summary>
+
+Multiple browser options for different needs.
+
+| Package | What it does | Why it's here |
+| ------- | ------------ | ------------- |
+| `firefox` | Browser (default) | Privacy-respecting, open source — pre-installed |
+| `brave-browser` | Browser | Chromium-based, built-in ad blocker, privacy-focused |
+| `google-chrome-stable` | Browser | For sites that require Chrome (some Google services) |
+| `torbrowser-launcher` | Tor Browser | Anonymous browsing, access .onion sites |
+| `proton-vpn-gnome-desktop` | VPN client | ProtonVPN — Swiss-based, no-logs VPN |
+
+</details>
+
+<details>
+<summary><strong>Development Tools</strong></summary>
+
+Everything needed for software development.
+
+| Package | What it does | Why it's here |
+| ------- | ------------ | ------------- |
+| `code` | VS Code | Most popular code editor — extensions, debugging, Git |
+| `docker-ce` | Container runtime | Run isolated containers for dev/deployment |
+| `docker-ce-cli` | Docker CLI | Command-line interface for Docker |
+| `containerd.io` | Container daemon | Low-level container runtime (Docker dependency) |
+| `docker-buildx-plugin` | Build tool | Multi-platform Docker image builds |
+| `docker-compose-plugin` | Compose | Define multi-container apps in YAML |
+| `postgresql-server` | Database | Relational database — auto-configured with your user |
+| `postgresql-contrib` | DB extensions | Additional PostgreSQL modules and utilities |
+| `fnm` (via install script) | Node.js manager | Fast Node.js version switching per project |
+
+</details>
+
+<details>
+<summary><strong>NVIDIA Support (Optional)</strong></summary>
+
+Auto-detected and installed only if NVIDIA GPU is present.
+
+| Package | What it does | Why it's here |
+| ------- | ------------ | ------------- |
+| `akmod-nvidia` | NVIDIA driver | Proprietary driver — auto-rebuilds on kernel updates |
 
 </details>
 
