Thales Maciel
359b5fbaf4
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.
65 lines
4.5 KiB
Markdown
65 lines
4.5 KiB
Markdown
# Runtime Recovery Guide
|
|
|
|
Use this guide when Aman is installed but not behaving correctly.
|
|
|
|
## First-run troubleshooting
|
|
|
|
- Settings window did not appear:
|
|
run `aman run --config ~/.config/aman/config.json` once in the foreground so
|
|
you can complete first-run setup.
|
|
- No tray icon after saving settings:
|
|
run `aman self-check --config ~/.config/aman/config.json` and confirm the
|
|
user service is enabled and active.
|
|
- Hotkey does not start recording:
|
|
run `aman doctor --config ~/.config/aman/config.json`, then choose a
|
|
different hotkey in Settings if `hotkey.parse` is not `ok`.
|
|
- Microphone test failed:
|
|
re-open Settings, choose another input device, then rerun `aman doctor`.
|
|
- Text was transcribed but not injected:
|
|
run `aman doctor`, then rerun `aman run --config ~/.config/aman/config.json --verbose`
|
|
to inspect the output backend in the foreground.
|
|
|
|
## Command roles
|
|
|
|
- `aman doctor --config ~/.config/aman/config.json` is the fast, read-only preflight for config, X11 session, audio runtime, input device resolution, hotkey availability, injection backend selection, and service prerequisites.
|
|
- `aman self-check --config ~/.config/aman/config.json` is the deeper, still read-only readiness check. It includes every `doctor` check plus the managed model cache, cache writability, installed user service, current service state, and startup readiness.
|
|
- Tray `Run Diagnostics` uses the same deeper `self-check` path and logs any non-`ok` results.
|
|
|
|
## Reading the output
|
|
|
|
- `ok`: the checked surface is ready.
|
|
- `warn`: the checked surface is degraded or incomplete, but the command still exits `0`.
|
|
- `fail`: the supported path is blocked, and the command exits `2`.
|
|
|
|
Example output:
|
|
|
|
```text
|
|
[OK] config.load: loaded config from /home/user/.config/aman/config.json
|
|
[WARN] model.cache: managed editor model is not cached at /home/user/.cache/aman/models/Qwen2.5-1.5B-Instruct-Q4_K_M.gguf | next_step: start Aman once on a networked connection so it can download the managed editor model, then rerun `aman self-check --config /home/user/.config/aman/config.json`
|
|
[FAIL] service.state: user service is installed but failed to start | next_step: inspect `journalctl --user -u aman -f` to see why aman.service is failing
|
|
overall: fail
|
|
```
|
|
|
|
## Failure map
|
|
|
|
| Symptom | First command | Diagnostic ID | Meaning | Next step |
|
|
| --- | --- | --- | --- | --- |
|
|
| Config missing or invalid | `aman doctor` | `config.load` | Config is absent or cannot be parsed | Save settings, fix the JSON, or rerun `aman init --force`, then rerun `doctor` |
|
|
| No X11 session | `aman doctor` | `session.x11` | `DISPLAY` is missing or Wayland was detected | Start Aman from the same X11 user session you expect to use daily |
|
|
| Audio runtime or microphone missing | `aman doctor` | `runtime.audio` or `audio.input` | PortAudio or the selected input device is unavailable | Install runtime dependencies, connect a microphone, or choose a valid `recording.input` |
|
|
| Hotkey cannot be registered | `aman doctor` | `hotkey.parse` | The configured hotkey is invalid or already taken | Choose a different hotkey in Settings |
|
|
| Output injection fails | `aman doctor` | `injection.backend` | The chosen X11 output path is not usable | Switch to a supported backend or rerun in the foreground with `--verbose` |
|
|
| Managed editor model missing or corrupt | `aman self-check` | `model.cache` | The managed model is absent or has a bad checksum | Start Aman once on a networked connection, or clear the broken cache and retry |
|
|
| Model cache directory is not writable | `aman self-check` | `cache.writable` | Aman cannot create or update its managed model cache | Fix permissions on `~/.cache/aman/models/` |
|
|
| User service missing or disabled | `aman self-check` | `service.unit` or `service.state` | The service was not installed cleanly or is not active | Reinstall Aman or run `systemctl --user enable --now aman` |
|
|
| Startup still fails after install | `aman self-check` | `startup.readiness` | Aman can load config but cannot assemble its runtime without failing | Fix the named runtime dependency, custom model path, or editor dependency, then rerun `self-check` |
|
|
|
|
## Escalation order
|
|
|
|
1. Run `aman doctor --config ~/.config/aman/config.json`.
|
|
2. Run `aman self-check --config ~/.config/aman/config.json`.
|
|
3. Inspect `journalctl --user -u aman -f`.
|
|
4. Re-run Aman in the foreground with `aman run --config ~/.config/aman/config.json --verbose`.
|
|
|
|
If you are collecting evidence for a release or support handoff, copy the first
|
|
non-`ok` diagnostic line and the first matching `journalctl` failure block.
|