# Portable X11 Install Guide

This is the canonical end-user install path for Aman on X11.

For the shortest first-run path, screenshots, and the expected tray/dictation
result, start with the quickstart in [`README.md`](../README.md).

Download published bundles, checksums, and release notes from
`https://git.thaloco.com/thaloco/aman/releases`.

## Supported environment

- X11 desktop session
- `systemd --user`
- System CPython `3.10`, `3.11`, or `3.12`
- Runtime dependencies installed from the distro package manager

Current automated validation covers Ubuntu CI on CPython `3.10`, `3.11`, and
`3.12` for unit/package coverage, plus a portable install and `aman doctor`
smoke path with Ubuntu system `python3`. The other distro-family instructions
below remain manual validation targets.

## 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 gir1.2-ayatanaappindicator3-0.1 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` from the releases page.
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`

The failure IDs and example outputs for this flow are documented in
[`docs/runtime-recovery.md`](./runtime-recovery.md).

Public support and issue reporting instructions live in
[`SUPPORT.md`](../SUPPORT.md).