feat(frontend) Improve onboarding screen with demo project selection

[mmabrouk]

Summary

Implements demo project workflow improvements including:

• Add open demo project option in onboarding screen

  • Adds "Return to your workspace" banner with improved UI and fixed positioning
  • Implements demo project state management (tracking last non-demo project, return hints)
  • Adds modal prompt when returning from demo to real workspace

  Changes

  State Management

  • Added lastNonDemoProjectAtom - tracks the user's last non-demo project
  • Added demoReturnHintPendingAtom & demoReturnHintDismissedAtom - manages demo return flow
  • Added helper functions cacheLastUsedProjectId for persisting project state

  UI Improvements

  • Layout banner: Fixed positioning banner that stays at top while scrolling
  • Replaced text-based banner with actionable "Return to your workspace" button
  • Added modal showing instructions when returning from demo

  OnboardingScreen

  • Updated to use project.is_demo field from API response

  Test Plan

  • Sign up with email/password → verify routed to /post-signup onboarding
  • Complete onboarding → verify placed in demo project
  • Scroll page → verify demo banner stays fixed at top
  • Click "Return to your workspace" button
  • Verify modal appears with instructions (first time)
  • Dismiss modal → verify navigates to last used real workspace
  • Re-enter demo → verify "Do not show again" dismissal is respected

---

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jan 27, 2026 8:34am

[mmabrouk]

Do not merge until demo project is ready

[CLAassistant]

All committers have signed the CLA.

[devin-ai-integration]

Devin Review found 1 potential issue.

View issue and 4 additional flags in Devin Review.

[devin-ai-integration]

🟡 Modal 'Got it' button incorrectly dismisses hint permanently

Both the 'Got it' (OK) and 'Do not show again' (Cancel) buttons in the demo return modal call the same closeDemoReturnModal function, which sets demoReturnHintDismissed to true. This means clicking 'Got it' will permanently dismiss the modal, making it behave identically to 'Do not show again'.

Click to expand

Expected vs Actual Behavior

Expected:

• 'Got it' should only close the modal for this session (user may see it again next time)
• 'Do not show again' should permanently dismiss the modal

Actual:
Both buttons permanently dismiss the modal because they both call:

const closeDemoReturnModal = useCallback(() => {
    setDemoReturnModalOpen(false)
    setDemoReturnHintDismissed(true)  // Always sets dismissed to true
}, [setDemoReturnHintDismissed])

This contradicts the PR's test plan which states:

• "Dismiss modal → verify navigates to last used real workspace"
• "Re-enter demo → verify 'Do not show again' dismissal is respected"

Impact

Users who click 'Got it' expecting to see the hint again later will never see it, breaking the intended UX flow where only explicit 'Do not show again' should permanently suppress the modal.

Recommendation: Create separate handlers for onOk and onCancel. The onOk handler ('Got it') should only close the modal without setting demoReturnHintDismissed, while onCancel ('Do not show again') should set demoReturnHintDismissed to true:

const handleOk = useCallback(() => {
    setDemoReturnModalOpen(false)
}, [])

const handleDoNotShowAgain = useCallback(() => {
    setDemoReturnModalOpen(false)
    setDemoReturnHintDismissed(true)
}, [setDemoReturnHintDismissed])

Then use onOk={handleOk} and onCancel={handleDoNotShowAgain}.

---

Was this helpful? React with 👍 or 👎 to provide feedback.