Ship the portable X11 bundle lifecycle

Implement milestone 2 around a portable X11 release bundle instead of\nkeeping distro packages as the only end-user path.\n\nAdd make/package scripts plus a portable installer helper that builds the\ntarball, creates a user-scoped venv install, manages the user service, handles\nupgrade rollback, and supports uninstall with optional purge.\n\nFlip the end-user docs to the portable bundle, add a dedicated install guide\nand validation matrix, and leave the roadmap milestone open only for the\nremaining manual distro validation evidence.\n\nValidation: python3 -m py_compile src/*.py packaging/portable/portable_installer.py tests/test_portable_bundle.py; PYTHONPATH=src python3 -m unittest tests.test_portable_bundle; PYTHONPATH=src python3 -m unittest tests.test_aman_cli tests.test_diagnostics tests.test_portable_bundle; PYTHONPATH=src python3 -m unittest discover -s tests -p 'test_*.py'

docs/portable-install.md

@@ -0,0 +1,146 @@
+# Portable X11 Install Guide
+
+This is the canonical end-user install path for Aman on X11.
+
+## Supported environment
+
+- X11 desktop session
+- `systemd --user`
+- System CPython `3.10`, `3.11`, or `3.12`
+- Runtime dependencies installed from the distro package manager
+
+## Runtime dependencies
+
+Install the runtime dependencies for your distro before running `install.sh`.
+
+### Ubuntu/Debian
+
+```bash
+sudo apt install -y libportaudio2 python3-gi python3-xlib gir1.2-gtk-3.0 libayatana-appindicator3-1
+```
+
+### Arch Linux
+
+```bash
+sudo pacman -S --needed portaudio gtk3 libayatana-appindicator python-gobject python-xlib
+```
+
+### Fedora
+
+```bash
+sudo dnf install -y portaudio gtk3 libayatana-appindicator-gtk3 python3-gobject python3-xlib
+```
+
+### openSUSE
+
+```bash
+sudo zypper install -y portaudio gtk3 libayatana-appindicator3-1 python3-gobject python3-python-xlib
+```
+
+## Fresh install
+
+1. Download `aman-x11-linux-<version>.tar.gz` and `aman-x11-linux-<version>.tar.gz.sha256`.
+2. Verify the checksum.
+3. Extract the bundle.
+4. Run `install.sh`.
+
+```bash
+sha256sum -c aman-x11-linux-<version>.tar.gz.sha256
+tar -xzf aman-x11-linux-<version>.tar.gz
+cd aman-x11-linux-<version>
+./install.sh
+```
+
+The installer:
+
+- creates `~/.local/share/aman/<version>/`
+- updates `~/.local/share/aman/current`
+- creates `~/.local/bin/aman`
+- installs `~/.config/systemd/user/aman.service`
+- runs `systemctl --user daemon-reload`
+- runs `systemctl --user enable --now aman`
+
+If `~/.config/aman/config.json` does not exist yet, the first service start
+opens the graphical settings window automatically.
+
+After saving the first-run settings, validate the install with:
+
+```bash
+aman self-check --config ~/.config/aman/config.json
+```
+
+## Upgrade
+
+Extract the new bundle and run the new `install.sh` again.
+
+```bash
+tar -xzf aman-x11-linux-<new-version>.tar.gz
+cd aman-x11-linux-<new-version>
+./install.sh
+```
+
+Upgrade behavior:
+
+- existing config in `~/.config/aman/` is preserved
+- existing cache in `~/.cache/aman/` is preserved
+- the old installed version is removed after the new one passes install and service restart
+- the service is restarted on the new version automatically
+
+## Uninstall
+
+Run the installed uninstaller from the active install:
+
+```bash
+~/.local/share/aman/current/uninstall.sh
+```
+
+Default uninstall removes:
+
+- `~/.local/share/aman/`
+- `~/.local/bin/aman`
+- `~/.config/systemd/user/aman.service`
+
+Default uninstall preserves:
+
+- `~/.config/aman/`
+- `~/.cache/aman/`
+
+## Purge uninstall
+
+To remove config and cache too:
+
+```bash
+~/.local/share/aman/current/uninstall.sh --purge
+```
+
+## Filesystem layout
+
+- Installed payload: `~/.local/share/aman/<version>/`
+- Active symlink: `~/.local/share/aman/current`
+- Command shim: `~/.local/bin/aman`
+- Install state: `~/.local/share/aman/install-state.json`
+- User service: `~/.config/systemd/user/aman.service`
+
+## Conflict resolution
+
+The portable installer refuses to overwrite:
+
+- an unmanaged `~/.local/bin/aman`
+- an unmanaged `~/.config/systemd/user/aman.service`
+- another non-portable `aman` found earlier in `PATH`
+
+If you already installed Aman from a distro package:
+
+1. uninstall the distro package
+2. remove any leftover `aman` command from `PATH`
+3. remove any leftover user service file
+4. rerun the portable `install.sh`
+
+## Recovery path
+
+If installation succeeds but runtime behavior is wrong, use the supported recovery order:
+
+1. `aman doctor --config ~/.config/aman/config.json`
+2. `aman self-check --config ~/.config/aman/config.json`
+3. `journalctl --user -u aman -f`
+4. `aman run --config ~/.config/aman/config.json --verbose`