# 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`