Context

The MCP server installation flow requires new users to generate API keys to use the product. We needed to decide where key management lives in the IA and whether keys should be front-and-center for new users.

Options Considered

Option A: Keep at /h/dashboard/keys (current)

Maintain nested dashboard route, rely on separate onboarding flow to guide users.

• Pros: No code changes, natural IA, expected location for returning users
• Cons: Not discoverable without guidance, requires separate onboarding work

Option B: Dedicated /h/keys route (top-level)

Elevate keys to first-class top-level route.

• Pros: More discoverable, cleaner URL, signals importance
• Cons: Still not first post-signup destination, route changes needed

Option C: Onboarding-first flow with keys as mandatory step

New users land on onboarding page requiring key generation before accessing main app.

• Pros: Ensures every user gets a key, streamlined first-run, clean separation
• Cons: More complexity, might feel blocking, two UIs for key generation

Option D: Post-signup redirect to keys page

Redirect new users to existing keys page after signup.

• Pros: Minimal code, leverages existing UI
• Cons: Less guided, may overwhelm with full feature set

Decision

Selected: Option C - Onboarding-first flow with keys as mandatory step

Approach

1. Create /h/onboard route that checks if user has any API keys
2. If no keys, show streamlined key generation flow (subset of current keys page)
3. After generating first key, redirect to dashboard
4. Returning users with keys bypass onboarding
5. Keys management remains at /h/dashboard/keys for ongoing management

Rationale

Given the parent goal is "MCP server installation flow for new users" and there's already a planned task for "Build first-time user onboarding flow", Option C aligns best:

1. Makes key generation the clear first action
2. Creates streamlined experience without cognitive overhead of full keys page
3. Clean separation: onboarding (get key) vs management (CRUD keys)
4. Naturally supports the "Update keys page for onboarding context" subtask

Implementation Notes

• /h/onboard should check for existing keys via API
• Streamlined UI: just key name input + generate button + copy result
• Skip rate limit info and revocation UI for first-run
• Store "has_completed_onboarding" or detect via key existence
• Keys page at /h/dashboard/keys unchanged for returning users

Context

The MCP server installation flow requires new users to generate API keys to use the product. We needed to decide where key management lives in the IA and whether keys should be front-and-center for new users.

Options Considered

Option A: Keep at /h/dashboard/keys (current)

Maintain nested dashboard route, rely on separate onboarding flow to guide users.

• Pros: No code changes, natural IA, expected location for returning users
• Cons: Not discoverable without guidance, requires separate onboarding work

Option B: Dedicated /h/keys route (top-level)

Elevate keys to first-class top-level route.

• Pros: More discoverable, cleaner URL, signals importance
• Cons: Still not first post-signup destination, route changes needed

Option C: Onboarding-first flow with keys as mandatory step

New users land on onboarding page requiring key generation before accessing main app.

• Pros: Ensures every user gets a key, streamlined first-run, clean separation
• Cons: More complexity, might feel blocking, two UIs for key generation

Option D: Post-signup redirect to keys page

Redirect new users to existing keys page after signup.

• Pros: Minimal code, leverages existing UI
• Cons: Less guided, may overwhelm with full feature set

Decision

Selected: Option C - Onboarding-first flow with keys as mandatory step

Approach

1. Create /h/onboard route that checks if user has any API keys
2. If no keys, show streamlined key generation flow (subset of current keys page)
3. After generating first key, redirect to dashboard
4. Returning users with keys bypass onboarding
5. Keys management remains at /h/dashboard/keys for ongoing management

Rationale

Given the parent goal is "MCP server installation flow for new users" and there's already a planned task for "Build first-time user onboarding flow", Option C aligns best:

1. Makes key generation the clear first action
2. Creates streamlined experience without cognitive overhead of full keys page
3. Clean separation: onboarding (get key) vs management (CRUD keys)
4. Naturally supports the "Update keys page for onboarding context" subtask

Implementation Notes

• /h/onboard should check for existing keys via API
• Streamlined UI: just key name input + generate button + copy result
• Skip rate limit info and revocation UI for first-run
• Store "has_completed_onboarding" or detect via key existence
• Keys page at /h/dashboard/keys unchanged for returning users