feat: nudge users to add keys for unconfigured providers

[chongjiazhen]

A provider with enabled models but no API key is invisible in the dashboard today — /api/health only reports platforms that already have keys (GROUP BY api_keys). So free models the user could unlock just sit there unused, with nothing pointing them out. This adds a small, dismissible nudge.

What it does

• GET /api/health gains unconfiguredProviders (raw: enabled models, no enabled key — excluding custom, keyless providers, and platforms this binary can't route) plus nudgeState.
• KeysPage banner lists those providers ("Agnes AI (5), Zhipu (3), …"), with an Add key menu (preselects the provider in the existing form) and a Dismiss menu: snooze until a new provider appears / don't show for {provider} / don't ask again.
• Permanent dropdown annotation — the AddKeyForm platform <select> now shows "· N free models, no key" on unconfigured providers, driven by the raw list so it survives "Don't ask again". This is the always-available reference; the banner is just the proactive layer.
• POST /api/keys/nudge ({scope, platform?}) persists dismiss state in settings; adding a key prunes that provider from the mute/snooze sets.

Design notes

• Dismiss state lives server-side (settings table), so it's consistent across the browser dashboard and desktop app.
• unconfiguredProviders is returned raw; the banner derives its visible subset (raw − muted − snoozed, hidden when disabled) on the client. Muting a provider therefore silences the banner but keeps its dropdown hint — the information is never buried.
• Value is mostly update-independent: it surfaces day-one keyless providers and catalog-sync additions for already-supported providers. (New provider support still needs a binary update — catalog-sync skips unregistered platforms — but the nudge then helps the user notice it.)

Scope

v1 is the KeysPage banner + dropdown only. Deliberately out: catalog-delta "newly-added only" detection, desktop tray notification, global banner.

Tests

New service unit tests (raw detection; keyless/custom/unroutable exclusion; mute/disable/snooze-snapshot semantics; prune; corrupt-JSON degrade) and route tests (health field, all dismiss scopes incl. 400s, prune-on-key-add). Full server suite green.

Test Files  49 passed (49)
     Tests  509 passed (509)

Client tsc -b && vite build clean.

[chongjiazhen]

Quick context on intent: this is a proposal, not a "please merge." I opened it as a draft PR so the design is concrete and reviewable rather than hand-waved in an issue — but I haven't gauged your appetite for it, and scope/approach are entirely yours to steer.

Totally fine to convert this to an issue, reshape it, or close if a key-nudge isn't a direction you want. If you are interested, the obvious open questions are:

• whether the surface (KeysPage banner + dropdown annotation) is where you'd want it, vs. somewhere lighter;
• whether the server-side dismiss state (settings table) is worth it, or you'd prefer something simpler;
• scope of Phase 1 vs. deferring the dropdown annotation.

No rush on this one — happy to follow your lead.

[tashfeenahmed]

The concept and tests here are good. The Keys page was redesigned in #467 (add-key dialog, collapsible provider sections), so the banner and the AddKeyForm hooks need re-hosting onto the new layout. A rebase is welcome; if the mapping isn't clean, ping me here and we'll figure out placement together.

[tashfeenahmed]

Thanks for opening this as a working draft instead of an issue. Having the design concrete made it much easier to think about, and the tests you wrote were genuinely good.

We ended up approaching the same problem from a slightly different angle. There is now a GET /api/keys/providers endpoint in main that reports which built in providers still have no key, and a checklist on the Keys page built on top of it is in review in #596. That covers the visibility gap you identified here, so I am closing this one on the offer you made in the thread.

Your diagnosis was right, and it pushed the idea forward. Thanks for the care you put into it.