Define the X11 support contract for milestone 1

Clarify the current release channels versus the X11 GA target so the project has an explicit support promise before milestone 2 delivery work begins.

Update the README, persona and distribution docs, and release checklist with a support matrix, the systemd --user daily-use path, the manual aman run support path, and the canonical recovery sequence. Mark milestone 1 complete in the roadmap once that contract is documented.

Align run, doctor, and self-check help text with the same service and diagnostics language without changing command behavior.

Validated with PYTHONPATH=src python3 -m aman --help, PYTHONPATH=src python3 -m aman doctor --help, and PYTHONPATH=src python3 -m aman self-check --help. Excludes generated src/aman.egg-info and prior user-readiness notes.

README.md

@@ -8,15 +8,37 @@ 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: native OS package install.
+- End-user path today: distro-specific release artifacts.
+- GA target: portable X11 release bundle for mainstream distros.
 - 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)
+## Current Release Channels
 
-End users do not need `uv`.
+Aman is not GA yet for X11 users across distros. Today the maintained release
+channels are:
+
+- Debian/Ubuntu `.deb`: current end-user channel.
+- Arch `PKGBUILD` plus source tarball: current 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
+
+| Surface | Contract |
+| --- | --- |
+| Desktop session | X11 only |
+| Runtime dependencies | Installed from the distro package manager |
+| Supported daily-use mode | `systemd --user` service |
+| 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 |
+
+## Current Install Instructions
 
 ### Debian/Ubuntu (`.deb`)
 
@@ -38,13 +60,23 @@ systemctl --user enable --now aman
 Use the generated packaging inputs (`PKGBUILD` + source tarball) in `dist/arch/`
 or your own packaging pipeline.
 
-## Distribution Matrix
+## Daily-Use And Support Modes
 
-| 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 |
+- Supported daily-use path: install Aman, then run it as a `systemd --user`
+  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
+
+When Aman does not behave as expected, use this order:
+
+1. Run `aman doctor --config ~/.config/aman/config.json`.
+2. Run `aman self-check --config ~/.config/aman/config.json`.
+3. Inspect `journalctl --user -u aman -f`.
+4. Re-run Aman in the foreground with `aman run --config ~/.config/aman/config.json --verbose`.
 
 ## Runtime Dependencies
 
@@ -89,10 +121,23 @@ sudo zypper install -y portaudio gtk3 libayatana-appindicator3-1 python3-gobject
 
 </details>
 
-## Quickstart
+## Quickstart (Current Release)
+
+For supported daily use on current release channels:
+
+1. Install the runtime dependencies for your distro.
+2. Install the current release artifact for your distro.
+3. Enable and start the user service:
 
 ```bash
-aman run
+systemctl --user daemon-reload
+systemctl --user enable --now aman
+```
+
+If you need the manual foreground path for setup or support:
+
+```bash
+aman run --config ~/.config/aman/config.json
 ```
 
 On first launch, Aman opens a graphical settings window automatically.
@@ -239,9 +284,13 @@ make install-service
 
 Service notes:
 
+- The supported daily-use path is the user service.
 - 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`.
+- Use `aman run --config ~/.config/aman/config.json` in the foreground for
+  setup, support, or debugging.
+- Start recovery with `aman doctor`, then `aman self-check`, before inspecting
+  `systemctl --user status aman` and `journalctl --user -u aman -f`.
 
 ## Usage
 
@@ -337,12 +386,12 @@ make install-local
 aman run --config ~/.config/aman/config.json
 ```
 
-CLI (internal/support fallback):
+CLI (support and developer workflows):
 
 ```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 run --config ~/.config/aman/config.json
 aman bench --text "example transcript" --repeat 5 --warmup 1
 aman build-heuristic-dataset --input benchmarks/heuristics_dataset.raw.jsonl --output benchmarks/heuristics_dataset.jsonl --json
 aman eval-models --dataset benchmarks/cleanup_dataset.jsonl --matrix benchmarks/model_matrix.small_first.json --heuristic-dataset benchmarks/heuristics_dataset.jsonl --heuristic-weight 0.25 --json