diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f9eae8d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,168 @@
+# COSMIC Store - Omarchy
+
+A graphical Flatpak app store for [Omarchy](https://omarchy.com) (Arch Linux + Hyprland), powered by System76's [COSMIC Store](https://github.com/pop-os/cosmic-store).
+
+Browse and install thousands of Flatpak applications through a clean, modern GUI — with full Hyprland integration so installed apps appear in your app launcher.
+
+## Requirements
+
+- **OS**: [Omarchy](https://omarchy.com) (Arch Linux)
+- **Compositor**: Hyprland
+- **AUR Helper**: yay or paru (Omarchy ships with yay)
+
+## Quick Start
+
+```bash
+git clone https://github.com/28allday/COSMIC-Store-Omarchy.git
+cd COSMIC-Store-Omarchy
+chmod +x cosmic.sh
+./cosmic.sh
+```
+
+After installation, **log out and back in** so the environment variables take effect, then search for "COSMIC Store" in your app launcher.
+
+## What It Does
+
+### 1. Installs Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `flatpak` | Sandboxed app distribution system (like Snap but open) |
+| `xdg-desktop-portal` | D-Bus bridge between sandboxed apps and the desktop |
+| `xdg-desktop-portal-gtk` | GTK fallback portal for file dialogs |
+| `xdg-desktop-portal-hyprland` | Hyprland-specific portal (screen sharing, window picking) |
+| `desktop-file-utils` | App menu integration tools |
+| `base-devel`, `git` | Build tools for compiling COSMIC Store from AUR |
+
+### 2. Configures Flathub
+
+Adds the [Flathub](https://flathub.org) repository at both system and user level, giving you access to thousands of applications.
+
+### 3. Installs COSMIC Store from AUR
+
+Builds and installs `cosmic-store-git` — System76's app store built with the COSMIC toolkit. It provides a graphical interface for browsing, installing, and managing Flatpak apps.
+
+### 4. Creates Hyprland Wrapper
+
+COSMIC Store needs to know it's running under Hyprland to use the correct desktop portal. The wrapper script sets `XDG_CURRENT_DESKTOP=Hyprland` before launching the store.
+
+### 5. Makes Flatpak Apps Visible in Launcher
+
+Flatpak installs `.desktop` files in non-standard locations. The script:
+- Adds Flatpak export directories to `XDG_DATA_DIRS`
+- Sets environment variables in both systemd and Hyprland config
+- Symlinks Flatpak `.desktop` files into `~/.local/share/applications/`
+
+This ensures installed Flatpak apps appear in Walker/Elephant (Omarchy's app launchers).
+
+### 6. Restarts Portal Services
+
+Restarts the XDG desktop portal daemons so they pick up the new Hyprland configuration immediately.
+
+## Files Created
+
+| Path | Purpose |
+|------|---------|
+| `/usr/local/bin/cosmic-store-hypr` | Wrapper script (sets Hyprland environment) |
+| `~/.local/share/applications/com.system76.CosmicStore.desktop` | User desktop entry |
+| `~/.config/environment.d/flatpak.conf` | Flatpak environment variables |
+
+## Usage
+
+### Opening COSMIC Store
+
+Search for **"COSMIC Store"** in your app launcher, or run:
+
+```bash
+cosmic-store-hypr
+```
+
+### Installing Apps via Command Line
+
+```bash
+# Search for an app
+flatpak search firefox
+
+# Install an app
+flatpak install flathub org.mozilla.firefox
+
+# Run an app
+flatpak run org.mozilla.firefox
+
+# List installed apps
+flatpak list
+```
+
+### Making New Flatpak Apps Appear in Launcher
+
+After installing a Flatpak app via the command line, you may need to symlink its desktop file:
+
+```bash
+# Symlink all Flatpak desktop files
+for d in ~/.local/share/flatpak/exports/share/applications /var/lib/flatpak/exports/share/applications; do
+  [ -d "$d" ] && find "$d" -maxdepth 1 -name '*.desktop' -exec ln -sf {} ~/.local/share/applications/ \;
+done
+```
+
+Apps installed through COSMIC Store should appear automatically.
+
+## Troubleshooting
+
+### COSMIC Store can't launch installed apps
+
+Make sure the wrapper is being used:
+```bash
+grep "Exec" ~/.local/share/applications/com.system76.CosmicStore.desktop
+```
+Should show: `Exec=/usr/local/bin/cosmic-store-hypr`
+
+### Flatpak apps don't appear in app launcher
+
+1. Log out and back in (environment variables need a session restart)
+2. Check XDG_DATA_DIRS includes Flatpak paths:
+   ```bash
+   echo $XDG_DATA_DIRS | tr ':' '\n' | grep flatpak
+   ```
+3. Re-run the symlink step:
+   ```bash
+   for d in ~/.local/share/flatpak/exports/share/applications /var/lib/flatpak/exports/share/applications; do
+     [ -d "$d" ] && find "$d" -maxdepth 1 -name '*.desktop' -exec ln -sf {} ~/.local/share/applications/ \;
+   done
+   ```
+
+### COSMIC Store won't build from AUR
+
+- Make sure `base-devel` and `git` are installed
+- Try rebuilding yay first: `cd /tmp && git clone https://aur.archlinux.org/yay.git && cd yay && makepkg -si`
+- Check if Rust is installed (COSMIC is written in Rust): `pacman -S rustup && rustup default stable`
+
+## Uninstalling
+
+```bash
+# Remove COSMIC Store
+yay -Rns cosmic-store-git
+
+# Remove wrapper and desktop entry
+sudo rm -f /usr/local/bin/cosmic-store-hypr
+rm -f ~/.local/share/applications/com.system76.CosmicStore.desktop
+
+# Remove environment config
+rm -f ~/.config/environment.d/flatpak.conf
+
+# Optionally remove Flatpak entirely
+sudo pacman -Rns flatpak
+
+# Log out and back in to apply changes
+```
+
+## Credits
+
+- [Omarchy](https://omarchy.com) - The Arch Linux distribution this was built for
+- [System76](https://system76.com/) - COSMIC Store and desktop environment
+- [Flatpak](https://flatpak.org/) - Sandboxed application framework
+- [Flathub](https://flathub.org/) - Flatpak app repository
+- [Hyprland](https://hyprland.org/) - Wayland compositor
+
+## License
+
+This project is provided as-is for the Omarchy community.
diff --git a/cosmic.sh b/cosmic.sh
index fa3db57..e58c077 100755
--- a/cosmic.sh
+++ b/cosmic.sh
@@ -1,8 +1,35 @@
 #!/usr/bin/env bash
+# ==============================================================================
+# COSMIC Store Installer for Omarchy (Arch Linux + Hyprland)
+#
+# This script installs System76's COSMIC Store on Omarchy so you can browse
+# and install Flatpak applications through a graphical app store — similar
+# to GNOME Software or KDE Discover, but built with the COSMIC desktop toolkit.
+#
+# Why this script exists:
+#   Omarchy uses Hyprland (a Wayland compositor), not COSMIC Desktop or GNOME.
+#   The COSMIC Store doesn't natively know how to launch apps through Hyprland's
+#   portal system. This script bridges that gap by:
+#     1. Installing the COSMIC Store from AUR
+#     2. Setting up Flatpak with the Flathub repository
+#     3. Creating a wrapper that tells COSMIC Store to use Hyprland's portal
+#     4. Configuring environment variables so Flatpak apps appear in the
+#        Omarchy app launcher (Walker/Elephant)
+#     5. Symlinking Flatpak .desktop files so they're discoverable
+#
+# The result: you get a full graphical app store that works seamlessly with
+# Hyprland, and installed Flatpak apps show up in your app launcher.
+# ==============================================================================
+
 set -euo pipefail
 
 echo "== COSMIC Store + Hyprland one-shot setup for Omarchy (Arch) =="
 
+# Utility functions:
+#   have() — checks if a command exists on the system
+#   need() — ensures a pacman package is installed (installs it if missing)
+#   append_if_missing() — adds a line to a file only if it's not already there
+#     (prevents duplicate entries when running the script multiple times)
 have(){ command -v "$1" >/dev/null 2>&1; }
 need(){ pacman -Q "$1" >/dev/null 2>&1 || sudo pacman -S --needed --noconfirm "$1"; }
 append_if_missing(){
@@ -11,10 +38,19 @@ append_if_missing(){
   grep -qxF "$line" "$file" || echo "$line" >> "$file"
 }
 
-# 0) sanity
+# Sanity check — this script uses pacman, so it only works on Arch-based systems.
 if ! have pacman; then echo "This script is for Arch/Arch-based systems."; exit 1; fi
 
-# 1) deps
+# Install dependencies:
+#   base-devel:                  Build tools needed to compile AUR packages
+#   git:                         Cloning AUR repos
+#   flatpak:                     The Flatpak package manager itself — sandboxed app
+#                                distribution system used by COSMIC Store
+#   xdg-desktop-portal:          D-Bus interface that lets sandboxed apps talk to the
+#                                desktop (file pickers, notifications, screen sharing)
+#   xdg-desktop-portal-gtk:      GTK fallback portal for dialogs
+#   xdg-desktop-portal-hyprland: Hyprland-specific portal (screen sharing, window picking)
+#   desktop-file-utils:          Provides update-desktop-database for app menu integration
 sudo pacman -Sy --noconfirm
 need base-devel
 need git
@@ -24,11 +60,19 @@ need xdg-desktop-portal-gtk
 need xdg-desktop-portal-hyprland
 need desktop-file-utils
 
-# 2) flathub (system + user)
+# Add the Flathub repository — this is the main app store for Flatpak with
+# thousands of applications. We add it at both system level (available to all
+# users) and user level (can install without sudo). --if-not-exists prevents
+# errors if it's already configured.
 sudo flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo || true
 flatpak  remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo || true
 
-# 3) install COSMIC Store (AUR)
+# Install COSMIC Store from AUR. cosmic-store-git is the development version
+# built from source. It's not in the official Arch repos because COSMIC is
+# still in active development by System76.
+#
+# Tries yay first (Omarchy default), then paru, and falls back to a manual
+# makepkg build if neither AUR helper is available.
 if have yay; then
   yay -S --noconfirm cosmic-store-git
 elif have paru; then
@@ -40,14 +84,21 @@ else
   makepkg -si --noconfirm
 fi
 
-# 4) wrapper so COSMIC Store uses Hyprland portal for launching apps
+# Create a wrapper script that sets XDG_CURRENT_DESKTOP=Hyprland before
+# launching COSMIC Store. Without this, COSMIC Store doesn't know it's
+# running under Hyprland and can't use the Hyprland portal to launch
+# installed apps. The portal is how sandboxed Flatpak apps open files,
+# show notifications, and interact with the desktop environment.
 sudo install -Dm755 /dev/stdin /usr/local/bin/cosmic-store-hypr <<'EOF'
 #!/usr/bin/env bash
 export XDG_CURRENT_DESKTOP=Hyprland
 exec cosmic-store "$@"
 EOF
 
-# 5) user desktop override to use our wrapper
+# Create a user-level .desktop entry that overrides the system one. User
+# entries in ~/.local/share/applications/ take priority over system entries
+# in /usr/share/applications/. This ensures COSMIC Store always launches
+# through our wrapper with the correct environment variables.
 USR_DESKTOP="$HOME/.local/share/applications/com.system76.CosmicStore.desktop"
 install -Dm644 /dev/stdin "$USR_DESKTOP" <<'EOF'
 [Desktop Entry]
@@ -61,7 +112,17 @@ Categories=System;PackageManager;
 StartupNotify=true
 EOF
 
-# 6) Omarchy launcher visibility: export env via systemd user + Hyprland config
+# Configure environment variables so Flatpak apps are visible in the
+# Omarchy app launcher (Walker/Elephant).
+#
+# The key is XDG_DATA_DIRS — this tells the desktop where to look for
+# .desktop files. Flatpak installs its .desktop files in special export
+# directories that aren't in the default search path. By adding them,
+# the app launcher can discover and display Flatpak apps.
+#
+# We set this in TWO places for reliability:
+#   1. ~/.config/environment.d/flatpak.conf — picked up by systemd user session
+#   2. ~/.config/hypr/hyprland.conf — picked up by Hyprland directly
 mkdir -p "$HOME/.config/environment.d"
 cat > "$HOME/.config/environment.d/flatpak.conf" <<'EOF'
 XDG_DATA_DIRS=%h/.local/share/flatpak/exports/share:/var/lib/flatpak/exports/share:/usr/local/share:/usr/share
@@ -72,22 +133,32 @@ HYPR_CFG="${XDG_CONFIG_HOME:-$HOME/.config}/hypr/hyprland.conf"
 append_if_missing "env = XDG_CURRENT_DESKTOP,Hyprland" "$HYPR_CFG"
 append_if_missing "env = XDG_DATA_DIRS,$HOME/.local/share/flatpak/exports/share:/var/lib/flatpak/exports/share:/usr/local/share:/usr/share" "$HYPR_CFG"
 
-# 7) belt & suspenders: symlink Flatpak .desktop files into user's applications dir
+# Belt and suspenders — symlink all Flatpak .desktop files directly into
+# the user's applications directory. Even if XDG_DATA_DIRS isn't picked up
+# correctly by every launcher, the symlinks ensure Flatpak apps are always
+# discoverable. Covers both user installs (~/.local/share/flatpak/) and
+# system installs (/var/lib/flatpak/).
 mkdir -p "$HOME/.local/share/applications"
 for d in "$HOME/.local/share/flatpak/exports/share/applications" "/var/lib/flatpak/exports/share/applications"; do
   [ -d "$d" ] && find "$d" -maxdepth 1 -name '*.desktop' -exec ln -sf {} "$HOME/.local/share/applications/" \;
 done
 
-# 8) update appstream + refresh desktop DB
+# Update Flatpak's appstream metadata (app descriptions, icons, categories)
+# and refresh the desktop database so the app launcher picks up new entries.
 flatpak update --appstream -y || true
 update-desktop-database "$HOME/.local/share/applications" >/dev/null || true
 sudo update-desktop-database /usr/share/applications >/dev/null || true
 
-# 9) restart portals so launches go through Hyprland
+# Restart the XDG desktop portal services so they pick up the new
+# configuration. The portals are D-Bus services that act as middlemen
+# between sandboxed Flatpak apps and the desktop. Restarting ensures
+# the Hyprland portal is active and ready to handle app launch requests.
 systemctl --user daemon-reload || true
 systemctl --user restart xdg-desktop-portal-hyprland xdg-desktop-portal || true
 
-# 10) quick test app (optional)
+# Install GNOME Calculator as a quick test to verify Flatpak is working.
+# If this succeeds, the full Flatpak pipeline is functional and you can
+# install any app from COSMIC Store or the command line.
 flatpak install -y flathub org.gnome.Calculator || true
 
 cat <<'EONOTE'