Polish onboarding flow docs and retry acceptance tests

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

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__":