thaloco/aman
1
Fork 0
Code Pull requests Releases Packages Activity Actions

Land milestone 4 first-run docs and media

Browse source 
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.
This commit is contained in:
Thales Maciel 2026-03-12 18:30:34 -03:00
parent ed1b59240b
commit 359b5fbaf4
16 changed files with 788 additions and 411 deletions
Download patch file Download diff file Expand all files Collapse all files

17
docs/runtime-recovery.md
View file

@ -2,6 +2,23 @@
Use this guide when Aman is installed but not behaving correctly.
## First-run troubleshooting
- Settings window did not appear:
run `aman run --config ~/.config/aman/config.json` once in the foreground so
you can complete first-run setup.
- No tray icon after saving settings:
run `aman self-check --config ~/.config/aman/config.json` and confirm the
user service is enabled and active.
- Hotkey does not start recording:
run `aman doctor --config ~/.config/aman/config.json`, then choose a
different hotkey in Settings if `hotkey.parse` is not `ok`.
- Microphone test failed:
re-open Settings, choose another input device, then rerun `aman doctor`.
- Text was transcribed but not injected:
run `aman doctor`, then rerun `aman run --config ~/.config/aman/config.json --verbose`
to inspect the output backend in the foreground.
## Command roles
- `aman doctor --config ~/.config/aman/config.json` is the fast, read-only preflight for config, X11 session, audio runtime, input device resolution, hotkey availability, injection backend selection, and service prerequisites.