Make the X11 user path visible on first contact instead of burying it under config and maintainer detail.
Rewrite the README around the supported quickstart, expected tray and dictation result, install validation, troubleshooting, and linked follow-on docs. Split deep config and developer material into separate docs, add checked-in screenshots plus a short WebM walkthrough, and add a generator so the media assets stay reproducible.
Also fix the CLI discovery gap by letting `aman --help` show the top-level command surface while keeping implicit foreground `run` behavior, and align the settings, help, and about copy with the supported service-plus-diagnostics model.
Validation: `PYTHONPATH=src python3 -m unittest tests.test_aman_cli tests.test_config_ui`; `PYTHONPATH=src python3 -m unittest discover -s tests -p 'test_*.py'`; `python3 -m py_compile src/*.py tests/*.py scripts/generate_docs_media.py`; `PYTHONPATH=src python3 -m aman --help`.
Milestone 4 stays open in the roadmap because `docs/x11-ga/first-run-review-notes.md` still needs a real non-implementer walkthrough.
Make the milestone 3 runtime story predictable instead of treating doctor, self-check, and startup failures as loosely related surfaces.
Split doctor and self-check into distinct read-only flows, add tri-state diagnostic status with stable IDs and next steps, and reuse that wording in CLI output, service logs, and tray-triggered diagnostics. Add non-mutating config/model probes, a make runtime-check gate, and public recovery/validation docs for the X11 GA roadmap.
Validation: make runtime-check; PYTHONPATH=src python3 -m unittest discover -s tests -p 'test_*.py'; python3 -m py_compile src/*.py tests/*.py; PYTHONPATH=src python3 -m aman doctor --help; PYTHONPATH=src python3 -m aman self-check --help. Leave milestone 3 open in the roadmap until the manual X11 validation rows are filled.
Implement milestone 2 around a portable X11 release bundle instead of\nkeeping distro packages as the only end-user path.\n\nAdd make/package scripts plus a portable installer helper that builds the\ntarball, creates a user-scoped venv install, manages the user service, handles\nupgrade rollback, and supports uninstall with optional purge.\n\nFlip the end-user docs to the portable bundle, add a dedicated install guide\nand validation matrix, and leave the roadmap milestone open only for the\nremaining manual distro validation evidence.\n\nValidation: python3 -m py_compile src/*.py packaging/portable/portable_installer.py tests/test_portable_bundle.py; PYTHONPATH=src python3 -m unittest tests.test_portable_bundle; PYTHONPATH=src python3 -m unittest tests.test_aman_cli tests.test_diagnostics tests.test_portable_bundle; PYTHONPATH=src python3 -m unittest discover -s tests -p 'test_*.py'
Keep the first user-readiness assessment in the repo so the GA work has a\nconcrete evaluator baseline to refer back to.\n\nAdd the existing timestamped report and document the directory convention in\nuser-readiness/README.md so future reviews can be added without guessing how\nfiles are named or what they represent.
Avoid treating setuptools metadata as working tree noise when packaging and\nrunning release checks.\n\nIgnore *.egg-info/ globally so generated metadata stays out of follow-on\ncommits while leaving the actual milestone work staged separately.
Clarify the current release channels versus the X11 GA target so the project has an explicit support promise before milestone 2 delivery work begins.
Update the README, persona and distribution docs, and release checklist with a support matrix, the systemd --user daily-use path, the manual aman run support path, and the canonical recovery sequence. Mark milestone 1 complete in the roadmap once that contract is documented.
Align run, doctor, and self-check help text with the same service and diagnostics language without changing command behavior.
Validated with PYTHONPATH=src python3 -m aman --help, PYTHONPATH=src python3 -m aman doctor --help, and PYTHONPATH=src python3 -m aman self-check --help. Excludes generated src/aman.egg-info and prior user-readiness notes.
Capture the current GA gaps and define a portable X11 support contract so the release bar is explicit for mainstream distros.
Document five ordered milestones covering support policy, portable install/update/uninstall, runtime reliability and diagnostics, first-run UX/docs, and GA validation/release evidence.
Left generated artifacts (src/aman.egg-info) and prior readiness notes uncommitted.
Keep the daemon path on the full ASR result so word timings and detected language survive into the editor pipeline instead of falling back to a plain transcript string.
Add PipelineEngine.run_asr_result(), have aman call it when live ASR data is available, and cover the word-aware alignment behavior in the daemon tests.
Collapse the llama cleanup flow to a single JSON-shaped completion while leaving the legacy pass1/pass2 parameters in place as compatibility no-ops.
Validated with PYTHONPATH=src python3 -m unittest tests.test_aiprocess tests.test_aman.
