Document usability workflow and add acceptance tests

README.md

@@ -61,6 +61,14 @@ X11 (supported):
 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
+```
+
 ## Config
 
 Create `~/.config/aman/config.json` (or let `aman` create it automatically on first start if missing):
@@ -74,6 +82,13 @@ Create `~/.config/aman/config.json` (or let `aman` create it automatically on fi
     "backend": "clipboard",
     "remove_transcription_from_clipboard": false
   },
+  "ux": {
+    "profile": "default",
+    "show_notifications": true
+  },
+  "advanced": {
+    "strict_startup": true
+  },
   "vocabulary": {
     "replacements": [
       { "from": "Martha", "to": "Marta" },
@@ -90,6 +105,14 @@ If `recording.input` is explicitly set and cannot be resolved, startup fails
 instead of falling back to a default device.
 
 Config validation is strict: unknown fields are rejected with a startup error.
+Validation errors include the exact field and an example fix snippet.
+
+Profile options:
+
+- `ux.profile=default`: baseline cleanup behavior.
+- `ux.profile=fast`: lower-latency AI generation settings.
+- `ux.profile=polished`: same cleanup depth as default.
+- `advanced.strict_startup=true`: keep fail-fast startup validation behavior.
 
 Hotkey notes:
 
@@ -142,6 +165,7 @@ 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`.
 
 Wayland note:
 
@@ -161,5 +185,14 @@ Control:
 
 ```bash
 make run
+make doctor
 make check
 ```
+
+CLI:
+
+```bash
+uv run python3 src/aman.py run --config ~/.config/aman/config.json
+uv run python3 src/aman.py doctor --config ~/.config/aman/config.json --json
+uv run python3 src/aman.py init --config ~/.config/aman/config.json --force
+```