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 |
+- Supported daily-use path: install Aman, then run it as a `systemd --user`
-| --- | --- | --- |
+  service.
-| Debian package (`.deb`) | End users on Ubuntu/Debian | Canonical |
+- Supported manual path: use `aman run` in the foreground while setting up,
-| Arch `PKGBUILD` + source tarball | Arch maintainers/power users | Supported |
+  debugging, or collecting support logs.
-| Python wheel/sdist | Developers/integrators | Supported |
+- 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

docs/persona-and-distribution.md

@@ -4,16 +4,21 @@
 
 This is the canonical Aman user.
 
-- Uses Linux desktop daily (X11 today), mostly Ubuntu/Debian.
+- Uses Linux desktop daily on X11, across mainstream distros.
 - Wants fast dictation and rewriting without learning Python tooling.
 - Prefers GUI setup and tray usage over CLI.
-- Expects normal install/uninstall/update behavior from system packages.
+- Expects a simple end-user install plus a normal background service lifecycle.
 
 Design implications:
 
 - End-user install path must not require `uv`.
 - Runtime defaults should work with minimal input.
-- Documentation should prioritize package install first.
+- Supported daily use should be a `systemd --user` service.
+- Foreground `aman run` should remain available for setup, support, and
+  debugging.
+- Diagnostics should be part of the user workflow, not only developer tooling.
+- Documentation should distinguish current release channels from the long-term
+  GA contract.
 
 ## Secondary Persona: Power User
 
@@ -27,24 +32,52 @@ Design implications:
 - Keep explicit expert-mode knobs in settings and config.
 - Keep docs for development separate from standard install docs.
 
-## Supported Distribution Path (Current)
+## Current Release Channels
 
-Tiered distribution model:
+The current release channels are:
 
-1. Canonical: Debian package (`.deb`) for Ubuntu/Debian users.
+1. Current end-user channel: Debian package (`.deb`) for Ubuntu/Debian users.
 2. Secondary: Arch package inputs (`PKGBUILD` + source tarball).
-3. Developer: wheel/sdist from `python -m build`.
+3. Developer: wheel and sdist from `python -m build`.
 
-## Out of Scope for Initial Packaging
+The portable X11 installer is the GA target channel, not the current shipped
+channel.
+
+## GA Target Support Contract
+
+For X11 GA, Aman supports:
+
+- X11 desktop sessions only.
+- 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.
+- Representative validation across Debian/Ubuntu, Arch, Fedora, and openSUSE.
+- The recovery sequence `aman doctor` -> `aman self-check` ->
+  `journalctl --user -u aman` -> `aman run --verbose`.
+
+"Any distro" means mainstream distros that satisfy these assumptions. It does
+not mean native-package parity or exhaustive certification for every Linux
+variant.
+
+## Out of Scope for X11 GA
 
 - Wayland production support.
 - Flatpak/snap-first distribution.
 - Cross-platform desktop installers outside Linux.
+- Native-package parity across every distro.
 
 ## Release and Support Policy
 
 - App versioning follows SemVer (`0.y.z` until API/UX stabilizes).
 - Config schema versioning is independent (`config_version` in config).
-- Packaging docs must always separate:
+- Docs must always separate:
-  - End-user install path (package-first)
+  - Current release channels
-  - Developer setup path (uv/pip/build workflows)
+  - GA target support contract
+  - Developer setup paths
+- The public support contract must always identify:
+  - Supported environment assumptions
+  - Daily-use service mode versus manual foreground mode
+  - Canonical recovery sequence
+  - Representative validation families
+- GA means the support contract, validation evidence, and release surface are
+  consistent. It does not require a native package for every distro.

docs/release-checklist.md

@@ -1,5 +1,8 @@
 # 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.
+
 1. Update `CHANGELOG.md` with final release notes.
 2. Bump `project.version` in `pyproject.toml`.
 3. Run quality and build gates:
@@ -20,3 +23,13 @@
    - `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):
+   - `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):
+   - 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.
+   - Public metadata, checksums, and support/reporting surfaces are complete.

docs/x11-ga/README.md

@@ -80,15 +80,19 @@ Any future docs, tray copy, and release notes should point users to this same se
 
 ## Milestones
 
-1. [Milestone 1: Support Contract and GA Bar](./01-support-contract-and-ga-bar.md)
+- [x] [Milestone 1: Support Contract and GA Bar](./01-support-contract-and-ga-bar.md)
-   Lock the public promise, supported environment, and final signoff bar.
+  Status: completed on 2026-03-12. Evidence: `README.md` now defines the
-2. [Milestone 2: Portable Install, Update, and Uninstall](./02-portable-install-update-uninstall.md)
+  support matrix, daily-use versus manual mode, and recovery sequence;
+  `docs/persona-and-distribution.md` now separates current release channels from
+  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.
-3. [Milestone 3: Runtime Reliability and Diagnostics](./03-runtime-reliability-and-diagnostics.md)
+- [ ] [Milestone 3: Runtime Reliability and Diagnostics](./03-runtime-reliability-and-diagnostics.md)
   Make startup, failure handling, and recovery predictable.
-4. [Milestone 4: First-Run UX and Support Docs](./04-first-run-ux-and-support-docs.md)
+- [ ] [Milestone 4: First-Run UX and Support Docs](./04-first-run-ux-and-support-docs.md)
   Turn the product from "documented by the author" into "understandable by a new user."
-5. [Milestone 5: GA Candidate Validation and Release](./05-ga-candidate-validation-and-release.md)
+- [ ] [Milestone 5: GA Candidate Validation and Release](./05-ga-candidate-validation-and-release.md)
   Close the remaining trust, legal, release, and validation work for a public 1.0 launch.
 
 ## Cross-milestone acceptance scenarios

src/aman.py

@@ -953,17 +953,29 @@ def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser()
     subparsers = parser.add_subparsers(dest="command")
 
-    run_parser = subparsers.add_parser("run", help="run the aman daemon")
+    run_parser = subparsers.add_parser(
+        "run",
+        help="run Aman in the foreground for setup, support, or debugging",
+        description="Run Aman in the foreground for setup, support, or debugging.",
+    )
     run_parser.add_argument("--config", default="", help="path to config.json")
     run_parser.add_argument("--dry-run", action="store_true", help="log hotkey only")
     run_parser.add_argument("-v", "--verbose", action="store_true", help="enable verbose logs")
 
-    doctor_parser = subparsers.add_parser("doctor", help="run startup diagnostics")
+    doctor_parser = subparsers.add_parser(
+        "doctor",
+        help="run preflight diagnostics for config and local environment",
+        description="Run preflight diagnostics for config and the local environment.",
+    )
     doctor_parser.add_argument("--config", default="", help="path to config.json")
     doctor_parser.add_argument("--json", action="store_true", help="print JSON output")
     doctor_parser.add_argument("-v", "--verbose", action="store_true", help="enable verbose logs")
 
-    self_check_parser = subparsers.add_parser("self-check", help="run runtime diagnostics")
+    self_check_parser = subparsers.add_parser(
+        "self-check",
+        help="run installed-system readiness diagnostics",
+        description="Run installed-system readiness diagnostics.",
+    )
     self_check_parser.add_argument("--config", default="", help="path to config.json")
     self_check_parser.add_argument("--json", action="store_true", help="print JSON output")
     self_check_parser.add_argument("-v", "--verbose", action="store_true", help="enable verbose logs")