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

14
src/aman.py
View file

@ -997,7 +997,17 @@ def _sync_default_model_command(args: argparse.Namespace) -> int:
def _build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser()
parser = argparse.ArgumentParser(
description=(
"Aman is an X11 dictation daemon for Linux desktops. "
"Use `run` for foreground setup/support, `doctor` for fast preflight checks, "
"and `self-check` for deeper installed-system readiness."
),
epilog=(
"Supported daily use is the systemd --user service. "
"For recovery: doctor -> self-check -> journalctl -> aman run --verbose."
),
)
subparsers = parser.add_subparsers(dest="command")
run_parser = subparsers.add_parser(
@ -1129,6 +1139,8 @@ def _parse_cli_args(argv: list[str]) -> argparse.Namespace:
"version",
"init",
}
if normalized_argv and normalized_argv[0] in {"-h", "--help"}:
return parser.parse_args(normalized_argv)
if not normalized_argv or normalized_argv[0] not in known_commands:
normalized_argv = ["run", *normalized_argv]
return parser.parse_args(normalized_argv)

29
src/config_ui.py
View file

@ -86,7 +86,7 @@ class ConfigWindow:
banner.set_show_close_button(False)
banner.set_message_type(Gtk.MessageType.WARNING)
banner_label = Gtk.Label(
label="Aman needs saved settings before it can start recording."
label="Aman needs saved settings before it can start recording from the tray."
)
banner_label.set_xalign(0.0)
banner_label.set_line_wrap(True)
@ -219,9 +219,6 @@ class ConfigWindow:
grid.attach(profile_label, 0, 5, 1, 1)
grid.attach(self._profile_combo, 1, 5, 1, 1)
self._show_notifications_check = Gtk.CheckButton(label="Enable tray notifications")
self._show_notifications_check.set_hexpand(True)
grid.attach(self._show_notifications_check, 1, 6, 1, 1)
return grid
def _build_audio_page(self) -> Gtk.Widget:
@ -382,13 +379,17 @@ class ConfigWindow:
"- Press your hotkey to start recording.\n"
"- Press the hotkey again to stop and process.\n"
"- Press Esc while recording to cancel.\n\n"
"Model/runtime tips:\n"
"Supported path:\n"
"- Daily use runs through the tray and user service.\n"
"- Aman-managed mode (recommended) handles model lifecycle for you.\n"
"- Expert mode lets you set custom Whisper model paths.\n\n"
"- Expert mode keeps custom Whisper paths available for advanced users.\n\n"
"Recovery:\n"
"- Use Run Diagnostics from the tray for a deeper self-check.\n"
"- If that is not enough, run aman doctor, then aman self-check.\n"
"- Next escalations are journalctl --user -u aman and aman run --verbose.\n\n"
"Safety tips:\n"
"- Keep fact guard enabled to prevent accidental name/number changes.\n"
"- Strict safety blocks output on fact violations.\n\n"
"Use the tray menu for pause/resume, config reload, and diagnostics."
"- Strict safety blocks output on fact violations."
)
)
help_text.set_xalign(0.0)
@ -412,7 +413,7 @@ class ConfigWindow:
title.set_xalign(0.0)
box.pack_start(title, False, False, 0)
subtitle = Gtk.Label(label="Local amanuensis for desktop dictation and rewriting.")
subtitle = Gtk.Label(label="Local amanuensis for X11 desktop dictation and rewriting.")
subtitle.set_xalign(0.0)
subtitle.set_line_wrap(True)
box.pack_start(subtitle, False, False, 0)
@ -445,7 +446,6 @@ class ConfigWindow:
if profile not in {"default", "fast", "polished"}:
profile = "default"
self._profile_combo.set_active_id(profile)
self._show_notifications_check.set_active(bool(self._config.ux.show_notifications))
self._strict_startup_check.set_active(bool(self._config.advanced.strict_startup))
self._safety_enabled_check.set_active(bool(self._config.safety.enabled))
self._safety_strict_check.set_active(bool(self._config.safety.strict))
@ -570,7 +570,6 @@ class ConfigWindow:
cfg.injection.remove_transcription_from_clipboard = self._remove_clipboard_check.get_active()
cfg.stt.language = self._language_combo.get_active_id() or "auto"
cfg.ux.profile = self._profile_combo.get_active_id() or "default"
cfg.ux.show_notifications = self._show_notifications_check.get_active()
cfg.advanced.strict_startup = self._strict_startup_check.get_active()
cfg.safety.enabled = self._safety_enabled_check.get_active()
cfg.safety.strict = self._safety_strict_check.get_active() and cfg.safety.enabled
@ -623,8 +622,10 @@ def show_help_dialog() -> None:
dialog.set_title("Aman Help")
dialog.format_secondary_text(
"Press your hotkey to record, press it again to process, and press Esc while recording to "
"cancel. Keep fact guard enabled to prevent accidental fact changes. Aman-managed mode is "
"the canonical supported path; expert mode exposes custom Whisper model paths for advanced users."
"cancel. Daily use runs through the tray and user service. Use Run Diagnostics or "
"the doctor -> self-check -> journalctl -> aman run --verbose flow when something breaks. "
"Aman-managed mode is the canonical supported path; expert mode exposes custom Whisper model paths "
"for advanced users."
)
dialog.run()
dialog.destroy()
@ -642,7 +643,7 @@ def _present_about_dialog(parent) -> None:
about = Gtk.AboutDialog(transient_for=parent, modal=True)
about.set_program_name("Aman")
about.set_version("pre-release")
about.set_comments("Local amanuensis for desktop dictation and rewriting.")
about.set_comments("Local amanuensis for X11 desktop dictation and rewriting.")
about.set_license("MIT")
about.set_wrap_license(True)
about.run()