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'

README.md

@@ -8,23 +8,22 @@ Python X11 STT daemon that records audio, runs Whisper, applies local AI cleanup
 The canonical Aman user is a desktop professional who wants dictation and
 rewriting features without learning Python tooling.
 
-- End-user path today: distro-specific release artifacts.
-- GA target: portable X11 release bundle for mainstream distros.
+- End-user path: portable X11 release bundle for mainstream distros.
+- Alternate package channels: Debian/Ubuntu `.deb` and Arch packaging inputs.
 - Developer path: Python/uv workflows.
 
 Persona details and distribution policy are documented in
 [`docs/persona-and-distribution.md`](docs/persona-and-distribution.md).
 
-## Current Release Channels
+## Release Channels
 
-Aman is not GA yet for X11 users across distros. Today the maintained release
+Aman is not GA yet for X11 users across distros. The maintained release
 channels are:
 
-- Debian/Ubuntu `.deb`: current end-user channel.
-- Arch `PKGBUILD` plus source tarball: current maintainer and power-user channel.
+- Portable X11 bundle: current canonical end-user channel.
+- Debian/Ubuntu `.deb`: secondary packaged channel.
+- Arch `PKGBUILD` plus source tarball: secondary maintainer and power-user channel.
 - Python wheel and sdist: current developer and integrator channel.
-- The portable X11 installer described in the GA roadmap is the target
-  distribution model, but it is not shipped yet.
 
 ## GA Support Matrix
 
@@ -36,9 +35,42 @@ channels are:
 | Manual foreground mode | `aman run` for setup, support, and debugging |
 | Canonical recovery sequence | `aman doctor` -> `aman self-check` -> `journalctl --user -u aman` -> `aman run --verbose` |
 | Representative GA validation families | Debian/Ubuntu, Arch, Fedora, openSUSE |
-| Portable installer prerequisite | System `python3` 3.10+ for the future GA installer |
+| Portable installer prerequisite | System CPython `3.10`, `3.11`, or `3.12` |
 
-## Current Install Instructions
+## Install (Portable Bundle)
+
+Download `aman-x11-linux-<version>.tar.gz` and
+`aman-x11-linux-<version>.tar.gz.sha256`, install the runtime dependencies for
+your distro, then install the bundle:
+
+```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 writes the user service, updates `~/.local/bin/aman`, and runs
+`systemctl --user enable --now aman` automatically.
+On first service start, Aman opens the graphical settings window if
+`~/.config/aman/config.json` does not exist yet.
+
+Upgrade by extracting the newer bundle and running its `install.sh` again.
+Config and cache are preserved by default.
+
+Uninstall with:
+
+```bash
+~/.local/share/aman/current/uninstall.sh
+```
+
+Add `--purge` if you also want to remove `~/.config/aman/` and
+`~/.cache/aman/`.
+
+Detailed install, upgrade, uninstall, and conflict guidance lives in
+[`docs/portable-install.md`](docs/portable-install.md).
+
+## Secondary Channels
 
 ### Debian/Ubuntu (`.deb`)
 
@@ -46,11 +78,6 @@ 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
 ```
@@ -66,8 +93,6 @@ or your own packaging pipeline.
   service.
 - Supported manual path: use `aman run` in the foreground while setting up,
   debugging, or collecting support logs.
-- Current release channels still differ by distro. The portable installer is the
-  milestone 2 target, not part of the current release.
 
 ## Recovery Sequence
 
@@ -121,17 +146,18 @@ sudo zypper install -y portaudio gtk3 libayatana-appindicator3-1 python3-gobject
 
 </details>
 
-## Quickstart (Current Release)
+## Quickstart (Portable Bundle)
 
-For supported daily use on current release channels:
+For supported daily use on the portable bundle:
 
 1. Install the runtime dependencies for your distro.
-2. Install the current release artifact for your distro.
-3. Enable and start the user service:
+2. Download and extract the portable release bundle.
+3. Run `./install.sh` from the extracted bundle.
+4. Save the first-run settings window.
+5. Validate the install:
 
 ```bash
-systemctl --user daemon-reload
-systemctl --user enable --now aman
+aman self-check --config ~/.config/aman/config.json
 ```
 
 If you need the manual foreground path for setup or support:
@@ -285,7 +311,9 @@ make install-service
 Service notes:
 
 - The supported daily-use path is the user service.
-- The user unit launches `aman` from `PATH`.
+- The portable installer writes and enables the user unit automatically.
+- The local developer unit launched by `make install-service` still resolves
+  `aman` from `PATH`.
 - Package installs should provide the `aman` command automatically.
 - Use `aman run --config ~/.config/aman/config.json` in the foreground for
   setup, support, or debugging.
@@ -323,11 +351,15 @@ Build and packaging (maintainers):
 ```bash
 make build
 make package
+make package-portable
 make package-deb
 make package-arch
 make release-check
 ```
 
+`make package-portable` builds `dist/aman-x11-linux-<version>.tar.gz` plus its
+`.sha256` file.
+
 `make package-deb` installs Python dependencies while creating the package.
 For offline packaging, set `AMAN_WHEELHOUSE_DIR` to a directory containing the
 required wheels.