aman/user-readiness/1773333303.md

• Verdict

This does not read as GA yet. For the narrow target you explicitly define, X11 desktop users on Ubuntu/Debian, it feels closer to a solid beta than a general release: the packaging and release mechanics are real, but the first-user surface still assumes too much context and lacks enough trust/polish for wider distribution. For broader Linux desktop GA, it is farther away because Wayland is still explicitly out of scope in README.md:257 and docs/persona-and-distribution.md:38.

This review is documentation-and-artifact based plus CLI help inspection. I did not launch the GUI daemon in a real X11 desktop session.

What A New User Would Experience

A new user can tell what Aman is and who it is for: a local X11 dictation daemon for desktop professionals, with package-first install as the intended end-user path README.md:4 README.md:17 docs/persona-and-distribution.md:3. But the path gets muddy quickly: the README tells them to install a .deb and enable a user service README.md:21, then later presents aman run as the quickstart README.md:92, then drops into a large block of config and model internals README.md:109. A first user never gets a visual preview, a “this is what success looks like” check, or a short guided first transcription.

Top Blockers

• The canonical install path is incomplete from a user perspective. The README says “download a release artifact” but does not point to an actual release location, explain which artifact to pick, or cover update/uninstall flow README.md:21. That is acceptable for maintainers, not for GA users.
• The launch story is ambiguous. The recommended path enables a systemd user service README.md:29, but the “Quickstart” immediately tells users to run aman run manually README.md:92. A new user should not have to infer when to use the service versus foreground mode.
• There is no visible proof of the product experience. The README describes a settings window and tray menu README.md:98 README.md:246, but I found no screenshots, demo GIFs, or sample before/after transcripts in the repo. For a desktop utility, that makes it feel internal.
• The docs over-explain internals before they prove the happy path. Large sections on config schema, model behavior, fact guard, and evaluation are useful later, but they crowd out first-run guidance README.md:109 README.md:297. A GA README should front-load “install, launch, test, expected result, troubleshooting.”
• The release surface still looks pre-GA. The project is 0.1.0 pyproject.toml:5, and your own distribution doc says you will stay on 0.y.z until API/UX stabilizes docs/persona-and-distribution.md:44. On top of that, pyproject.toml lacks license/URL/author metadata pyproject.toml:5, there is no repo LICENSE file, and the Debian package template still uses a placeholder maintainer address control.in:6.
• Wayland being unsupported materially limits any GA claim beyond a narrow X11 niche README.md:257. My inference: in 2026, that is fine for a constrained preview audience, but weak for “Linux desktop GA.”

What Already Works

• The target persona and supported distribution strategy are explicit, which is better than most early projects docs/persona-and-distribution.md:3.
• The repo has real release hygiene: changelog, release checklist, package scripts, and a Debian control file with runtime deps CHANGELOG.md:1 docs/release- checklist.md:1 control.in:1.
• There is a support/diagnostics surface, not just run: doctor, self-check, version, init, benchmarking, and model tooling are documented README.md:340. The CLI help for doctor and self-check is also usable.
• The README does communicate important operational constraints clearly: X11-only, strict config validation, runtime dependencies, and service behavior README.md:49 README.md:153 README.md:234.

Quick Wins

• Split the README into two flows at the top: End-user install and Developer/maintainer docs. Right now the end-user story is diluted by packaging and benchmarking material.
• Replace the current quickstart with a 60-second happy path: install, launch, open settings, choose mic, press hotkey, speak sample phrase, expected tray/ notification/result.
• Add two screenshots and one short GIF: settings window, tray menu, and a single dictation round-trip.
• Add a “validate your install” step using aman self-check or the tray diagnostics, with an example success result.
• Add trust metadata now: LICENSE, real maintainer/contact, project URL, issue tracker, and complete package metadata in pyproject.toml:5.
• Make aman --help show the command set directly. Right now discoverability is weaker than the README suggests.

Minimum Bar For GA

• A real release surface exists: downloadable artifacts, checksums, release notes, upgrade/uninstall guidance, and a support/contact path.
• The README proves the product visually and operationally, not just textually.
• The end-user path is singular and unambiguous for the supported audience.
• Legal and package metadata are complete.
• You define GA honestly as either Ubuntu/Debian X11 only or you expand platform scope. Without that, the market promise and the actual support boundary are misaligned.

If you want a blunt summary: this looks one focused release cycle away from a credible limited GA for Ubuntu/Debian X11 users, and more than that away from broad Linux desktop GA.