Thales Maciel
359b5fbaf4
Make the X11 user path visible on first contact instead of burying it under config and maintainer detail. Rewrite the README around the supported quickstart, expected tray and dictation result, install validation, troubleshooting, and linked follow-on docs. Split deep config and developer material into separate docs, add checked-in screenshots plus a short WebM walkthrough, and add a generator so the media assets stay reproducible. Also fix the CLI discovery gap by letting `aman --help` show the top-level command surface while keeping implicit foreground `run` behavior, and align the settings, help, and about copy with the supported service-plus-diagnostics model. Validation: `PYTHONPATH=src python3 -m unittest tests.test_aman_cli tests.test_config_ui`; `PYTHONPATH=src python3 -m unittest discover -s tests -p 'test_*.py'`; `python3 -m py_compile src/*.py tests/*.py scripts/generate_docs_media.py`; `PYTHONPATH=src python3 -m aman --help`. Milestone 4 stays open in the roadmap because `docs/x11-ga/first-run-review-notes.md` still needs a real non-implementer walkthrough.
141 lines
7.8 KiB
Markdown
141 lines
7.8 KiB
Markdown
# Aman X11 GA Roadmap
|
|
|
|
## What is missing today
|
|
|
|
Aman is not starting from zero. It already has a working X11 daemon, a settings-first flow, diagnostics commands, Debian packaging, Arch packaging inputs, and a release checklist. What it does not have yet is a credible GA story for X11 users across mainstream distros.
|
|
|
|
The current gaps are:
|
|
|
|
- The canonical portable install, update, and uninstall path now exists, but the representative distro rows still need real manual validation evidence before it can count as a GA-ready channel.
|
|
- The X11 support contract and service-versus-foreground split are now documented, but the public release surface still needs the remaining trust and support work from milestones 4 and 5.
|
|
- Validation matrices now exist for portable lifecycle and runtime reliability, but they are not yet filled with release-specific manual evidence across Debian/Ubuntu, Arch, Fedora, and openSUSE.
|
|
- Incomplete trust surface. The project still needs a real license file, real maintainer/contact metadata, real project URLs, published release artifacts, and public checksums.
|
|
- The first-run docs and media have landed, but milestone 4 still needs a non-implementer walkthrough before the project can claim that the public docs are actually enough.
|
|
- Diagnostics are now the canonical recovery path, but milestone 3 still needs release-specific X11 evidence for restart, offline-start, tray diagnostics, and recovery scenarios.
|
|
- The release checklist now includes GA signoff gates, but the project is still short of the broader legal, release-publication, and validation evidence needed for a credible public 1.0 release.
|
|
|
|
## GA target
|
|
|
|
For this roadmap, GA means:
|
|
|
|
- X11 only. Wayland is explicitly out of scope.
|
|
- One canonical portable install path for end users.
|
|
- Distro-specific runtime dependency guidance for major distro families.
|
|
- Representative validation on Debian/Ubuntu, Arch, Fedora, and openSUSE.
|
|
- A stable support contract, clear recovery path, and public release surface that a first-time user can trust.
|
|
|
|
"Any distro" does not mean literal certification of every Linux distribution. It means Aman ships one portable X11 installation path that works on mainstream distros with the documented runtime dependencies and system assumptions.
|
|
|
|
## Support contract for GA
|
|
|
|
The GA support promise for Aman should be:
|
|
|
|
- Linux desktop sessions running X11.
|
|
- Mainstream distros with `systemd --user` available.
|
|
- System CPython `3.10`, `3.11`, or `3.12` available for the portable installer.
|
|
- Runtime dependencies installed from the distro package manager.
|
|
- Service mode is the default end-user mode.
|
|
- Foreground `aman run` remains a support and debugging path, not the primary daily-use path.
|
|
|
|
Native distro packages remain valuable, but they are secondary distribution channels. They are not the GA definition for X11 users on any distro.
|
|
|
|
## Roadmap principles
|
|
|
|
- Reliability beats feature expansion.
|
|
- Simplicity beats distro-specific cleverness.
|
|
- One canonical end-user path.
|
|
- One canonical recovery path.
|
|
- Public docs should explain the supported path before they explain internals.
|
|
- Each milestone must reduce ambiguity, not just add artifacts.
|
|
|
|
## Canonical delivery model
|
|
|
|
The roadmap assumes one portable release bundle for GA:
|
|
|
|
- Release artifact: `aman-x11-linux-<version>.tar.gz`
|
|
- Companion checksum file: `aman-x11-linux-<version>.tar.gz.sha256`
|
|
- Installer entrypoint: `install.sh`
|
|
- Uninstall entrypoint: `uninstall.sh`
|
|
|
|
The bundle installs Aman into user scope:
|
|
|
|
- Versioned payload: `~/.local/share/aman/<version>/`
|
|
- Current symlink: `~/.local/share/aman/current`
|
|
- Command shim: `~/.local/bin/aman`
|
|
- User service: `~/.config/systemd/user/aman.service`
|
|
|
|
The installer should use `python3 -m venv --system-site-packages` so Aman can rely on distro-provided GTK, X11, and audio bindings while still shipping its own Python package payload. This keeps the runtime simpler than a full custom bundle and avoids asking end users to learn `uv`.
|
|
|
|
## Canonical recovery model
|
|
|
|
The roadmap also fixes the supported recovery path:
|
|
|
|
- `aman doctor` is the first environment and config preflight.
|
|
- `aman self-check` is the deeper readiness check for an installed system.
|
|
- `journalctl --user -u aman` is the primary service log surface.
|
|
- Foreground `aman run --verbose` is the support fallback when service mode is not enough.
|
|
|
|
Any future docs, tray copy, and release notes should point users to this same sequence.
|
|
|
|
## Milestones
|
|
|
|
- [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)
|
|
Implementation landed on 2026-03-12: the portable bundle, installer,
|
|
uninstaller, docs, and automated lifecycle tests are in the repo. Leave this
|
|
milestone open until the representative distro rows in
|
|
[`portable-validation-matrix.md`](./portable-validation-matrix.md) are filled
|
|
with real manual validation evidence.
|
|
- [ ] [Milestone 3: Runtime Reliability and Diagnostics](./03-runtime-reliability-and-diagnostics.md)
|
|
Implementation landed on 2026-03-12: `doctor` and `self-check` now have
|
|
distinct read-only roles, runtime failures log stable IDs plus next steps,
|
|
`make runtime-check` is part of the release surface, and the runtime recovery
|
|
guide plus validation report now exist. Leave this milestone open until the
|
|
release-specific manual rows in
|
|
[`runtime-validation-report.md`](./runtime-validation-report.md) are filled
|
|
with real X11 validation evidence.
|
|
- [ ] [Milestone 4: First-Run UX and Support Docs](./04-first-run-ux-and-support-docs.md)
|
|
Implementation landed on 2026-03-12: the README is now end-user-first,
|
|
first-run assets live under `docs/media/`, deep config and maintainer content
|
|
moved into linked docs, and `aman --help` exposes the top-level commands
|
|
directly. Leave this milestone open until
|
|
[`first-run-review-notes.md`](./first-run-review-notes.md) contains a real
|
|
non-implementer walkthrough.
|
|
- [ ] [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
|
|
|
|
Every milestone should advance the same core scenarios:
|
|
|
|
- Fresh install on a representative distro family.
|
|
- First-run settings flow and first successful dictation.
|
|
- Reboot or service restart followed by successful reuse.
|
|
- Upgrade with config preservation.
|
|
- Uninstall and cleanup.
|
|
- Offline start with already-cached models.
|
|
- Broken config or missing dependency followed by successful diagnosis and recovery.
|
|
- Manual validation by someone who did not implement the feature.
|
|
|
|
## Final GA release bar
|
|
|
|
Before declaring Aman GA for X11 users, all of the following should be true:
|
|
|
|
- The support contract is public and unambiguous.
|
|
- The portable installer and uninstaller are the primary documented user path.
|
|
- The runtime and diagnostics path are reliable enough that failures are usually self-explanatory.
|
|
- End-user docs include a 60-second quickstart, expected visible results, screenshots, and troubleshooting.
|
|
- Release artifacts, checksums, license, project metadata, and support/contact surfaces are complete.
|
|
- Validation evidence exists for Debian/Ubuntu, Arch, Fedora, and openSUSE.
|
|
- The release is tagged and published as `1.0.0`.
|
|
|
|
## Non-goals
|
|
|
|
- Wayland support.
|
|
- New transcription or editing features that do not directly improve reliability, install simplicity, or diagnosability.
|
|
- Full native-package parity across all distros as a GA gate.
|