Add package-first build and distribution workflow

README.md

@@ -3,23 +3,61 @@
 
 Python X11 STT daemon that records audio, runs Whisper, applies local AI cleanup, and injects text.
 
-## Requirements
+## Target User
+
+The canonical Aman user is a desktop professional who wants dictation and
+rewriting features without learning Python tooling.
+
+- End-user path: native OS package install.
+- Developer path: Python/uv workflows.
+
+Persona details and distribution policy are documented in
+[`docs/persona-and-distribution.md`](docs/persona-and-distribution.md).
+
+## Install (Recommended)
+
+End users do not need `uv`.
+
+### Debian/Ubuntu (`.deb`)
+
+Download a release artifact and install it:
+
+```bash
+sudo apt install ./aman_<version>_<arch>.deb
+```
+
+Then enable the user service:
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now aman
+```
+
+### Arch Linux
+
+Use the generated packaging inputs (`PKGBUILD` + source tarball) in `dist/arch/`
+or your own packaging pipeline.
+
+## Distribution Matrix
+
+| Channel | Audience | Status |
+| --- | --- | --- |
+| Debian package (`.deb`) | End users on Ubuntu/Debian | Canonical |
+| Arch `PKGBUILD` + source tarball | Arch maintainers/power users | Supported |
+| Python wheel/sdist | Developers/integrators | Supported |
+
+## Runtime Dependencies
 
 - X11
-- `sounddevice` (PortAudio)
-- `faster-whisper`
-- `llama-cpp-python`
-- Tray icon deps: `gtk3`, `libayatana-appindicator3`
-- Python deps (core): `numpy`, `pillow`, `faster-whisper`, `llama-cpp-python`, `sounddevice`
-- X11 extras: `PyGObject`, `python-xlib`
-
-System packages (example names): `portaudio`/`libportaudio2`.
+- PortAudio runtime (`libportaudio2` or distro equivalent)
+- GTK3 and AppIndicator runtime (`gtk3`, `libayatana-appindicator3`)
+- Python GTK and X11 bindings (`python3-gi`/`python-gobject`, `python-xlib`)
 
 <details>
 <summary>Ubuntu/Debian</summary>
 
 ```bash
-sudo apt install -y portaudio19-dev libportaudio2 python3-gi gir1.2-gtk-3.0 libayatana-appindicator3-1
+sudo apt install -y libportaudio2 python3-gi python3-xlib gir1.2-gtk-3.0 libayatana-appindicator3-1
 ```
 
 </details>
@@ -28,7 +66,7 @@ sudo apt install -y portaudio19-dev libportaudio2 python3-gi gir1.2-gtk-3.0 liba
 <summary>Arch Linux</summary>
 
 ```bash
-sudo pacman -S --needed portaudio gtk3 libayatana-appindicator
+sudo pacman -S --needed portaudio gtk3 libayatana-appindicator python-gobject python-xlib
 ```
 
 </details>
@@ -37,7 +75,7 @@ sudo pacman -S --needed portaudio gtk3 libayatana-appindicator
 <summary>Fedora</summary>
 
 ```bash
-sudo dnf install -y portaudio portaudio-devel gtk3 libayatana-appindicator-gtk3
+sudo dnf install -y portaudio gtk3 libayatana-appindicator-gtk3 python3-gobject python3-xlib
 ```
 
 </details>
@@ -46,25 +84,15 @@ sudo dnf install -y portaudio portaudio-devel gtk3 libayatana-appindicator-gtk3
 <summary>openSUSE</summary>
 
 ```bash
-sudo zypper install -y portaudio portaudio-devel gtk3 libayatana-appindicator3-1
+sudo zypper install -y portaudio gtk3 libayatana-appindicator3-1 python3-gobject python3-python-xlib
 ```
 
 </details>
 
-## Python Daemon
-
-Install Python deps:
-
-X11 (supported):
-
-```bash
-uv sync --extra x11
-```
-
 ## Quickstart
 
 ```bash
-uv run aman run
+aman run
 ```
 
 On first launch, Aman opens a graphical settings window automatically.
@@ -191,15 +219,13 @@ STT hinting:
 ## systemd user service
 
 ```bash
-uv pip install --user .
-cp systemd/aman.service ~/.config/systemd/user/aman.service
-systemctl --user daemon-reload
-systemctl --user enable --now aman
+make install-service
 ```
 
 Service notes:
 
-- The user unit launches `aman` from `PATH`; ensure `~/.local/bin` is present in your user PATH.
+- The user unit launches `aman` from `PATH`.
+- Package installs should provide the `aman` command automatically.
 - Inspect failures with `systemctl --user status aman` and `journalctl --user -u aman -f`.
 
 ## Usage
@@ -228,21 +254,50 @@ AI processing:
 - Default local llama.cpp model.
 - Optional external API provider through `llm.provider=external_api`.
 
+Build and packaging (maintainers):
+
+```bash
+make build
+make package
+make package-deb
+make package-arch
+make release-check
+```
+
+`make package-deb` installs Python dependencies while creating the package.
+For offline packaging, set `AMAN_WHEELHOUSE_DIR` to a directory containing the
+required wheels.
+
 Control:
 
 ```bash
 make run
+make run config.example.json
 make doctor
 make self-check
 make check
 ```
 
-CLI (internal/support fallback, mostly for automation/tests):
+Developer setup (optional, `uv` workflow):
 
 ```bash
+uv sync --extra x11
 uv run aman run --config ~/.config/aman/config.json
-uv run aman doctor --config ~/.config/aman/config.json --json
-uv run aman self-check --config ~/.config/aman/config.json --json
-uv run aman version
-uv run aman init --config ~/.config/aman/config.json --force
+```
+
+Developer setup (optional, `pip` workflow):
+
+```bash
+make install-local
+aman run --config ~/.config/aman/config.json
+```
+
+CLI (internal/support fallback):
+
+```bash
+aman run --config ~/.config/aman/config.json
+aman doctor --config ~/.config/aman/config.json --json
+aman self-check --config ~/.config/aman/config.json --json
+aman version
+aman init --config ~/.config/aman/config.json --force
 ```