Update pricing UX, billing flows, and API rules

app/dewemoji-user-dashboard-implementation-plan.md

@@ -0,0 +1,143 @@
+# Dewemoji User Dashboard Implementation Plan
+
+**Source:** `dewemoji-ux-flow-brief.md`  
+**Goal:** Build the Personal user dashboard + inline personalization flows aligned with the UX brief.
+
+---
+
+## 1) Scope & Principles
+
+- **Primary flow**: Add keywords directly on emoji detail pages (fast, contextual).
+- **Secondary flow**: Manage keywords in the dashboard (bulk + power tools).
+- **Zero friction** for Visitors/Free users; gentle upgrade prompts.
+- **Shared layout** with admin (same shell, role-based sidebar).
+
+---
+
+## 2) User States & Routing
+
+### Visitor (non-logged)
+- Public search + emoji detail only.
+- CTA: “Sign up free” / “Upgrade to Personal”.
+
+### Free user (logged, no subscription)
+- See public content, “Your keywords” section locked.
+- Upgrade nudges on detail + empty states in dashboard.
+
+### Personal user (paid)
+- Full access: quick add on detail + dashboard CRUD.
+
+---
+
+## 3) UI Screens (User Dashboard)
+
+### 3.1 Dashboard shell (shared)
+- Same layout as admin (sidebar, top bar).
+- Role-based sidebar menu:
+  - Overview
+  - My Keywords
+  - API Keys
+  - Billing
+  - Preferences
+  - Support / Logout
+
+### 3.2 Overview (user)
+- Show:
+  - Total keywords
+  - Recent keyword additions (last 7 days)
+  - Synced devices (optional later)
+- Small quick link to “My Keywords”.
+
+### 3.3 My Keywords (primary management)
+- Table: Emoji | Your keywords | Language | Actions
+- Toolbar:
+  - + Add Keyword
+  - Import JSON
+  - Export JSON
+  - Search/filter
+- Modal: emoji picker → add keywords + language.
+
+### 3.4 API Keys
+- List user API keys
+- Create/revoke key
+
+### 3.5 Billing
+- Current plan + renewal / expiry
+- Payment method (future)
+- Upgrade CTA if free
+
+### 3.6 Preferences
+- Theme
+- Tone lock / preferred skin tone (future)
+- Locale
+
+---
+
+## 4) Site Page Enhancements (Non-dashboard)
+
+### 4.1 Emoji Detail Page (critical)
+- Show public keywords for everyone.
+- If Personal: show “Your Keywords” list + quick add modal.
+- If Free: show locked section + upgrade CTA.
+- If Visitor: CTA to sign up.
+
+### 4.2 Search Results Page
+- Personal user: blend public + user keywords.
+- Show “Your keyword” badge and “quick edit” button.
+
+---
+
+## 5) API Endpoints (v1)
+
+### Keyword CRUD
+- `GET /v1/emoji/{slug}?include_user_keywords=true`
+- `POST /v1/keywords` (add keyword)
+- `PUT /v1/keywords/{id}` (edit)
+- `DELETE /v1/keywords/{id}`
+- `GET /v1/keywords` (list user keywords)
+
+### User keyword import/export
+- `POST /v1/keywords/import`
+- `GET /v1/keywords/export`
+
+### Dashboard data
+- `GET /v1/user/summary` (counts + recents)
+- `GET /v1/user/apikeys` / `POST /v1/user/apikeys`
+- `GET /v1/user/billing` (subscription status)
+
+---
+
+## 6) Database / Models
+
+Existing:
+- `user_keywords`
+- `subscriptions`
+
+Add if needed:
+- `user_keyword_imports` (optional audit)
+
+---
+
+## 7) Implementation Phases
+
+### Phase A — Foundation
+- Add user routes + dashboard views
+- Layout reuse with role‑based sidebar
+
+### Phase B — Keywords UX
+- Detail page quick add
+- Dashboard keyword CRUD + import/export
+
+### Phase C — Billing & API Keys
+- Billing summary + upgrade CTA
+- API key list + create/revoke
+
+---
+
+## 8) Acceptance Criteria
+
+- Personal user can add keywords from detail page in <5 seconds.
+- Keyword appears in search results immediately.
+- Dashboard keyword table supports filter + edit + delete.
+- Free users see upgrade prompts, not broken UI.
+