Universal "payment required" UX harness (out-of-credits / needs-credits gate)

[softmarshmallow]

Problem

Metered features refuse when the org can't pay: the entitlement gate returns a hard insufficient_credits (402) before any work happens. Today each surface handles that refusal ad hoc — the desktop agent pane maps the code → an "add credits" CTA → web billing. As more metered surfaces land (agent chat, image, video, and web-side AI), each re-implements the "you're out of credits / this needs credits → top up" experience, and they will drift in copy, affordance, and resolution path.

Goal

One universal, reusable "payment required" UX harness — a single pattern (and shared component) every metered surface uses to present the gate and offer a consistent way to resolve it. Surface-agnostic (desktop + web) and modality-agnostic (chat / image / video).

Should cover

• Detection contract — the typed code (e.g. insufficient_credits) that survives boundaries like Electron's contextBridge. The Grida Gateway path already establishes this idiom; generalize it rather than re-derive per surface.
• Presentation — the consistent forms: inline banner, empty-state, and mid-action interruption, with shared copy and CTA.
• Resolution path — "add credits" → the web-delegated billing flow (manage_path + open_external on desktop; in-app on web). One canonical route.
• First-run vs. mid-use — a brand-new org with zero balance hits this on the first call, which reads differently from running out mid-session. The harness should present both cleanly.

Boundaries (related, separate issues)

• The initial-credit / trial decision (do new orgs get starter/trial credits at all?) is a product decision, not this harness.
• Plan-included credit grants (billing infra) are separate.

This issue is the UX harness those two plug into.

Altitude

Design → implementation: define the pattern + copy, then build the shared component and adopt it on the existing metered surfaces.