AI settings UX: unclear relationship between Vision, Analysis, and API keys

[danmunz]

Problem

Users are confused by the AI settings:

"Do I need a Google Vision API key if I'm using GPT? What's the difference between Identification and Analysis? What is Analysis doing that Vision isn't doing?"

The two-stage pipeline (Vision for identification → Claude/OpenAI for analysis) is not intuitive from the Settings UI alone.

Current Behavior

The Settings modal has three sections:

1. Identification — Google Vision toggle + API key
2. Analysis — Claude or OpenAI model selection + API key
3. Automation — auto-analyze toggle

There is no in-UI explanation of:

• Why there are two separate services
• That Vision is optional (just provides hints to the LLM)
• That Analysis works fine without Vision
• What each stage actually produces

Proposed Fix

Add brief inline help text to the Settings modal:

• Under Identification: "Optional. Uses Google Vision to reverse-image search art databases, providing hints to the analysis model. Works without it — the LLM analyzes the image directly."
• Under Analysis: "Required for AI features. Analyzes the artwork image to identify artist, title, year, medium, movement, and mood. If Vision is enabled, its results are passed as context for more accurate identification."

Consider also:

• A small "How it works" expandable section
• Better field labels (e.g. "Stage 1: Identification (optional)" / "Stage 2: Analysis")

Source

Beta tester feedback on first-run confusion with AI configuration.