⌥+Space does nothing

The global hotkey needs no permissions. If it doesn’t respond:

Another app may own the same shortcut – change either side, or pick a different combination in Settings → General.
Check the menu bar: is Gisti actually running?

Screenshot overlay is black or empty

⇧ ⌘ X needs Screen Recording permission. Same procedure: System Settings → Privacy & Security → Screen Recording, enable Gisti, then relaunch – macOS applies this permission only on restart of the app.

AI doesn’t answer

Settings → AI → Test Connection tells you which part is wrong: key, URL, or model.
Cloud: check the key and billing/quota on the provider’s side.
Local: is the server actually up? curl http://localhost:11434 for Ollama. Check the model is pulled/loaded.
Slow local models can hit the timeout – raise aiTimeouts in advanced.yaml.

Semantic search / Topics look empty

The embedding model downloads on first use (~350 MB). Give it a moment on first run; check disk space. If it never recovers, delete advanced.yaml overrides (if any) and restart.

After an update

The Screen Recording permission occasionally needs re-granting after signature changes – macOS shows the entry as enabled while ignoring it. Remove Gisti from the list (−), add it again (+), relaunch.