[devxsubh]

Why

The AI Control Center showed a green "Everything stays on this computer" banner and "On-device" badges on every task while Ollama wasn't running, so nothing AI-related worked and the only hint was a small "Couldn't list models: fetch failed". It also asked people to assign models to tasks before they had any way to run one.

What changes

Status first. A new GET /api/ai/health checks each task for real: is the runtime up, is the model downloaded, is the key present and accepted, is Local-only mode blocking it, can the model use tools, does the provider support embeddings. The page's top card shows the result in plain words, with one fix button per cause (Start Ollama, Download, Add key, Allow cloud AI, Change model). The app-wide banner uses the same check, so it also warns when AI is configured but broken.

Guided setup. Choose "On this computer" or "Cloud provider":

• On-device: detects whether Ollama is missing or just stopped (and can start it), recommends models that fit this computer's memory, checks disk space, marks models that are already downloaded, optionally adds document search, and shows download progress in plain words. Downloads can be cancelled and resume where they left off.
• Cloud: pick a provider, then paste a key. The key is cleaned up (quotes, Bearer , NAME= lines), checked against the right provider ("This key looks like it's for OpenAI, not Anthropic"), and verified with the provider before it's stored. A rejected key is never saved; when you're offline you can save without the check. The model list comes from your account with a recommended default, and there's a text fallback if the list fails to load. Finishing requires explicit consent to what leaves the computer, and turns Local-only off. Document search uses the provider's embeddings, or keyword search for Anthropic, Groq and OpenRouter, with no Ollama dependency.

Advanced settings (collapsed) keeps the per-task model picker, model downloads, API keys and custom servers, with:

• confirmations before removing a model or key that's in use, and when choosing a cloud model while Local-only is on;
• a note that changing the embedding model sends existing documents back to keyword search;
• custom server IDs prefixed custom- so a server named "OpenAI" can't overwrite the built-in preset.

Errors. classifyLlmError sorts failures into auth / quota / rate-limit / model-missing / local-down / offline / timeout, and reads the cause on Node fetch errors. Messages no longer say "fetch failed" or "restart the backend".

Testing

• Backend and frontend typecheck clean; lint has 0 errors, and the 153 warnings are the same ones already on main.
• 21 helper checks pass: key cleanup and provider detection, chat-model filtering and recommendation, Ollama tag matching, error classification.
• In the desktop app with Ollama stopped: the card showed "Ollama isn't running" with a single Start Ollama button. Clicking it launched Ollama and the card switched to "AI is ready".
• On an isolated backend with a throwaway data directory:
  • Anthropic rejected a fake key with HTTP 422, and no secrets file was written.
  • The wrong-provider key, too-short key, bad custom URL, Anthropic-as-embedding, and cloud setup without a key were all refused with plain messages.
  • Health gave the right status and fix for: not set up, model not downloaded, blocked by Local-only, and key missing.
• Not tested: cloud setup end to end with a real API key.

🤖 Generated with Claude Code