From c92c4c53a6eb68d5d0e975e4f1e7aac3083c649c Mon Sep 17 00:00:00 2001
From: Jason Ross <jason.ross841@gmail.com>
Date: Tue, 26 Aug 2025 17:07:29 -0500
Subject: [PATCH] documentation update - clarify which is for developers and
 add instructions for Arch users

---
 README.md |  2 +-
 WIKI.md   | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 90 insertions(+), 1 deletion(-)
 create mode 100644 WIKI.md

diff --git a/README.md b/README.md
index 2ae387a..fef39e0 100644
--- a/README.md
+++ b/README.md
@@ -18,7 +18,7 @@ A simple Windows GUI tool to pull folders from an Android device using ADB (Andr
 - [Poetry](https://python-poetry.org/) for dependency management
 - (Optional) pyenv for Python version managment
 
-## Installation
+## Installation (Developers)
 
 1. Clone this repository:
 
diff --git a/WIKI.md b/WIKI.md
new file mode 100644
index 0000000..1072b13
--- /dev/null
+++ b/WIKI.md
@@ -0,0 +1,89 @@
+# Arch Linux installation instructions
+
+## Arch Linux installation
+
+These instructions describe how Arch users can install the Linux build produced by the project's `simple-release.yml` workflow. The workflow produces an Arch package named similar to:
+
+```
+android-file-handler-<VERSION>-1-x86_64.pkg.tar.zst
+```
+
+Find that file on the project's GitHub Releases page for the matching version and download it.
+
+### System install (recommended)
+
+Use pacman to install the downloaded package so package scripts run and files are placed in standard system locations:
+
+```bash
+# from the directory with the downloaded package
+sudo pacman -U ./android-file-handler-1.2.3-1-x86_64.pkg.tar.zst
+```
+
+Replace the filename with the actual release artifact you downloaded. After installation you should have:
+
+- Binary: e.g. `/usr/local/bin/android-file-handler`
+- Desktop entry: `/usr/share/applications/android-file-handler.desktop`
+- Icons: under `/usr/share/icons/hicolor/...`
+
+Launch the app from your application menu (search "Android File Handler") or from a terminal:
+
+```bash
+android-file-handler
+```
+
+### Non-root / manual install
+
+If you cannot or do not want to install the package system-wide, you can extract and install files into your home directory manually:
+
+1. Extract the package to a temporary folder:
+
+```bash
+mkdir -p /tmp/afh_pkg
+tar -I zstd -xvf android-file-handler-1.2.3-1-x86_64.pkg.tar.zst -C /tmp/afh_pkg
+```
+
+2. Copy the executable and desktop/icon files to your local directories:
+
+```bash
+mkdir -p ~/.local/bin ~/.local/share/applications ~/.local/share/icons/hicolor/256x256/apps
+cp /tmp/afh_pkg/usr/local/bin/android-file-handler ~/.local/bin/
+chmod +x ~/.local/bin/android-file-handler
+
+# Copy desktop entry and icon (paths inside the package may vary)
+cp /tmp/afh_pkg/usr/share/applications/android-file-handler.desktop ~/.local/share/applications/
+cp /tmp/afh_pkg/usr/share/icons/hicolor/256x256/apps/android-file-handler.png ~/.local/share/icons/hicolor/256x256/apps/
+```
+
+3. (Optional) Update desktop and icon caches so the menu picks up the new entry immediately:
+
+```bash
+update-desktop-database ~/.local/share/applications || true
+gtk-update-icon-cache -t -f ~/.local/share/icons/hicolor || true
+```
+
+Now run the app from the menu or with `~/.local/bin/android-file-handler`.
+
+### Verify package contents
+
+To inspect the package contents without installing:
+
+```bash
+# list files in the package
+pacman -Qlp android-file-handler-1.2.3-1-x86_64.pkg.tar.zst
+```
+
+To query package info (after installation):
+
+```bash
+pacman -Qi android-file-handler
+```
+
+### Troubleshooting
+
+- If the app does not appear in your menu, try logging out/in or run the cache update commands above.
+- If icons are missing, ensure the `icons/hicolor/*/apps/android-file-handler.png` entries were copied to the correct theme directories.
+- If you manually copied files, ensure `~/.local/bin` is on your PATH; add it to `~/.profile` if necessary:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```