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/persona-and-distribution.md

@@ -36,18 +36,17 @@ Design implications:
 
 The current release channels are:
 
-1. Current end-user channel: Debian package (`.deb`) for Ubuntu/Debian users.
-2. Secondary: Arch package inputs (`PKGBUILD` + source tarball).
-3. Developer: wheel and sdist from `python -m build`.
-
-The portable X11 installer is the GA target channel, not the current shipped
-channel.
+1. Current canonical end-user channel: portable X11 bundle (`aman-x11-linux-<version>.tar.gz`).
+2. Secondary packaged channel: Debian package (`.deb`) for Ubuntu/Debian users.
+3. Secondary maintainer channel: Arch package inputs (`PKGBUILD` + source tarball).
+4. Developer: wheel and sdist from `python -m build`.
 
 ## GA Target Support Contract
 
 For X11 GA, Aman supports:
 
 - X11 desktop sessions only.
+- System CPython `3.10`, `3.11`, or `3.12` for the portable installer.
 - Runtime dependencies installed from the distro package manager.
 - `systemd --user` as the supported daily-use path.
 - `aman run` as the foreground setup, support, and debugging path.
@@ -59,6 +58,14 @@ For X11 GA, Aman supports:
 not mean native-package parity or exhaustive certification for every Linux
 variant.
 
+## Canonical end-user lifecycle
+
+- Install: extract the portable bundle and run `./install.sh`.
+- Update: extract the newer portable bundle and run its `./install.sh`.
+- Uninstall: run `~/.local/share/aman/current/uninstall.sh`.
+- Purge uninstall: run `~/.local/share/aman/current/uninstall.sh --purge`.
+- Recovery: `aman doctor` -> `aman self-check` -> `journalctl --user -u aman` -> `aman run --verbose`.
+
 ## Out of Scope for X11 GA
 
 - Wayland production support.

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`

docs/release-checklist.md

@@ -1,7 +1,7 @@
 # Release Checklist
 
-This checklist covers both current releases and the future X11 GA bar. The GA
-signoff sections are required for `v1.0.0` and later.
+This checklist covers the current portable X11 release flow and the remaining
+GA signoff bar. The GA signoff sections are required for `v1.0.0` and later.
 
 1. Update `CHANGELOG.md` with final release notes.
 2. Bump `project.version` in `pyproject.toml`.
@@ -16,19 +16,25 @@ signoff sections are required for `v1.0.0` and later.
    - `make package`
 6. Verify artifacts:
    - `dist/*.whl`
-   - `dist/*.tar.gz`
+   - `dist/aman-x11-linux-<version>.tar.gz`
+   - `dist/aman-x11-linux-<version>.tar.gz.sha256`
    - `dist/*.deb`
    - `dist/arch/PKGBUILD`
 7. Tag release:
    - `git tag vX.Y.Z`
    - `git push origin vX.Y.Z`
 8. Publish release and upload package artifacts from `dist/`.
-9. GA support-contract signoff (`v1.0.0` and later):
+9. Portable bundle release signoff:
+   - `README.md` points end users to the portable bundle first.
+   - [`docs/portable-install.md`](./portable-install.md) matches the shipped install, upgrade, uninstall, and purge behavior.
+   - `make package-portable` produces the portable tarball and checksum.
+   - `docs/x11-ga/portable-validation-matrix.md` contains current automated evidence and release-specific manual validation entries.
+10. GA support-contract signoff (`v1.0.0` and later):
    - `README.md` and `docs/persona-and-distribution.md` agree on supported environment assumptions.
    - The support matrix names X11, runtime dependency ownership, `systemd --user`, and the representative distro families.
    - Service mode is documented as the default daily-use path and `aman run` as the manual support/debug path.
    - The recovery sequence `aman doctor` -> `aman self-check` -> `journalctl --user -u aman` -> `aman run --verbose` is documented consistently.
-10. GA validation signoff (`v1.0.0` and later):
+11. GA validation signoff (`v1.0.0` and later):
    - Validation evidence exists for Debian/Ubuntu, Arch, Fedora, and openSUSE.
    - The portable installer, upgrade path, and uninstall path are validated.
    - End-user docs and release notes match the shipped artifact set.

docs/x11-ga/README.md

@@ -33,7 +33,7 @@ The GA support promise for Aman should be:
 
 - Linux desktop sessions running X11.
 - Mainstream distros with `systemd --user` available.
-- System `python3` 3.10+ available for the portable installer.
+- System CPython `3.10`, `3.11`, or `3.12` available for the portable installer.
 - Runtime dependencies installed from the distro package manager.
 - Service mode is the default end-user mode.
 - Foreground `aman run` remains a support and debugging path, not the primary daily-use path.
@@ -87,7 +87,11 @@ Any future docs, tray copy, and release notes should point users to this same se
   the GA contract; `docs/release-checklist.md` now includes GA signoff gates;
   CLI help text now matches the same service/support language.
 - [ ] [Milestone 2: Portable Install, Update, and Uninstall](./02-portable-install-update-uninstall.md)
-  Build one reliable end-user lifecycle that works across mainstream X11 distros.
+  Implementation landed on 2026-03-12: the portable bundle, installer,
+  uninstaller, docs, and automated lifecycle tests are in the repo. Leave this
+  milestone open until the representative distro rows in
+  [`portable-validation-matrix.md`](./portable-validation-matrix.md) are filled
+  with real manual validation evidence.
 - [ ] [Milestone 3: Runtime Reliability and Diagnostics](./03-runtime-reliability-and-diagnostics.md)
   Make startup, failure handling, and recovery predictable.
 - [ ] [Milestone 4: First-Run UX and Support Docs](./04-first-run-ux-and-support-docs.md)

docs/x11-ga/portable-validation-matrix.md

@@ -0,0 +1,43 @@
+# Portable Validation Matrix
+
+This document tracks milestone 2 and GA validation evidence for the portable
+X11 bundle.
+
+## Automated evidence
+
+Completed on 2026-03-12:
+
+- `PYTHONPATH=src python3 -m unittest tests.test_portable_bundle`
+  - covers bundle packaging shape, fresh install, upgrade, uninstall, purge,
+    unmanaged-conflict fail-fast behavior, and rollback after service-start
+    failure
+- `PYTHONPATH=src python3 -m unittest tests.test_aman_cli tests.test_diagnostics tests.test_portable_bundle`
+  - confirms portable bundle work did not regress the CLI help or diagnostics
+    surfaces used in the support flow
+
+## Manual distro validation
+
+These rows must be filled with real results before milestone 2 can be closed as
+fully complete for GA evidence.
+
+| Distro family | Fresh install | First service start | Upgrade | Uninstall | Reinstall | Reboot or service restart | Missing dependency recovery | Conflict with prior package install | Reviewer | Status | Notes |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| Debian/Ubuntu | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | |
+| Arch | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | |
+| Fedora | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | |
+| openSUSE | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | |
+
+## Required release scenarios
+
+Every row above must cover:
+
+- runtime dependencies installed with the documented distro command
+- bundle checksum verified
+- `./install.sh` succeeds
+- `systemctl --user enable --now aman` succeeds through the installer
+- first launch reaches the normal settings or tray workflow
+- upgrade preserves `~/.config/aman/` and `~/.cache/aman/`
+- uninstall removes the command shim and user service cleanly
+- reinstall succeeds after uninstall
+- missing dependency path gives actionable remediation
+- pre-existing distro package or unmanaged shim conflict fails clearly