diff --git a/README.ai.md b/README.ai.md
new file mode 100644
index 0000000..17f6157
--- /dev/null
+++ b/README.ai.md
@@ -0,0 +1,170 @@
+# imports
+
+## distros.sh
+
+Import the script inside your own script like this:
+
+```bash
+url="https://git.k4li.de/scripts/imports/raw/branch/main/distros.sh"
+import="$(mktemp)"
+if command_exists curl; then
+  curl -fsSL $url -o $import
+else
+  echo "curl is required, but missing.."
+  exit 1
+fi
+
+source "$import"
+sleep 0.3
+rm "$import"
+```
+
+### DISTRIBUTION VARIABLES
+
+After importing, these boolean variables are available for distribution checks:
+
+$arch     - true/false for Arch Linux and derivatives
+$debian - true/false for Debian and derivatives  
+$ubuntu   - true/false for Ubuntu and derivatives
+$fedora - true/false for Fedora and derivatives
+$opensuse - true/false for openSUSE
+$alpine - true/false for Alpine Linux
+$distro - contains the detected distro name (e.g. "arch", "debian")
+
+Example usage:
+
+```bash
+if $arch; then
+    echo "Using Arch Linux!"
+fi
+
+case "$distro" in
+    arch) echo "Arch detected" ;;
+    debian) echo "Debian detected" ;;
+esac
+```
+
+### CORE FUNCTIONS
+
+1. Package Management:
+
+\_install pkg1 pkg2 - Installs packages using the correct package manager
+\_remove pkg1 pkg2 - Removes packages (CAUTION: no confirmation!)
+checkAndInstall pkg1 pkg2 - Checks if command exists, installs if missing
+
+Example:
+
+```bash
+_install neovim git
+checkAndInstall curl wget
+```
+
+2. Logging Functions:
+
+echo_error "message" - Red error message
+echo_warning "message" - Yellow warning message  
+echo_info "message" - Blue info message
+echo_note "message" - Green note message
+echo_pkg type "message" - Special package-related messages
+
+Types for echo_pkg:
+
+- build: Building messages
+- clone: Cloning messages
+- install: Installation messages
+- deps: Dependency messages
+
+Example:
+
+```bash
+echo_error "Failed to install!"
+echo_pkg install "Installing package"
+```
+
+3. Utility Functions:
+
+command_exists cmd - Checks if command exists (silent)
+run cmd - Runs command with silent mode support
+source_script url - Sources another script from URL or file
+silentexec cmd - Runs command silently
+
+Example:
+
+```bash
+if command_exists git; then
+    run git clone url
+fi
+
+source_script "https://example.com/script.sh"
+```
+
+### DISTRIBUTION-SPECIFIC FEATURES
+
+For Debian/Ubuntu:
+
+- Version codename variables:
+  $trixie (Debian 13)
+  $bookworm (Debian 12)  
+  $jammy (Ubuntu 22.04)
+  $focal (Ubuntu 20.04)
+
+For Fedora:
+
+- Version variables like $fedora_40 for Fedora 40
+
+For Arch:
+
+- $aur - true if yay/paru is available
+
+### ADVANCED USAGE
+
+1. Handling dependencies per distro:
+
+```bash
+getDeps() {
+    local depsDebian=(git cmake)
+    local depsArch=(git base-devel)
+
+    declare -A deps=(
+        [debian]="depsDebian"
+        [arch]="depsArch"
+    )
+
+    declare -n pkgArray="${deps[$distro]}"
+    checkAndInstall "${pkgArray[@]}"
+}
+```
+
+2. Silent mode:
+
+```bash
+silent=true  # Enable silent mode
+_install pkg # Will install without output
+```
+
+3. Conditional operations:
+
+```bash
+if ! command_exists node; then
+    echo_info "Installing Node.js..."
+    _install nodejs
+fi
+```
+
+### BEST PRACTICES
+
+1. Always check for commands before using them
+2. Use the provided echo functions for consistent output
+3. For distro-specific code, check the boolean variables first
+4. Use arrays with checkAndInstall for multiple packages
+5. Use source_script for modular script organization
+
+### TROUBLESHOOTING
+
+If something doesn't work:
+
+1. Check if /etc/os-release exists
+2. Verify internet connection for remote scripts
+3. Check permissions (script handles sudo automatically)
+4. Verify $distro variable matches your system
+5. Check if required package managers are available
diff --git a/README.md b/README.md
index 4894367..eeafbd3 100644
--- a/README.md
+++ b/README.md
@@ -53,10 +53,10 @@ esac
 
 | variable  | values                                                                  |
 | --------- | ----------------------------------------------------------------------- |
-| $arch     | `true/false`                                                            |
-| $debian   | `true/false`                                                            |
-| $ubuntu   | `true/false`                                                            |
-| $fedora   | `true/false`                                                            |
-| $opensuse | `true/false`                                                            |
-| $alpine   | `true/false`                                                            |
+| $arch     | boolean: `true`/`false`                                                 |
+| $debian   | boolean: `true`/`false`                                                 |
+| $ubuntu   | boolean: `true`/`false`                                                 |
+| $fedora   | boolean: `true`/`false`                                                 |
+| $opensuse | boolean: `true`/`false`                                                 |
+| $alpine   | boolean: `true`/`false`                                                 |
 | $distros  | One value of `arch`, `debian`, `ubuntu`, `fedora`, `opensuse`, `alpine` |