docs: document AppImage workflow

docs/appimage.md

@@ -0,0 +1,86 @@
+# AppImage Build Guide
+
+ScanSlicer includes a full AppImage packaging workflow under `packaging/appimage/`.
+
+## Files
+
+- `packaging/appimage/AppImageBuilder.yml`: AppDir recipe and AppImage config
+- `packaging/appimage/build-appimage.sh`: local build script
+- `packaging/appimage/build-appimage-docker.sh`: containerized build wrapper
+- `packaging/appimage/Dockerfile`: AppImage build environment
+- desktop entry file in `packaging/appimage/`
+- application icon file in `packaging/appimage/`
+
+## Local Build
+
+Prerequisites:
+
+- `uv`
+- `appimage-builder` (or custom binary via `APPIMAGE_BUILDER_BIN`)
+
+Command:
+
+```bash
+bash packaging/appimage/build-appimage.sh
+```
+
+What the script does:
+
+1. Exports runtime requirements from `uv.lock` to `appimage/build/requirements.txt`
+2. Builds wheel into `appimage/build/`
+3. Appends wheel path to requirements list
+4. Sets:
+  - `SCANSLICER_ROOT`
+  - `SCANSLICER_APPDIR`
+  - `SCANSLICER_REQUIREMENTS`
+5. Runs `appimage-builder` with `AppImageBuilder.yml`
+6. Moves `.AppImage` and `.zsync` artifacts to `appimage/dist/`
+
+## Dockerized Build
+
+Prerequisite:
+
+- Docker
+
+Command:
+
+```bash
+bash packaging/appimage/build-appimage-docker.sh
+```
+
+What it does:
+
+1. Builds an image from `packaging/appimage/Dockerfile`
+2. Runs the local AppImage build script inside the container
+3. Applies host UID/GID ownership to generated `appimage/` outputs
+
+Optional environment variables:
+
+- `APPIMAGE_DOCKER_IMAGE` (default: `scanslicer-appimage-builder`)
+- `HOST_UID` and `HOST_GID`
+
+## Recipe Notes
+
+`AppImageBuilder.yml` currently:
+
+- Uses Ubuntu Noble apt sources
+- Bundles Python and runtime shared libs
+- Removes bundled Qt system libs to prefer PySide wheel Qt runtime
+- Installs Python dependencies and project wheel into AppDir `/usr`
+- Injects desktop entry and icon assets during `after_bundle`
+
+Runtime environment variables set in AppDir include:
+
+- `PYTHONHOME`
+- `PYTHONNOUSERSITE`
+- `QT_PLUGIN_PATH`
+- `LD_LIBRARY_PATH`
+- `PATH`
+
+## Output
+
+Expected output artifact location:
+
+- `appimage/dist/ScanSlicer-<version>-x86_64.AppImage`
+
+Intermediate build files are kept under `appimage/build/`.