Thales Maciel 359b5fbaf4 Land milestone 4 first-run docs and media

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.

2026-03-12 18:30:34 -03:00

4.5 KiB

Raw Blame History

Runtime Recovery Guide

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.
aman self-check --config ~/.config/aman/config.json is the deeper, still read-only readiness check. It includes every doctor check plus the managed model cache, cache writability, installed user service, current service state, and startup readiness.
Tray Run Diagnostics uses the same deeper self-check path and logs any non-ok results.

Reading the output

ok: the checked surface is ready.
warn: the checked surface is degraded or incomplete, but the command still exits 0.
fail: the supported path is blocked, and the command exits 2.

Example output:

[OK] config.load: loaded config from /home/user/.config/aman/config.json
[WARN] model.cache: managed editor model is not cached at /home/user/.cache/aman/models/Qwen2.5-1.5B-Instruct-Q4_K_M.gguf | next_step: start Aman once on a networked connection so it can download the managed editor model, then rerun `aman self-check --config /home/user/.config/aman/config.json`
[FAIL] service.state: user service is installed but failed to start | next_step: inspect `journalctl --user -u aman -f` to see why aman.service is failing
overall: fail

Failure map

Symptom	First command	Diagnostic ID	Meaning	Next step
Config missing or invalid	`aman doctor`	`config.load`	Config is absent or cannot be parsed	Save settings, fix the JSON, or rerun `aman init --force`, then rerun `doctor`
No X11 session	`aman doctor`	`session.x11`	`DISPLAY` is missing or Wayland was detected	Start Aman from the same X11 user session you expect to use daily
Audio runtime or microphone missing	`aman doctor`	`runtime.audio` or `audio.input`	PortAudio or the selected input device is unavailable	Install runtime dependencies, connect a microphone, or choose a valid `recording.input`
Hotkey cannot be registered	`aman doctor`	`hotkey.parse`	The configured hotkey is invalid or already taken	Choose a different hotkey in Settings
Output injection fails	`aman doctor`	`injection.backend`	The chosen X11 output path is not usable	Switch to a supported backend or rerun in the foreground with `--verbose`
Managed editor model missing or corrupt	`aman self-check`	`model.cache`	The managed model is absent or has a bad checksum	Start Aman once on a networked connection, or clear the broken cache and retry
Model cache directory is not writable	`aman self-check`	`cache.writable`	Aman cannot create or update its managed model cache	Fix permissions on `~/.cache/aman/models/`
User service missing or disabled	`aman self-check`	`service.unit` or `service.state`	The service was not installed cleanly or is not active	Reinstall Aman or run `systemctl --user enable --now aman`
Startup still fails after install	`aman self-check`	`startup.readiness`	Aman can load config but cannot assemble its runtime without failing	Fix the named runtime dependency, custom model path, or editor dependency, then rerun `self-check`

Escalation order

Run aman doctor --config ~/.config/aman/config.json.
Run aman self-check --config ~/.config/aman/config.json.
Inspect journalctl --user -u aman -f.
Re-run Aman in the foreground with aman run --config ~/.config/aman/config.json --verbose.

If you are collecting evidence for a release or support handoff, copy the first non-ok diagnostic line and the first matching journalctl failure block.

4.5 KiB Raw Blame History