=== CURSOR-READY PROMPT ===

Task: Build a responsive dashboard page for authenticated users in the existing SaaS app.

Context: The app already has login/authentication. The dashboard should show user metrics, recent activity, and quick actions while following existing project patterns.

Before editing:

1. Inspect the project structure.
2. Identify the framework, routing system, authentication flow, layout components, styling conventions, and existing data-fetching patterns.
3. Identify whether a dashboard route or authenticated layout already exists.
4. Identify any existing metric, activity, card, button, or navigation components that should be reused.
5. Check for existing tests and run relevant ones if possible.
6. Create a brief implementation plan before editing.

Scope: Create or update the authenticated dashboard experience.

Out of scope:

• changing authentication logic
• changing database schema
• changing payment or billing logic
• replacing the styling system
• rewriting unrelated components
• changing public routes
• adding unnecessary dependencies

Implementation requirements: The dashboard must include:

1. Welcome/header section for the signed-in user.
2. User metrics section with clear cards.
3. Recent activity section.
4. Quick actions section.
5. Loading state.
6. Empty state for new users.
7. Error state for failed data loading.
8. Responsive layout for desktop, tablet, and mobile.
9. Accessible headings, labels, buttons, and color contrast.

Data requirements: Use existing API/data-fetching patterns if available. If real dashboard data is not available yet, create a clearly marked mock-data layer or placeholder structure that can be replaced later without changing the UI.

Acceptance criteria:

• Authenticated users can view the dashboard.
• Unauthenticated access follows the existing app behavior.
• Dashboard layout works on mobile and desktop.
• Loading, empty, error, and success states are handled.
• Existing navigation and authentication behavior remain unchanged.
• No unrelated broad refactor is performed.
• Code follows existing project conventions.

Testing requirements:

• Run existing tests if available.
• Add or recommend component/page tests for dashboard states if the project supports them.
• Manually verify the dashboard at mobile and desktop widths.
• Verify no console errors appear.
• Verify authentication flow is not changed.

Constraints:

• Do not rewrite unrelated files.
• Do not modify authentication logic unless required and explained first.
• Do not change database schema.
• Do not add new dependencies unless necessary.
• Do not expose secrets or environment variable values.

Return:

• files inspected
• files changed
• implementation summary
• tests added or run
• manual verification steps
• assumptions made
• risks remaining