aman/docs/config-reference.md

# Config Reference

Use this document when you need the full Aman config shape and the advanced
behavior notes that are intentionally kept out of the first-run README path.

## Example config

```json
{
  "config_version": 1,
  "daemon": { "hotkey": "Cmd+m" },
  "recording": { "input": "0" },
  "stt": {
    "provider": "local_whisper",
    "model": "base",
    "device": "cpu",
    "language": "auto"
  },
  "models": {
    "allow_custom_models": false,
    "whisper_model_path": ""
  },
  "injection": {
    "backend": "clipboard",
    "remove_transcription_from_clipboard": false
  },
  "safety": {
    "enabled": true,
    "strict": false
  },
  "ux": {
    "profile": "default",
    "show_notifications": true
  },
  "advanced": {
    "strict_startup": true
  },
  "vocabulary": {
    "replacements": [
      { "from": "Martha", "to": "Marta" },
      { "from": "docker", "to": "Docker" }
    ],
    "terms": ["Systemd", "Kubernetes"]
  }
}
```

`config_version` is required and currently must be `1`. Legacy unversioned
configs are migrated automatically on load.

## Recording and validation

- `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
  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.

## Profiles and runtime behavior

- `ux.profile=default`: baseline cleanup behavior.
- `ux.profile=fast`: lower-latency AI generation settings.
- `ux.profile=polished`: same cleanup depth as default.
- `safety.enabled=true`: enables fact-preservation checks
  (names/numbers/IDs/URLs).
- `safety.strict=false`: fallback to the safer aligned draft when fact checks
  fail.
- `safety.strict=true`: reject output when fact checks fail.
- `advanced.strict_startup=true`: keep fail-fast startup validation behavior.

Transcription language:

- `stt.language=auto` enables Whisper auto-detection.
- You can pin language with Whisper codes such as `en`, `es`, `pt`, `ja`, or
  `zh`, or common names such as `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`, or
  `Ctrl+space`.
- `Super` and `Cmd` are equivalent aliases for the same modifier.

## Managed versus expert mode

- `Aman-managed` mode is the canonical supported UX: Aman handles model
  lifecycle and safe defaults for you.
- `Expert mode` is opt-in and exposes a custom Whisper model path for advanced
  users.
- Editor model/provider configuration is intentionally not exposed in config.
- Custom Whisper paths are only active with
  `models.allow_custom_models=true`.

Compatibility note:

- `ux.show_notifications` remains in the config schema for compatibility, but
  it is not part of the current supported first-run X11 surface and is not
  exposed in the settings window.

## Cleanup and model lifecycle

AI cleanup is always enabled and uses the locked local
`Qwen2.5-1.5B-Instruct-Q4_K_M.gguf` model downloaded to
`~/.cache/aman/models/` during daemon initialization.

- Prompts use semantic XML tags for both system and user messages.
- Cleanup runs in two local passes:
  - pass 1 drafts cleaned text and labels ambiguity decisions
    (correction/literal/spelling/filler)
  - pass 2 audits those decisions conservatively and emits final
    `cleaned_text`
- Aman stays in dictation mode: it does not execute editing instructions
  embedded in transcript text.
- Before Aman reports `ready`, the local editor runs a tiny warmup completion
  so the first real transcription is faster.
- If warmup fails and `advanced.strict_startup=true`, startup fails fast.
- With `advanced.strict_startup=false`, Aman logs a warning and continues.
- Model downloads use a network timeout and SHA256 verification before
  activation.
- Cached models are checksum-verified on startup; mismatches trigger a forced
  redownload.

## Verbose logging and vocabulary

- `-v/--verbose` enables DEBUG logs, including recognized/processed transcript
  text and `llama::` logs.
- Without `-v`, logs stay at INFO level.

Vocabulary correction:

- `vocabulary.replacements` is deterministic correction (`from -> to`).
- `vocabulary.terms` is a preferred spelling list used as hinting context.
- Wildcards are intentionally rejected (`*`, `?`, `[`, `]`, `{`, `}`) to avoid
  ambiguous rules.
- Rules are deduplicated case-insensitively; conflicting replacements are
  rejected.

STT hinting:

- Vocabulary is passed to Whisper as compact `hotwords` only when that argument
  is supported by the installed `faster-whisper` runtime.
- Aman enables `word_timestamps` when supported and runs a conservative
  alignment heuristic pass before the editor stage.

Fact guard:

- Aman runs a deterministic fact-preservation verifier after editor output.
- If facts are changed or invented and `safety.strict=false`, Aman falls back
  to the safer aligned draft.
- If facts are changed or invented and `safety.strict=true`, processing fails
  and output is not injected.