Add multilingual STT support and config UI/runtime updates

README.md

@@ -64,16 +64,18 @@ uv sync --extra x11
 ## Quickstart
 
 ```bash
-uv run python3 src/aman.py run
+uv run aman run
 ```
 
-On first launch, Aman opens a graphical setup wizard automatically.  
-The wizard asks for:
+On first launch, Aman opens a graphical settings window automatically.
+It includes sections for:
 
 - microphone input
 - hotkey
 - output backend
 - writing profile
+- runtime and model strategy
+- help/about actions
 
 ## Config
 
@@ -81,9 +83,30 @@ Create `~/.config/aman/config.json` (or let `aman` create it automatically on fi
 
 ```json
 {
+  "config_version": 1,
   "daemon": { "hotkey": "Cmd+m" },
   "recording": { "input": "0" },
-  "stt": { "model": "base", "device": "cpu" },
+  "stt": {
+    "provider": "local_whisper",
+    "model": "base",
+    "device": "cpu",
+    "language": "auto"
+  },
+  "llm": { "provider": "local_llama" },
+  "models": {
+    "allow_custom_models": false,
+    "whisper_model_path": "",
+    "llm_model_path": ""
+  },
+  "external_api": {
+    "enabled": false,
+    "provider": "openai",
+    "base_url": "https://api.openai.com/v1",
+    "model": "gpt-4o-mini",
+    "timeout_ms": 15000,
+    "max_retries": 2,
+    "api_key_env_var": "AMAN_EXTERNAL_API_KEY"
+  },
   "injection": {
     "backend": "clipboard",
     "remove_transcription_from_clipboard": false
@@ -105,6 +128,9 @@ Create `~/.config/aman/config.json` (or let `aman` create it automatically on fi
 }
 ```
 
+`config_version` is required and currently must be `1`. Legacy unversioned
+configs are migrated automatically on load.
+
 Recording input can be a device index (preferred) or a substring of the device
 name.
 If `recording.input` is explicitly set and cannot be resolved, startup fails
@@ -120,6 +146,12 @@ Profile options:
 - `ux.profile=polished`: same cleanup depth as default.
 - `advanced.strict_startup=true`: keep fail-fast startup validation behavior.
 
+Transcription language:
+
+- `stt.language=auto` (default) enables Whisper auto-detection.
+- You can pin language with Whisper codes (for example `en`, `es`, `pt`, `ja`, `zh`) or common names like `English`/`Spanish`.
+- If a pinned language hint is rejected by the runtime, Aman logs a warning and retries with auto-detect.
+
 Hotkey notes:
 
 - Use one key plus optional modifiers (for example `Cmd+m`, `Super+m`, `Ctrl+space`).
@@ -131,6 +163,15 @@ Model downloads use a network timeout and SHA256 verification before activation.
 Cached models are checksum-verified on startup; mismatches trigger a forced
 redownload.
 
+Provider policy:
+
+- `Aman-managed` mode (recommended) is the canonical supported UX:
+  Aman handles model lifecycle and safe defaults for you.
+- `Expert mode` is opt-in and exposes custom providers/models for advanced users.
+- External API auth is environment-variable based (`external_api.api_key_env_var`);
+  no API key is stored in config.
+- Custom local model paths are only active with `models.allow_custom_models=true`.
+
 Use `-v/--verbose` to enable DEBUG logs, including recognized/processed
 transcript text and llama.cpp logs (`llama::` prefix). Without `-v`, logs are
 INFO level.
@@ -150,9 +191,7 @@ STT hinting:
 ## systemd user service
 
 ```bash
-mkdir -p ~/.local/share/aman/src/assets
-cp src/*.py ~/.local/share/aman/src/
-cp src/assets/*.png ~/.local/share/aman/src/assets/
+uv pip install --user .
 cp systemd/aman.service ~/.config/systemd/user/aman.service
 systemctl --user daemon-reload
 systemctl --user enable --now aman
@@ -160,7 +199,7 @@ systemctl --user enable --now aman
 
 Service notes:
 
-- The user unit launches `uv` via `/usr/bin/env`; ensure `uv` is available in your user `PATH` (for example `~/.local/bin`).
+- The user unit launches `aman` from `PATH`; ensure `~/.local/bin` is present in your user PATH.
 - Inspect failures with `systemctl --user status aman` and `journalctl --user -u aman -f`.
 
 ## Usage
@@ -171,8 +210,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: `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.
+- Tray menu includes: `Settings...`, `Help`, `About`, `Pause/Resume Aman`, `Reload Config`, `Run Diagnostics`, `Open Config Path`, and `Quit`.
+- If required settings are not saved, Aman enters a `Settings Required` tray mode and does not capture audio.
 
 Wayland note:
 
@@ -186,20 +225,24 @@ Injection backends:
 
 AI processing:
 
-- Local llama.cpp model only (no remote provider configuration).
+- Default local llama.cpp model.
+- Optional external API provider through `llm.provider=external_api`.
 
 Control:
 
 ```bash
 make run
 make doctor
+make self-check
 make check
 ```
 
-CLI (internal/support fallback):
+CLI (internal/support fallback, mostly for automation/tests):
 
 ```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
+uv run aman run --config ~/.config/aman/config.json
+uv run aman doctor --config ~/.config/aman/config.json --json
+uv run aman self-check --config ~/.config/aman/config.json --json
+uv run aman version
+uv run aman init --config ~/.config/aman/config.json --force
 ```