Record the independent reviewer pass that closes the first-run UX/docs milestone and archive the raw readiness report under user-readiness.

Clarify the README quickstart by naming the default Cmd+m/Super+m hotkey, and align the roadmap plus release checklist with the independent-review closeout wording while keeping milestones 2 and 3 open pending manual validation.

Validation: PYTHONPATH=src python3 -m aman --help; PYTHONPATH=src python3 -m unittest tests.test_aman_cli tests.test_config_ui; user-confirmed milestone 4 validation.

2026-03-12 18:57:57 -03:00

2.3 KiB

Raw Permalink Blame History

Verdict

For milestone 4's defined bar, the first-run surface now reads as complete. A new X11 user can tell what Aman is, how to install it, what success looks like, how to validate the install, and where to go when the first run fails. This review is documentation-and-artifact based plus CLI help inspection; I did not launch the GTK daemon in a live X11 session.

What A New User Would Experience

A new user now lands on a README that leads with the supported X11 path instead of maintainer internals. The first-run flow is clear: install runtime dependencies, verify the portable bundle, run install.sh, save the required settings window, dictate a known phrase, and compare the result against an explicit tray-state and injected-text expectation. The linked install, recovery, config, and developer docs are separated cleanly enough that the first user path stays intact. python3 -m aman --help also now exposes the main command surface directly, which makes the support story match the docs.

Top Blockers

No blocking first-run issues remained after the quickstart hotkey clarification. For the milestone 4 scope, the public docs and visual proof are now coherent enough to understand the product without guessing.

Residual non-blocking gaps:

The repo still does not point users at a real release download location.
Legal/project metadata is still incomplete for a public GA trust surface.

Those are real project gaps, but they belong to milestone 5 rather than the first-run UX/docs milestone.

Quick Wins

Keep the README quickstart and docs/media/ assets in sync whenever tray labels, settings copy, or the default hotkey change.
Preserve the split between end-user docs and maintainer docs; that is the biggest quality improvement in this milestone.
When milestone 5 tackles public release trust, add the real release download surface without reintroducing maintainer detail near the top of the README.

What Would Make It Distribution-Ready

Milestone 4 does not make Aman GA by itself. Before broader X11 distribution, the project still needs:

a real release download/publication surface
license, maintainer, and project metadata completion
representative distro validation evidence
the remaining runtime and portable-install manual validation rows required by milestones 2 and 3

2.3 KiB Raw Permalink Blame History