From ed950cb7c45f2a0fd716e2b59dcd9e3b25657670 Mon Sep 17 00:00:00 2001
From: Thales Maciel <thales@thalesmaciel.com>
Date: Thu, 26 Feb 2026 17:58:16 -0300
Subject: [PATCH] Polish onboarding flow docs and retry acceptance tests

---
 README.md              | 15 +++++++++++----
 tests/test_aman_cli.py | 36 ++++++++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 91928da..f8db258 100644
--- a/README.md
+++ b/README.md
@@ -64,11 +64,17 @@ uv sync --extra x11
 ## Quickstart
 
 ```bash
-uv run python3 src/aman.py init
-uv run python3 src/aman.py doctor
 uv run python3 src/aman.py run
 ```
 
+On first launch, Aman opens a graphical setup wizard automatically.  
+The wizard asks for:
+
+- microphone input
+- hotkey
+- output backend
+- writing profile
+
 ## Config
 
 Create `~/.config/aman/config.json` (or let `aman` create it automatically on first start if missing):
@@ -165,7 +171,8 @@ Service notes:
 - `Esc` is only captured during active recording.
 - Recording start is aborted if the cancel listener cannot be armed.
 - Transcript contents are logged only when `-v/--verbose` is used.
-- Tray menu includes: `Pause/Resume Aman`, `Reload Config`, `Run Diagnostics`, `Open Config Path`, and `Quit`.
+- Tray menu includes: `Setup Aman...`, `Pause/Resume Aman`, `Reload Config`, `Run Diagnostics`, `Open Config Path`, and `Quit`.
+- If setup is not completed, Aman enters a `Setup Required` tray mode and does not capture audio.
 
 Wayland note:
 
@@ -189,7 +196,7 @@ make doctor
 make check
 ```
 
-CLI:
+CLI (internal/support fallback):
 
 ```bash
 uv run python3 src/aman.py run --config ~/.config/aman/config.json
diff --git a/tests/test_aman_cli.py b/tests/test_aman_cli.py
index 05cfacd..1d4f4b2 100644
--- a/tests/test_aman_cli.py
+++ b/tests/test_aman_cli.py
@@ -78,6 +78,20 @@ class _FakeDaemon:
         return True
 
 
+class _RetrySetupDesktop(_FakeDesktop):
+    def __init__(self):
+        super().__init__()
+        self.setup_invocations = 0
+
+    def run_tray(self, _state_getter, on_quit, **kwargs):
+        setup_cb = kwargs.get("on_setup_wizard")
+        if setup_cb is not None and self.setup_invocations == 0:
+            self.setup_invocations += 1
+            setup_cb()
+            return
+        on_quit()
+
+
 class AmanCliTests(unittest.TestCase):
     def test_parse_cli_args_defaults_to_run_command(self):
         args = aman._parse_cli_args(["--dry-run"])
@@ -186,6 +200,28 @@ class AmanCliTests(unittest.TestCase):
             self.assertFalse(path.exists())
             daemon_cls.assert_not_called()
 
+    def test_run_command_missing_config_cancel_then_retry_setup(self):
+        with tempfile.TemporaryDirectory() as td:
+            path = Path(td) / "config.json"
+            args = aman._parse_cli_args(["run", "--config", str(path)])
+            desktop = _RetrySetupDesktop()
+            onboard_cfg = Config()
+            onboarding_results = [
+                OnboardingResult(completed=False, config=None, aborted_reason="cancelled"),
+                OnboardingResult(completed=True, config=onboard_cfg, aborted_reason=None),
+            ]
+            with patch("aman._lock_single_instance", return_value=object()), patch(
+                "aman.get_desktop_adapter", return_value=desktop
+            ), patch(
+                "aman.run_onboarding_wizard",
+                side_effect=onboarding_results,
+            ), patch("aman.Daemon", _FakeDaemon):
+                exit_code = aman._run_command(args)
+
+            self.assertEqual(exit_code, 0)
+            self.assertTrue(path.exists())
+            self.assertEqual(desktop.setup_invocations, 1)
+
 
 
 if __name__ == "__main__":