[UX] First-time AI service setup flow is fragmented and does not clearly lead users to first proxy success

[wanghuan-520]

Background

The current first-time AI service setup path is split across multiple product concepts and surfaces. A user can add an external service from AI Services, but the UI does not clearly guide them through the remaining steps needed to complete the actual end-to-end value path: creating or selecting a NyxID Agent Key and making the first successful proxied request.

The UX audit identifies this as a core activation risk. Users must understand the difference between:

External Service
External API Key / provider credential
NyxID API Key / Agent Key
Proxy verification

These concepts currently exist in the product, but there is no single guided path from service setup to first proxy success.

Current Behavior

A first-time user may follow this flow:

1. Open AI Services.
2. Click Add Service.
3. Select a catalog provider.
4. Enter a provider credential or OAuth app credentials.
5. Land on the new service detail page.
6. Separately discover that a NyxID Agent Key is required for proxy calls.
7. Navigate to the Agent Keys / NyxID API Keys tab.
8. Create an Agent Key.
9. Return to the service detail page or API Usage section.
10. Attempt a proxy call.

The flow does not clearly tell users what is complete, what remains, or which key should be used at each step.

Problem

Service creation, Agent Key creation, and proxy verification are split across different pages and concepts. Users can successfully create a service but still fail to reach the first successful proxy call.

The /ai-setup page also adds ambiguity. It sounds related to adding AI services, but it actually configures AI tools / MCP / skills rather than creating proxied services.

Expected Experience

The product should provide a clear first-time setup path that leads users to a first successful proxied call.

A complete flow should explicitly guide users through:

1. Add an external AI service.
2. Store or authorize the provider credential.
3. Create or select a NyxID Agent Key with proxy scope.
4. Copy or run the correct proxy verification command.
5. Confirm that the first proxy call returned a valid response.

Suggested Fix

• Add a guided first-time setup checklist or wizard for the AI service path.
• Make the relationship between External Services and NyxID Agent Keys explicit.
• After service creation, show a clear next step to create or select an Agent Key.
• Add an inline verification step that tells users whether the first proxy call succeeded.
• Clarify the naming and purpose of /ai-setup so users do not confuse it with service creation.

Impact

• Improves first-time user activation.
• Reduces confusion around which key to use.
• Reduces support burden for first proxy setup.
• Aligns the product flow with the core value path: connect a service and successfully proxy through NyxID.

---

[chronoai-bot]

github-devloop intake decision: enable
Service class: standard

Reason:
Progressive onboarding best practice favors a guided path to first value; this is implementable UX work for AI Services//ai-setup with no human-gate condition, and no two closed same-class siblings justify escalation.

[chronoai-bot]

github-devloop thinking: consensus started

[chronoai-bot]

github-devloop convergence round 0 - no three-angle consensus; narrowing

Narrowed question: Apply progressive onboarding to first value by narrowing #684 to improving existing AI Services flow: after service creation, show explicit NyxID Agent Key create/select guidance with proxy scope, a copyable proxy verification command, success/failure feedback, and clarify /ai-setup copy/navigation without adding a standalone wizard unless later evidence proves existing surfaces cannot carry it.

Angle stances:

• minimal: approve — Established practice for onboarding/activation is progressive guidance to first value, here first successful proxy call; approve only a narrow slice: after AI Services creation, show explicit NyxID Agent Key create/select guidance and a copyable verification command/result state, while deferring a full wizard and broad /ai-setup renaming until supported by user evidence; recurrence does not show a third same-class closed issue requiring class-level reframing.
• structural: approve — Established practice is progressive onboarding to first value with explicit state transitions while preserving domain boundaries; this proposal aligns by connecting External Service, provider credential, NyxID Agent Key, and proxy verification as separate but guided steps, with no recurrence threshold met in the provided history and no structural contract violation apparent.
• delete: abstain — Established onboarding practice supports guiding users to first value with progressive disclosure, contextual next steps, and success feedback, but the proposal jumps to adding a checklist or wizard without proving that existing AI Services, Agent Key, and proxy-usage surfaces cannot be simplified instead; approve only after narrowing to remove ambiguity in existing flows, add post-service next-step guidance, and verify first proxy success without introducing a new setup surface unless necessary.

⟦AI:FKST⟧