diff --git a/scripts/distro-package-map.yaml b/scripts/distro-package-map.yaml
new file mode 100644
index 0000000..95280d8
--- /dev/null
+++ b/scripts/distro-package-map.yaml
@@ -0,0 +1,235 @@
+# Package name mapping for different Linux distributions
+# This file documents the package names used by the installer for each distribution
+# It serves as a reference for manual installation and for adding support for new distributions
+
+# System packages required for Vocalinux
+system_packages:
+  # GTK3 and PyGObject
+  gtk3:
+    ubuntu: ["python3-gi", "python3-gi-cairo", "gir1.2-gtk-3.0", "gir1.2-gdkpixbuf-2.0"]
+    debian: ["python3-gi", "python3-gi-cairo", "gir1.2-gtk-3.0", "gir1.2-gdkpixbuf-2.0", "libcairo2-dev"]
+    fedora: ["python3-gobject", "gtk3", "gobject-introspection-devel"]
+    arch: ["python-gobject", "gtk3", "gobject-introspection", "python-cairo"]
+    opensuse: ["python3-gobject", "python3-gobject-cairo", "gtk3", "gobject-introspection-devel"]
+    gentoo: ["dev-python/pygobject:3", "x11-libs/gtk+:3"]
+    alpine: ["py3-gobject3", "py3-cairo", "gtk+3.0"]
+    void: ["python3-gobject", "gtk+3"]
+    solus: ["python3-gobject", "gtk3"]
+
+  # AppIndicator / Ayatana AppIndicator
+  appindicator:
+    ubuntu: ["gir1.2-appindicator3-0.1"]
+    debian_11: ["gir1.2-ayatanaappindicator3-0.1"]
+    debian_12_plus: ["gir1.2-ayatanaappindicator3-0.1"]
+    fedora: ["libappindicator-gtk3"]
+    arch: ["libappindicator-gtk3"]
+    opensuse: ["libappindicator-gtk3"]
+    gentoo: ["dev-libs/libappindicator:3"]
+    alpine: ["libayatana-appindicator"]
+    void: ["libappindicator"]
+    solus: ["libappindicator"]
+
+  # PortAudio
+  portaudio:
+    ubuntu: ["portaudio19-dev"]
+    debian: ["portaudio19-dev"]
+    fedora: ["portaudio-devel"]
+    arch: ["portaudio"]
+    opensuse: ["portaudio-devel"]
+    gentoo: ["media-libs/portaudio"]
+    alpine: ["portaudio-dev"]
+    void: ["portaudio-devel"]
+    solus: ["portaudio-devel"]
+
+  # Python development
+  python_dev:
+    ubuntu: ["python3-dev", "python3-venv"]
+    debian: ["python3-dev", "python3-venv"]
+    fedora: ["python3-devel", "python3-virtualenv"]
+    arch: ["python"]  # Arch includes venv by default
+    opensuse: ["python3-devel", "python3-virtualenv"]
+    gentoo: ["dev-lang/python:3.8"]
+    alpine: ["py3-virtualenv"]
+    void: ["python3-devel"]
+    solus: ["python3-virtualenv"]
+
+  # Package build tools
+  build_tools:
+    ubuntu: ["pkg-config", "wget", "curl", "unzip"]
+    debian: ["pkg-config", "wget", "curl", "unzip"]
+    fedora: ["pkg-config", "wget", "curl", "unzip"]
+    arch: ["pkgconf", "wget", "curl", "unzip"]
+    opensuse: ["pkg-config", "wget", "curl", "unzip"]
+    gentoo: ["dev-util/pkgconfig", "net-misc/wget", "net-misc/curl", "app-arch/unzip"]
+    alpine: ["pkgconf", "wget", "curl", "unzip"]
+    void: ["pkg-config", "wget", "curl", "unzip"]
+    solus: ["pkg-config", "wget", "curl", "unzip"]
+
+  # Text injection tools
+  xdotool:
+    ubuntu: ["xdotool"]
+    debian: ["xdotool"]
+    fedora: ["xdotool"]
+    arch: ["xdotool"]
+    opensuse: ["xdotool"]
+    gentoo: ["x11-misc/xdotool"]
+    alpine: ["xdotool"]
+    void: ["xdotool"]
+    solus: ["xdotool"]
+
+  wtype:
+    ubuntu: ["wtype"]
+    debian: ["wtype"]
+    fedora: ["wtype"]
+    arch: ["wtype"]
+    opensuse: ["wtype"]
+    gentoo: ["x11-misc/wtype"]
+    alpine: ["wtype"]
+    void: ["wtype"]
+    solus: ["wtype"]
+
+  ydotool:
+    ubuntu: ["ydotool"]
+    debian: ["ydotool"]
+    fedora: ["ydotool"]
+    arch: ["ydotool"]
+    opensuse: ["ydotool"]
+    gentoo: ["app-misc/ydotool"]
+    alpine: ["ydotool"]
+    void: ["ydotool"]
+    solus: ["ydotool"]
+
+# Command templates for package managers
+install_commands:
+  apt: "sudo apt install -y {packages}"
+  apt_update: "sudo apt update"
+
+  dnf: "sudo dnf install -y {packages}"
+  dnf_update: "sudo dnf update -y"  # Optional update
+
+  yum: "sudo yum install -y {packages}"
+
+  pacman: "sudo pacman -S --noconfirm {packages}"
+  pacman_update: "sudo pacman -Syu"  # Optional update
+
+  zypper: "sudo zypper install -y {packages}"
+  zypper_update: "sudo zypper refresh"  # Optional update
+
+  emerge: "sudo emerge {packages}"
+
+  apk: "sudo apk add {packages}"
+  apk_update: "sudo apk update"  # Optional update
+
+  xbps: "sudo xbps-install -Sy {packages}"
+  xbps_update: "sudo xbps-install -Sy"  # Updates sync during install
+
+  eopkg: "sudo eopkg install -y {packages}"
+  eopkg_update: "sudo eopkg upgrade"  # Optional update
+
+# Distribution family mappings
+# This helps determine which package manager and package names to use
+distribution_families:
+  # Ubuntu family
+  - id: ubuntu
+    family: ubuntu
+    package_manager: apt
+    variations: [pop, linuxmint, elementary, zorin]
+
+  # Debian family
+  - id: debian
+    family: debian
+    package_manager: apt
+    variations: []
+
+  # Fedora family
+  - id: fedora
+    family: fedora
+    package_manager: dnf
+    variations: [rhel, centos, rocky, almalinux]
+
+  # Arch family
+  - id: arch
+    family: arch
+    package_manager: pacman
+    variations: [manjaro, endeavouros]
+
+  # openSUSE family
+  - id: opensuse
+    family: suse
+    package_manager: zypper
+    variations: []
+
+  # Gentoo
+  - id: gentoo
+    family: gentoo
+    package_manager: emerge
+    variations: []
+
+  # Alpine
+  - id: alpine
+    family: alpine
+    package_manager: apk
+    variations: []
+
+  # Void Linux
+  - id: void
+    family: void
+    package_manager: xbps
+    variations: []
+
+  # Solus
+  - id: solus
+    family: solus
+    package_manager: eopkg
+    variations: []
+
+  # Mageia
+  - id: mageia
+    family: mageia
+    package_manager: dnf  # Prefers dnf, falls back to urpmi
+    variations: []
+
+# Notes for specific distributions
+distribution_notes:
+  debian_11:
+    appindicator: "Use gir1.2-ayatanaappindicator3-0.1 instead of gir1.2-appindicator3-0.1"
+
+  gentoo:
+    general: "Gentoo compiles packages from source. Installation will take longer."
+    python: "Ensure Python 3.8+ is set as the active version"
+
+  alpine:
+    general: "Alpine uses musl libc. Some Python packages may not have pre-built wheels."
+
+  nixos:
+    general: "NixOS is not supported due to completely different filesystem layout."
+
+  void:
+    general: "Void Linux may use either glibc or musl libc. glibc version recommended."
+
+# Architecture-specific library paths
+library_paths:
+  typelib:
+    # Debian/Ubuntu multiarch paths
+    - /usr/lib/x86_64-linux-gnu/girepository-1.0
+    - /usr/lib/aarch64-linux-gnu/girepository-1.0
+    - /usr/lib/arm-linux-gnueabihf/girepository-1.0
+    - /usr/lib/riscv64-linux-gnu/girepository-1.0
+    - /usr/lib/powerpc64le-linux-gnu/girepository-1.0
+    - /usr/lib/s390x-linux-gnu/girepository-1.0
+
+    # Fedora/RHEL
+    - /usr/lib64/girepository-1.0
+
+    # Arch, generic
+    - /usr/lib/girepository-1.0
+
+    # Local installations
+    - /usr/local/lib/girepository-1.0
+    - /usr/local/lib64/girepository-1.0
+
+  models:
+    - /usr/local/share/vocalinux/models
+    - /usr/share/vocalinux/models
+    - /usr/lib64/vocalinux/models
+    - /usr/lib/vocalinux/models