thaloco/aman
1
Fork 0
Code Pull requests Releases Packages Activity Actions
aman/user-readiness/1773354709.md
Thales Maciel 31a1e069b3
Prepare the 1.0.0 GA release surface 
Add the repo-side pieces for milestone 5: MIT licensing, real maintainer and forge metadata, a public support doc, 1.0.0 release notes, release-prep tooling, and CI uploads for the full candidate artifact set.

Keep source-tree version surfaces honest by reading the local project version in the CLI and About dialog, and cover the new release-prep plus version-fallback behavior with focused tests.

Document where raw validation evidence belongs, add the GA validation rollup, and archive the latest readiness review. Milestone 5 remains open until the forge release page is published and the milestone 2 and 3 matrices are filled with linked manual evidence.

Validation: PYTHONPATH=src python3 -m unittest discover -s tests -p 'test_*.py'; PYTHONPATH=src python3 -m unittest tests.test_release_prep tests.test_portable_bundle tests.test_aman_cli tests.test_config_ui; python3 -m py_compile src/*.py tests/*.py; PYTHONPATH=src python3 -m aman version
2026-03-12 19:36:52 -03:00

4.7 KiB
Raw Blame History

User Readiness Review

  • Date: 2026-03-12
  • Reviewer: Codex
  • Scope: documentation, packaged artifacts, and CLI help surface
  • Live run status: documentation-and-artifact based plus python3 -m aman --help; I did not launch the GTK daemon in a live X11 session

Verdict

A new X11 user can now tell what Aman is for, how to install it, what success looks like, and what recovery path to follow when the first run goes wrong. That is a real improvement over an internal-looking project surface.

It still does not feel fully distribution-ready. The first-contact and onboarding story are strong, but the public release and validation story still looks in-progress rather than complete.

What A New User Would Experience

A new user lands on a README that immediately states the product, the supported environment, the install path, the expected first dictation result, and the recovery flow. The quickstart is concrete, with distro-specific dependency commands, screenshots, demo media, and a plain-language description of what the tray and injected text should do. The install and support docs stay aligned with that same path, which keeps the project from feeling like it requires author hand-holding.

Confidence drops once the user looks for proof that the release is actually published and validated. The repo-visible evidence still shows pending GA publication work and pending manual distro validation, so the project reads as "nearly ready" instead of "safe to recommend."

Top Blockers

  1. The public release trust surface is still incomplete. The supported install path depends on a published release page, but docs/x11-ga/ga-validation-report.md still marks Published release page as Pending.
  2. The artifact story still reads as pre-release. docs/releases/1.0.0.md says the release page "should publish" the artifacts, and local dist/ contents are still 0.1.0 wheel and tarball outputs rather than a visible 1.0.0 portable bundle plus checksum set.
  3. Supported-distro validation is still promise, not proof. docs/x11-ga/portable-validation-matrix.md and docs/x11-ga/runtime-validation-report.md show good automated coverage, but every manual Debian/Ubuntu, Arch, Fedora, and openSUSE row is still Pending.
  4. The top-level CLI help still mixes end-user and maintainer workflows. Commands like bench, eval-models, build-heuristic-dataset, and sync-default-model make the help surface feel more internal than a focused desktop product when a user checks --help.

What Is Already Working

  • A new user can tell what Aman is and who it is for from README.md.
  • A new user can follow one obvious install path without being pushed into developer tooling.
  • A new user can see screenshots, demo media, expected tray states, and a sample dictated phrase before installing.
  • A new user gets a coherent support and recovery story through doctor, self-check, journalctl, and aman run --verbose.
  • The repo now has visible trust signals such as a real LICENSE, maintainer/contact metadata, and a public support document.

Quick Wins

  • Publish the 1.0.0 release page with the portable bundle, checksum files, and final release notes, then replace every Pending or "should publish" wording with completed wording.
  • Make the local artifact story match the docs by generating or checking in the expected 1.0.0 release outputs referenced by the release documentation.
  • Fill at least one full manual validation pass per supported distro family and link each timestamped evidence file into the two GA matrices.
  • Narrow the top-level CLI help to the supported user commands, or clearly label maintainer-only commands so the main recovery path stays prominent.

What Would Make It Distribution-Ready

Before broader distribution, it needs a real published 1.0.0 release page, artifact and checksum evidence that matches the docs, linked manual validation results across the supported distro families, and a slightly cleaner user-facing CLI surface. Once those land, the project will look like a maintained product rather than a well-documented release candidate.

Evidence

Commands Run

  • bash /home/thales/projects/personal/skills-exploration/.agents/skills/user-readiness-review/scripts/collect_readiness_context.sh
  • PYTHONPATH=src python3 -m aman --help
  • find docs/media -maxdepth 1 -type f | sort
  • ls -la dist

Files Reviewed

  • README.md
  • docs/portable-install.md
  • SUPPORT.md
  • pyproject.toml
  • CHANGELOG.md
  • docs/releases/1.0.0.md
  • docs/persona-and-distribution.md
  • docs/x11-ga/ga-validation-report.md
  • docs/x11-ga/portable-validation-matrix.md
  • docs/x11-ga/runtime-validation-report.md