From 9ccf73cff5016721bfebbf1bd45800f41ef5202c Mon Sep 17 00:00:00 2001 From: Thales Maciel Date: Thu, 12 Mar 2026 14:14:24 -0300 Subject: [PATCH] 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 | 77 ++++++++++++++++++++++++++------ docs/persona-and-distribution.md | 55 ++++++++++++++++++----- docs/release-checklist.md | 13 ++++++ docs/x11-ga/README.md | 24 +++++----- src/aman.py | 18 ++++++-- 5 files changed, 149 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 66f8597..86e138d 100644 --- a/README.md +++ b/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 -## 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 diff --git a/docs/persona-and-distribution.md b/docs/persona-and-distribution.md index 5cec2b5..2491c3c 100644 --- a/docs/persona-and-distribution.md +++ b/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: - - End-user install path (package-first) - - Developer setup path (uv/pip/build workflows) +- Docs must always separate: + - Current release channels + - 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. diff --git a/docs/release-checklist.md b/docs/release-checklist.md index 94598a5..1763b7d 100644 --- a/docs/release-checklist.md +++ b/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. diff --git a/docs/x11-ga/README.md b/docs/x11-ga/README.md index 17572c1..663c88d 100644 --- a/docs/x11-ga/README.md +++ b/docs/x11-ga/README.md @@ -80,16 +80,20 @@ 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) - Lock the public promise, supported environment, and final signoff bar. -2. [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) - Make startup, failure handling, and recovery predictable. -4. [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) - Close the remaining trust, legal, release, and validation work for a public 1.0 launch. +- [x] [Milestone 1: Support Contract and GA Bar](./01-support-contract-and-ga-bar.md) + Status: completed on 2026-03-12. Evidence: `README.md` now defines the + 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. +- [ ] [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) + Turn the product from "documented by the author" into "understandable by a new user." +- [ ] [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 diff --git a/src/aman.py b/src/aman.py index 7f9d22a..7bc959d 100755 --- a/src/aman.py +++ b/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")