thaloco/aman
1
Fork 0
Code Pull requests Releases Packages Activity Actions

Define the X11 support contract for milestone 1

Browse source 
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.
This commit is contained in:
Thales Maciel 2026-03-12 14:14:24 -03:00
parent 01a580f359
commit 9ccf73cff5
5 changed files with 149 additions and 38 deletions
Download patch file Download diff file Expand all files Collapse all files

77
README.md
View file

@ -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

55
docs/persona-and-distribution.md
View file

@ -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.

13
docs/release-checklist.md
View file

@ -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.

24
docs/x11-ga/README.md
View file

@ -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

18
src/aman.py
View file

@ -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")