Thales Maciel
31a1e069b3
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
105 lines
4.7 KiB
Markdown
105 lines
4.7 KiB
Markdown
# 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`
|