diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c2a2e85..1755aea 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -177,32 +177,34 @@ VPN & Network • Security • File Sharing • System
 
 ## 🎨 Icon System
 
-TuxMate uses the [Iconify API](https://iconify.design/) for icons.
+TuxMate uses the [Iconify API](https://iconify.design/) for icons. Icon helpers are defined in [`src/lib/data.ts`](src/lib/data.ts).
 
 ### Helper Functions
 
 | Function | Use Case | Example |
 |----------|----------|---------|
-| `si('slug', '#color')` | Brand icons | `si('firefox', '#FF7139')` |
+| `si('slug', '#color')` | Simple Icons (brands) | `si('firefox', '#FF7139')` |
 | `lo('slug')` | Colorful logos | `lo('chrome')` |
-| `mdi('slug', '#color')` | Material icons | `mdi('console', '#57F287')` |
-| `dev('slug')` | Developer tools | `dev('vscode')` |
-| `sk('slug')` | Skill/tech icons | `sk('react')` |
+| `mdi('slug', '#color')` | Material Design icons | `mdi('console', '#57F287')` |
+| `dev('slug')` | Devicon (dev tools) | `dev('vscode')` |
+| `sk('slug')` | Skill Icons (colorful) | `sk('react')` |
 | `vs('slug')` | VS Code file icons | `vs('file-type-shell')` |
 
 ### Finding Icon Slugs
 
 | Source | URL | Notes |
 |--------|-----|-------|
-| **Simple Icons** | [simpleicons.org](https://simpleicons.org/) | Use lowercase slug |
+| **Simple Icons** | [simpleicons.org](https://simpleicons.org/) | Use lowercase slug, add hex color |
 | **Material Design** | [pictogrammers.com/library/mdi](https://pictogrammers.com/library/mdi/) | Use icon name |
+| **Iconify Search** | [icon-sets.iconify.design](https://icon-sets.iconify.design/) | Search all sets |
 | **Fallback** | — | Use `mdi('application', '#color')` |
 
 ### Icon Requirements
 
 - ✅ Must be recognizable at 24×24px
-- ✅ Use [official brand colors](https://simpleicons.org)
-- ✅ Monochrome icons require a color parameter
+- ✅ Use [official brand colors](https://simpleicons.org) - click icon to copy hex
+- ✅ Monochrome icons (si, mdi) require a color parameter
+- ✅ Colorful icons (lo, sk, vs) don't need color
 - ❌ Don't use blurry or low-quality external URLs
 
 ---
@@ -224,6 +226,7 @@ TuxMate uses the [Iconify API](https://iconify.design/) for icons.
 - [ ] Tested locally with `npm run dev`
 - [ ] Production build passes: `npm run build`
 - [ ] Lint passes: `npm run lint`
+- [ ] Unit tests pass: `npm run test`
 - [ ] Apps added in **alphabetical order** within their category
 - [ ] Icons display correctly at small sizes
 
@@ -273,6 +276,7 @@ npm run dev
 ```bash
 npm run lint          # Check for errors
 npm run lint -- --fix # Auto-fix issues
+npm run test          # Run unit tests
 npm run build         # Verify production build
 ```
 
@@ -304,34 +308,57 @@ Distributions are defined in [`src/lib/data.ts`](src/lib/data.ts).
 {
   id: 'distro-id',
   name: 'Display Name',
-  iconUrl: si('distro-slug'),
+  iconUrl: si('distro-slug', '#color'),
   color: '#HexColor',
   installPrefix: 'sudo pkg install -y'
 }
 ```
 
 ### After Adding a Distro
-1. Update `src/lib/generateInstallScript.ts`
-2. Add the distro case in `generateInstallScript()`
-3. Handle distro-specific logic (repo enabling, AUR helpers, etc.)
-4. Include proper error handling and package detection
+1. Add the distro ID to the `DistroId` type in `src/lib/data.ts`
+2. Create a new script generator file: `src/lib/scripts/[distro].ts`
+3. Export the generator from `src/lib/scripts/index.ts`
+4. Add the case in `src/lib/generateInstallScript.ts` (both functions)
+5. Handle distro-specific logic (repo setup, package detection, etc.)
+6. Add `targets.[distro]` entries to relevant apps in `data.ts`
 
 ---
 
 ## ⚙️ Script Generation
 
-The install script logic lives in [`src/lib/generateInstallScript.ts`](src/lib/generateInstallScript.ts).
+Script generation is modular. Each distro has its own generator:
+
+```
+src/lib/
+├── generateInstallScript.ts    # Main entry point
+├── aur.ts                      # AUR package detection
+└── scripts/
+    ├── index.ts                # Exports all generators
+    ├── shared.ts               # Colors, progress bars, utilities
+    ├── arch.ts                 # Arch + AUR (yay)
+    ├── debian.ts               # Debian apt
+    ├── ubuntu.ts               # Ubuntu apt + PPA handling
+    ├── fedora.ts               # Fedora dnf + RPM Fusion
+    ├── opensuse.ts             # openSUSE zypper
+    ├── nix.ts                  # Nix package manager
+    ├── flatpak.ts              # Flatpak (parallel install)
+    └── snap.ts                 # Snap packages
+```
 
 ### Key Features to Maintain
-- Package detection for already-installed software
-- AUR handling with auto-install of yay helper
-- RPM Fusion auto-enabling for Fedora
-- Parallel installation support for Flatpak
-- Exponential backoff retry for network failures
-- Progress bars with ETA and colored output
+- **Package detection** - Skip already-installed packages
+- **AUR handling** - Auto-install `yay` helper (see `aur.ts` for patterns)
+- **RPM Fusion** - Auto-enable for Fedora when needed
+- **Parallel installation** - Flatpak concurrent installs
+- **Network retry** - Exponential backoff for failures
+- **Progress bars** - ETA with colored output
+- **Shell escaping** - Security against injection (see `escapeShellString()` in `shared.ts`)
 
 ### Testing Script Changes
 ```bash
+# Run unit tests (shell escaping, AUR detection)
+npm run test
+
 # Generate and test a script
 npm run dev
 # Select packages → Copy script → Test in VM/container
diff --git a/README.md b/README.md
index f194811..e3fdf24 100644
--- a/README.md
+++ b/README.md
@@ -52,11 +52,11 @@ Shows which apps are available for your selected distro, with instructions for u
 
 
 
-## �📸 Screenshots 🖼️
+## 📸 Screenshots
 
-![](src/screenshots/1.png)
-![](src/screenshots/2.png)
-![](src/screenshots/3.png)
+![Main interface with app selection](src/screenshots/1.png)
+![Category browsing and filtering](src/screenshots/2.png)
+![Generated install script](src/screenshots/3.png)
 
 
 
@@ -81,6 +81,39 @@ npm start
 </details>
 
 
+<details>
+<summary><h2>🗂️ Project Structure</h2></summary>
+
+```
+src/
+├── app/                    # Next.js app router
+│   ├── page.tsx            # Main page component
+│   ├── layout.tsx          # Root layout with meta tags
+│   └── globals.css         # Tailwind styles
+├── components/
+│   ├── app/                # App cards & categories
+│   ├── command/            # Command footer & AUR bar
+│   ├── common/             # Tooltips, loading states
+│   ├── distro/             # Distribution selector
+│   ├── header/             # Header & theme toggle
+│   └── ui/                 # Base UI components
+├── hooks/                  # React hooks
+│   ├── useLinuxInit.ts     # Main app state management
+│   ├── useKeyboardNavigation.ts
+│   ├── useTheme.ts
+│   └── useDelayedTooltip.ts
+├── lib/
+│   ├── data.ts             # Apps, distros, icons
+│   ├── aur.ts              # AUR package detection
+│   ├── analytics.ts        # Umami tracking
+│   ├── generateInstallScript.ts
+│   └── scripts/            # Per-distro script generators
+└── __tests__/              # Vitest unit tests
+```
+
+</details>
+
+
 <details>
 <summary><h2>🐳 Docker Deployment</h2></summary>
 
@@ -153,12 +186,14 @@ docker run -p 3000:3000 \
 
 ## 🛠️ Tech Stack
 
-- Next.js 16
-- React 19
-- TypeScript
-- Tailwind CSS 4
-- Framer Motion
-- GSAP
+- [Next.js](https://nextjs.org/) 16 (App Router)
+- [React](https://react.dev/) 19
+- [TypeScript](https://www.typescriptlang.org/)
+- [Tailwind CSS](https://tailwindcss.com/) 4
+- [Framer Motion](https://www.framer.com/motion/)
+- [GSAP](https://gsap.com/)
+- [Vitest](https://vitest.dev/) (testing)
+- [Lucide React](https://lucide.dev/) (icons)
 
 
 ## 🚀 Usage