Consolidate docs and finalize APK companion updates

2026-03-16 01:06:41 +07:00
parent 95609dc0cf
commit 88218c7798
48 changed files with 7847 additions and 4502 deletions
--- a/dewemoji-direction-2026.md
+++ b/dewemoji-direction-2026.md
@@ -1,641 +1,142 @@
-# Dewemoji Product Direction & Strategy Brief
+# Dewemoji Product Direction (2026)

-**Version:** 2.0  
-**Date:** February 8, 2026  
-**Author:** Dwindi (Project Owner)  
+## Product decision snapshot

---
+Dewemoji is a **personal emoji library** product:

-## Executive Summary
+- Free: public emoji discovery (EN/ID dataset)
+- Paid (`Personal`): private keyword library + sync + account features
+- Main value: "your words -> your emojis"

-Dewemoji pivots from a public community-driven emoji dictionary to a **personal emoji library platform** where users build, sync, and own their keyword vocabularies across devices. This eliminates moderation overhead, AI costs, and public abuse risks while monetizing the core unique value: **private, multilingual keyword customization + seamless sync**.
+Tagline:

-**New Tagline:** *"Your words → your emojis, anywhere"*
+- "Your words -> your emojis, anywhere"

---
+## What is in scope now

-## 1. Vision & Mission
+### Core model

-### Vision
-Enable everyone to find and use emojis using *their* language, slang, and personal vocabulary—without language barriers or platform limitations.
+1. Public search remains open and fast.
+2. Private keywords are user-owned and synced.
+3. Paid conversion is driven by personalization value, not by limiting discovery.

-### Mission
-Provide a semantic emoji discovery platform that:
- Offers unlimited free public search (EN/ID + semantic matching)
- Lets users create private, personal keyword libraries (any language, any script)
- Syncs personal libraries across web, extensions, and future apps
- Removes friction from emoji usage in daily communication
+### Tier model

-### Core Problem Being Solved
-"I spent too much time finding an emoji because I think in my language/slang ('bekicot' for 🐌), and most tools only understand English keywords."
+- Free: unlimited public search, copy/insert, skin tone utilities
+- Personal: private keywords, keyword sync, API keys, dashboard access

---
+Pricing target used in planning:

-## 2. Strategic Pivot: Why Private-Only Keywords
+- Monthly: `$4.99`
+- Annual: `$49`
+- Lifetime: `$99`

-### Previous Model (Abandoned)
- Public community keyword submissions
- Voting/moderation for global searchability
- AI moderation for toxicity
- SEO feeding from user keywords
+## UX direction

-### Problems with Previous Model
-1. **AI moderation costs** haunting scalability
-2. **Moral responsibility** for public bad words feeding internet
-3. **Unclear monetization** (who pays for emoji stuff?)
-4. **Complexity** managing voting, thresholds, public curation
+### User states

-### New Model (Adopted)
- **Fully private user keyword libraries**
- No public submissions, no voting, no AI moderation
- Users own and control their keywords (stored per account)
- Public search stays free and unlimited (referrer-whitelisted)
-
-### Benefits
-✅ **Zero moderation burden** (private = user's responsibility)  
-✅ **No AI costs** (no content filtering needed)  
-✅ **Clear monetization** (pay for personal sync, not public features)  
-✅ **Moral simplicity** (no liability for user's private words)  
-✅ **Technical simplicity** (CRUD keywords per user_id)  
-
---
+1. Visitor: discover and use immediately (no login wall)
+2. Free logged-in user: sees upgrade paths where personalization would help
+3. Personal user: quick add on detail pages + full dashboard management

-## 3. Monetization Model
+### Primary flow

-### Core Principle
-**"Free discovery → Paid personalization"**
+1. User discovers emoji from public search.
+2. Personal user adds custom keyword from emoji detail page.
+3. Keyword becomes immediately searchable for that user.
+4. Dashboard handles bulk CRUD/import/export/API key management.

-Users get unlimited free public search to discover and love the product, then upgrade to sync their personal vocabulary.
-
-### Tiers
-
-| Feature | Free | Personal ($4.99/mo) |
-|---------|------|---------------------|
-| **Public emoji search** | ✅ Unlimited (EN/ID keywords) | ✅ Unlimited |
-| **Search result limit** | ✅ No limits | ✅ No limits |
-| **Skintone variations** | ✅ Free | ✅ Free |
-| **Copy to clipboard** | ✅ Free | ✅ Free |
-| **Auto-Insert to page** | ✅ Free (viral hook!) | ✅ Free |
-| **Automatic mode** | ✅ Free | ✅ Free |
-| **Private keywords** | ❌ Not available | ✅ Unlimited CRUD |
-| **Keyword sync** | ❌ Not available | ✅ Cross-device/app |
-| **API keys** | ❌ Not available | ✅ Generate/revoke |
-| **Dashboard access** | ❌ Not available | ✅ Full management |
-
-### Tier Naming
- **Free** → stays "Free"
- **Pro** → renamed to **"Personal"** (reflects private/personal keywords, not business/pro tools)
-
-### Pricing Options
- **Monthly:** $4.99/month (Stripe subscription)
- **Annual:** $49/year (~$4.08/month, 17% savings)
- **Lifetime:** $99 (one-time, early adopter offer)
-
-### Payment Flexibility
-Self-generated API keys mean **any payment provider works**:
- Stripe (primary, global)
- Paddle (backup)
- Midtrans/Xendit (Indonesia localization)
- No dependency on Gumroad license keys
-
---
-
-## 4. Channel Roles & User Flows
-
-### 4.1 Website (dewemoji.com)
-
-#### Non-Logged Users
-**Purpose:** Free discovery & viral entry point
-
-**Features:**
- Search emojis by public keywords (EN/ID)
- Browse by category/subcategory
- Copy emojis to clipboard
- View emoji details (unified, codepoints, shortcodes)
- No account required
-
-**CTA:** "Want your own keywords like 'bekicot'? → Sign Up Free"
-
-#### Logged Users (Free Account)
-**Purpose:** Dashboard teaser
-
-**Features:**
- View personal keywords section (muted/disabled with upgrade prompt)
- View API keys section (muted/disabled)
- Access to upgrade flow
- Search still unlimited (public keywords)
-
-**State:** "You have 0 personal keywords. Upgrade to Personal to create unlimited."
-
-#### Logged Users (Personal Tier)
-**Purpose:** Full keyword management hub
-
-**Features:**
- **Keyword Management:**
-  - Table view: emoji | your keywords | language | actions (edit/delete)
-  - Add new keyword: select emoji → enter keyword(s) → set language → save
-  - Bulk import/export (JSON)
- **API Key Management:**
-  - Generate new keys (dew_abc123...)
-  - Revoke keys
-  - Copy to clipboard (for extension login)
-  - View usage stats per key (future)
- **Billing Dashboard:**
-  - Current plan status
-  - Payment history table (date, amount, status, invoice)
-  - Upgrade/downgrade/cancel buttons
-  - Next billing date
-
-**Navigation:**
-```
-Dashboard
-├─ Search (always visible)
-├─ My Keywords
-├─ API Keys
-└─ Billing
-```
-
---
-
-### 4.2 Chrome Extension
-
-**Purpose:** Viral growth engine + seamless Personal upsell
-
-#### Free Features (Unlimited, No Limits)
- Search public emoji keywords (EN/ID + semantic)
- Skintone variations
- Copy to clipboard
- **Auto-Insert** (click emoji → inserts at cursor position)
- **Automatic mode** (detect input → insert; else copy)
- No daily/hourly limits
- No login required for public search
-
-#### Personal Features (Requires Login)
- Search blends **private + public** keywords
- Personal keywords auto-sync from dashboard
- API key authentication (stored securely in chrome.storage)
-
-#### Auth Flow
-1. User clicks "Link Account" in extension settings
-2. Login popup (email/password) → POST /v1/user/login
-3. Extension receives + stores API key
-4. All searches now include Authorization: Bearer header
-5. Results blend user's private keywords + public semantic data
-
-#### Upgrade Prompt
- Trigger: User searches term matching no public results
- Message: "Not found in public keywords. Create 'bekicot → 🐌' in your Personal library?"
- CTA: Opens dewemoji.com/upgrade in new tab
-
---
-
-### 4.3 API (Backend)
-
-**Purpose:** Single source of truth for all channels
-
-#### Public Endpoints (Free, Referrer-Whitelisted)
-```
-GET  /v1/emojis              # Search/browse public keywords
-GET  /v1/emoji/:slug         # Emoji detail
-GET  /v1/categories          # Category list
-GET  /v1/health              # Health check
-```
-
-**Whitelist Rules:**
- `Origin: https://dewemoji.com`
- `User-Agent: ...chrome-extension://elcikbedkbpkmdhkcmfnkdaacmnpdmha...`
- `Origin: localhost | 127.0.0.1` (dev)
-
-**Rate Limit:** Soft throttle at 5000 requests/hour/IP (invisible to real users, stops bombers)
-
-#### User Endpoints (Authentication Required)
-```
-POST /v1/user/register       # Create account
-POST /v1/user/login          # Login → returns api_keys
-POST /v1/user/logout         # Invalidate session
-```
-
-#### Personal Tier Endpoints (API Key Required)
-```
-# Keyword CRUD
-GET    /v1/keywords          # List user's private keywords
-POST   /v1/keywords          # Create/update keyword
-DELETE /v1/keywords/:id      # Delete keyword
-GET    /v1/search?private=true  # Search (private + public blend)
-
-# API Key Management
-GET    /v1/user/apikeys      # List user's keys
-POST   /v1/user/apikeys      # Generate new key
-DELETE /v1/user/apikeys/:key # Revoke key
-```
-
-**Authentication:**
- Header: `Authorization: Bearer dew_abc123...`
- Validation: Lookup in `user_api_keys` table → verify user_id has active Personal subscription
-
---
-
-## 5. Technical Implementation
-
-### 5.1 Database Schema Changes
-
-#### New Tables
-
-```sql
-- Users table
-users (
-  id UUID PRIMARY KEY,
-  email VARCHAR UNIQUE NOT NULL,
-  password_hash VARCHAR NOT NULL,
-  tier ENUM('free', 'personal') DEFAULT 'free',
-  created_at TIMESTAMP,
-  updated_at TIMESTAMP
-)
-
-- API keys table
-user_api_keys (
-  id UUID PRIMARY KEY,
-  user_id UUID REFERENCES users(id),
-  key VARCHAR(64) UNIQUE NOT NULL,  -- e.g., dew_abc123...
-  name VARCHAR(100),  -- optional label
-  created_at TIMESTAMP,
-  last_used_at TIMESTAMP,
-  revoked_at TIMESTAMP NULL
-)
-
-- Private keywords table
-user_keywords (
-  id UUID PRIMARY KEY,
-  user_id UUID REFERENCES users(id),
-  emoji_slug VARCHAR NOT NULL,  -- references existing emoji dataset
-  keyword VARCHAR(200) NOT NULL,
-  lang VARCHAR(10) NOT NULL,  -- ISO code or 'slang'
-  created_at TIMESTAMP,
-  updated_at TIMESTAMP,
-  UNIQUE(user_id, emoji_slug, keyword)
-)
-
-- Subscriptions table (for billing)
-subscriptions (
-  id UUID PRIMARY KEY,
-  user_id UUID REFERENCES users(id),
-  plan VARCHAR(20),  -- 'monthly', 'annual', 'lifetime'
-  status ENUM('active', 'canceled', 'expired'),
-  started_at TIMESTAMP,
-  expires_at TIMESTAMP NULL,
-  stripe_subscription_id VARCHAR NULL
-)
-```
-
-### 5.2 API Validation Flow
-
-**For Public Endpoints:**
-```
-1. Check Origin/Referer/User-Agent
-2. If whitelisted → allow unlimited
-3. Else → require valid API key (Personal tier)
-4. Apply soft IP throttle (5000/hour)
-```
-
-**For Personal Endpoints:**
-```
-1. Extract Authorization: Bearer <key>
-2. Lookup key in user_api_keys (not revoked)
-3. Lookup user_id → verify subscriptions.status = 'active'
-4. If valid → proceed
-5. Else → 401 Unauthorized
-```
-
-### 5.3 Search Logic (Private + Public Blend)
-
-**Endpoint:** `GET /v1/search?q=bekicot&private=true`
-
-**Algorithm:**
-```
-1. If private=true and valid API key:
-   a. Query user_keywords WHERE user_id=X AND keyword LIKE '%bekicot%'
-   b. Query public emojis.json WHERE keywords LIKE '%bekicot%'
-   c. Merge results (private first, then public)
-   d. Deduplicate by emoji_slug
-   
-2. If private=false or no API key:
-   a. Query public emojis.json only
-   
-3. Return unified response
-```
-
-### 5.4 API Key Generation
-
-**Format:** `dew_{random_32_chars}`
-
-**Example:** `dew_k7j3m9q2n8p4r6s1t5v8w0x2y4z7a9c1`
-
-**Generation:**
-```php
-function generateApiKey() {
-    return 'dew_' . bin2hex(random_bytes(16));
-}
-```
-
-**Storage:** Hashed (bcrypt) or plain (with secure storage + HTTPS)
-
---
-
-## 6. Migration Strategy
-
-### Phase 1: Foundation (Week 1-2)
-**Backend:**
- [ ] Create database tables (users, user_api_keys, user_keywords, subscriptions)
- [ ] Build auth endpoints (register, login, logout)
- [ ] Build API key CRUD endpoints
- [ ] Build private keyword CRUD endpoints
- [ ] Implement referrer whitelisting logic
- [ ] Update search endpoint to blend private + public
-
-**Frontend (Website):**
- [ ] Build registration/login UI
- [ ] Build dashboard with tabs (Keywords, API Keys, Billing)
- [ ] Build keyword management table (CRUD interface)
- [ ] Build API key management UI
- [ ] Add upgrade CTAs for free users
-
-**Testing:**
- [ ] Test auth flow
- [ ] Test keyword CRUD
- [ ] Test search blending (private + public)
- [ ] Test referrer whitelisting
-
-### Phase 2: Extension Integration (Week 3)
-**Extension Update:**
- [ ] Add "Link Account" button in settings
- [ ] Build login popup (OAuth-style or simple form)
- [ ] Store API key in chrome.storage.sync
- [ ] Update search to send Authorization header when logged in
- [ ] Update UI to show "Signed in as {email}"
- [ ] Add logout button
- [ ] Add upgrade prompt on private keyword miss
-
-**Testing:**
- [ ] Test login flow from extension
- [ ] Test private keyword search from extension
- [ ] Test auto-insert with private keywords
- [ ] Test logout/revoke flow
-
-### Phase 3: Payment Integration (Week 4)
-**Stripe Setup:**
- [ ] Create Stripe products (Monthly, Annual, Lifetime)
- [ ] Build checkout flow (dewemoji.com/upgrade)
- [ ] Build webhook handler (subscription created/updated/canceled)
- [ ] Update subscriptions table on payment events
- [ ] Build billing dashboard (payment history, cancel)
-
-**Testing:**
- [ ] Test full upgrade flow (free → Personal)
- [ ] Test subscription renewal
- [ ] Test cancellation
- [ ] Test lifetime purchase
-
-### Phase 4: Deprecation of Gumroad (Optional)
- [ ] Add migration tool for existing Gumroad license holders
- [ ] Offer 1-click conversion: paste license key → create account → auto-upgrade to Personal
- [ ] Send email to existing users with migration instructions
- [ ] Set sunset date for Gumroad validation (e.g., 90 days)
-
---
-
-## 7. Changes Required to Current Site
-
-### Homepage (dewemoji.com)
-**Current:** General emoji search + copy  
-**Required Changes:**
- [ ] Add hero section: "Find emojis in *your* language. Add personal keywords like 'bekicot' → 🐌"
- [ ] Add CTA: "Search Free" + "Create Personal Library"
- [ ] Add feature comparison table (Free vs Personal)
- [ ] Update footer: Add "Pricing", "Dashboard", "API Docs"
-
-### Search Page
-**Current:** Public search only  
-**Required Changes:**
- [ ] No changes for non-logged users
- [ ] For logged Personal users: blend private keywords in results
- [ ] Add badge on results: "Your keyword" vs "Public keyword"
- [ ] Add "Edit keyword" quick action on personal results
-
-### Emoji Detail Page
-**Current:** Shows public keywords, metadata  
-**Required Changes:**
- [ ] Add "Add to my keywords" button (Personal users only)
- [ ] Quick add modal: "What do you call this? → [input] → Save"
- [ ] Show user's private keywords for this emoji (if any)
- [ ] Remove voting/public submission UI (deprecated)
-
-### New Pages to Build
-
-#### `/register`
- Email + password form
- "Continue with Google" (optional, future)
- Terms acceptance
- Auto-login after registration
-
-#### `/login`
- Email + password
- "Forgot password" link
- Redirect to dashboard after login
-
-#### `/dashboard`
-**Tabs:**
-1. **My Keywords** (default)
-   - Table: Emoji | Keywords | Language | Actions
-   - Add button → modal (search emoji → add keyword)
-   - Bulk import/export buttons
-   
-2. **API Keys**
-   - List of keys with names + last used
-   - Generate button → creates new key
-   - Copy button + revoke button per key
-   
-3. **Billing**
-   - Current plan badge
-   - Next billing date
-   - Payment history table
-   - Upgrade/downgrade/cancel buttons
-
-#### `/upgrade` or `/pricing`
- Feature comparison table (Free vs Personal)
- Pricing cards (Monthly $4.99 | Annual $49 | Lifetime $99)
- Stripe checkout integration
- FAQ section
-
---
-
-## 8. Marketing & Positioning
-
-### Target Audiences
-
-**Primary:**
-1. **Multilingual communicators** (Indonesian, Korean, Japanese, etc.)
-   - Problem: "Emoji pickers don't understand my language"
-   - Hook: "Search in bahasa Indonesia: 'bekicot' → 🐌"
-
-2. **Heavy messengers** (WhatsApp, Discord, Twitter power users)
-   - Problem: "I use emojis 50+ times/day, default pickers suck"
-   - Hook: "Auto-insert emojis anywhere, instantly"
-
-3. **Content creators & social media managers**
-   - Problem: "Need specific emojis fast, can't waste time scrolling"
-   - Hook: "Your custom emoji library, synced everywhere"
-
-**Secondary:**
-1. Developers needing semantic emoji API
-2. Writers using emojis in documentation
-3. Non-Latin language communities (Korean, Japanese, Russian)
-
-### Positioning Statements
-
-**For Indonesian users:**
-*"Dewemoji adalah library emoji pribadi yang ngerti bahasa lo—dari 'bekicot' sampe slang gaul, semua bisa jadi shortcut emoji lo."*
-
-**For global users:**
-*"Your personal emoji dictionary that speaks your language—sync your custom keywords across all your devices."*
-
-**For Chrome Web Store:**
-*"Emoji search that understands you. Add personal keywords like 'snail' or 'bekicot'—works anywhere, syncs everywhere."*
-
-### Growth Channels
-
-1. **Chrome Web Store**
-   - Current: Already live (https://chromewebstore.google.com/detail/dewemoji...)
-   - Action: Update description with Personal tier benefits
-   - Strategy: Drive reviews via in-extension prompt ("Enjoying Dewemoji? Rate us!")
-
-2. **Indonesian tech communities**
-   - Reddit: r/indonesia, r/indonesian
-   - Kaskus, Discord servers (DevID, IndieHackers Indonesia)
-   - Messaging: "Finally, emoji search yang ngerti bahasa kita"
-
-3. **Product Hunt launch**
-   - Position: "Personal emoji library with multilingual keyword search"
-   - Hook: "Stop scrolling through emoji pickers—search in your language"
-
-4. **Twitter/X shares**
-   - User screenshots: "Look, I can search 'bekicot' now!"
-   - Developer shares: "Semantic emoji API that understands Indonesian slang"
-
-5. **SEO (organic)**
-   - Target: "emoji search [language]", "emoji picker indonesia", "find emoji by keyword"
-   - Content: Blog posts on emoji localization, multilingual search
-
---
-
-## 9. Success Metrics
-
-### Growth Metrics
- **Extension installs/month:** Target 1,000 → 10,000 in 6 months
- **Website MAU:** Target 5,000 → 50,000 in 6 months
- **Free → Personal conversion:** Target 2-5% (industry standard)
-
-### Revenue Metrics
- **MRR (Monthly Recurring Revenue):** Target $500 → $5,000 in 6 months
- **Annual plan adoption:** Target 30% of paid users
- **Lifetime purchases:** Target 10% of paid users
-
-### Usage Metrics
- **Avg searches/user/day:** Track engagement depth
- **Private keywords created/user:** Measure feature adoption
- **API key active usage:** Track cross-device sync adoption
-
-### Quality Metrics
- **Extension rating:** Maintain >4.5 stars
- **User retention (30-day):** Target >40%
- **Churn rate:** Target <10%/month for Personal tier
-
---
-
-## 10. Risks & Mitigation
-
-### Risk 1: Low conversion (free → Personal)
-**Mitigation:**
- Make free tier extremely generous (unlimited searches, all features except private)
- Add in-context upgrade prompts ("Not found. Create this keyword in Personal?")
- Offer 7-day free trial on Personal tier
+### Upgrade triggers

-### Risk 2: API abuse (free tier bombing)
-**Mitigation:**
- Referrer whitelisting (already planned)
- Soft IP throttle (5000/hour)
- Monitor usage patterns; tighten if needed
+- Search miss prompts
+- Locked "Your Keywords" section for free users
+- Extension contextual prompts

-### Risk 3: Low awareness ("Who needs emoji search?")
-**Mitigation:**
- Target pain-aware users (multilingual, heavy messengers)
- Leverage Chrome Web Store (existing 237M Chrome users search "emoji")
- Create viral hooks (screenshot-worthy Indonesian keyword searches)
-
-### Risk 4: Payment processor issues (Indonesia)
-**Mitigation:**
- Start with Stripe (global, easiest)
- Add Midtrans/Xendit for local payment methods (bank transfer, e-wallet)
- Offer annual/lifetime for users without recurring billing access
+## Platform responsibilities

---
-
-## 11. Next Steps (Immediate Actions)
+### Website

-### Week 1: Backend Foundation
-1. Design & implement database schema
-2. Build auth system (register, login, JWT/session)
-3. Build API key generation/validation
-4. Build private keyword CRUD endpoints
-5. Update search endpoint to blend private + public
-
-### Week 2: Frontend Dashboard
-1. Build registration/login pages
-2. Build dashboard layout (tabs: Keywords, API Keys, Billing)
-3. Build keyword management table + CRUD UI
-4. Build API key management UI
-5. Add upgrade CTAs throughout free tier
-
-### Week 3: Extension Integration
-1. Add "Link Account" in extension settings
-2. Build login popup for extension
-3. Store API key securely (chrome.storage)
-4. Update search to send auth header when logged in
-5. Add upgrade prompt on private keyword miss
-
-### Week 4: Payment & Launch
-1. Set up Stripe products (Monthly, Annual, Lifetime)
-2. Build checkout flow + webhook handler
-3. Build billing dashboard
-4. Test full user journey (register → add keywords → login in extension → search)
-5. Soft launch to existing users + Indonesian tech communities
-
---
-
-## 12. Appendix: Key Decisions Made
-
-| Decision | Rationale |
-|----------|-----------|
-| **Private-only keywords (no public)** | Eliminates moderation costs, AI costs, legal risks, complexity |
-| **Free unlimited public search** | Drives viral growth; users fall in love before paywall |
-| **Auto-Insert free (not paid)** | Core viral hook; competitors lack this, users share screenshots |
-| **Tier renamed: Pro → Personal** | "Personal" clarifies it's private keywords, not business tools |
-| **Self-generated API keys** | Flexibility with any payment provider (Stripe, Paddle, local) |
-| **Referrer whitelisting for free** | Protects API from abuse without limiting real users |
-| **No search count limits** | Emoji tools die with limits; unlimited = frictionless growth |
-| **Payment: $4.99/mo or $49/yr** | Coffee price for individuals; low friction, high volume model |
-
---
-
-## 13. Questions for Future Consideration
-
-1. **Team libraries:** Should Personal tier allow shared keyword libraries (e.g., family/team)?
-2. **Mobile apps:** Native iOS/Android apps or continue web + extension focus?
-3. **API marketplace:** Offer public API access for developers (separate paid tier)?
-4. **Localization:** Add more default language packs (Korean, Japanese, Spanish)?
-5. **AI assistance:** "Suggest keywords for this emoji based on my usage patterns"?
-
---
-
-**End of Brief**
-
-This document serves as the north star for Dewemoji's development through 2026. All implementation decisions should align with the principle: **"Free discovery → Paid personalization"** and the vision of enabling personal, multilingual emoji expression for everyone.
+- discovery pages
+- emoji detail
+- pricing/upgrade
+- user dashboard (keywords, API keys, billing)
+
+### Extension
+
+- free discovery remains strong
+- account linking for personal sync
+- blend private + public results when authenticated
+
+### API
+
+- stable public contract for search/category/detail
+- authenticated personal keyword endpoints
+- clear throttling and abuse controls
+
+## Architecture priorities
+
+1. Move from license-centric model toward account + subscription + API keys.
+2. Keep legacy compatibility while migration is active.
+3. Preserve cache-first behavior (`app/data/emojis.json`) for reliable performance.
+4. Keep operational observability for billing/webhooks/usage.
+
+## Implementation phases
+
+### Phase A - Foundation
+
+- user auth foundations
+- private keyword model
+- API key lifecycle
+- public endpoint guard/throttle hardening
+
+### Phase B - Dashboard
+
+- my keywords CRUD
+- API key management
+- billing state view
+- role-aware dashboard shell
+
+### Phase C - Extension sync
+
+- link account
+- send auth key/header
+- show private result badges and edit actions
+
+### Phase D - Billing completion
+
+- provider webhooks with idempotency
+- accurate subscription status transitions
+- admin controls for pricing and subscription operations
+
+## Community/contribution decision
+
+Current active direction is **private-first personalization**.
+
+- Public community contribution/voting is not in the immediate build scope.
+- If reintroduced later, it should be optional, moderated, and separated from private keyword ownership.
+
+## Admin priorities
+
+1. subscription and payment visibility
+2. webhook replay and diagnostics
+3. pricing controls + change logging
+4. safety controls and audit logs
+
+## Success signals
+
+1. private keyword adoption per Personal user
+2. search success lift from private keywords
+3. free -> Personal conversion rate
+4. extension retention and sync reliability
+
+## Risks to monitor
+
+1. abuse on public endpoints -> enforce edge throttling + allowlists
+2. billing webhook drift -> queue + idempotency + replay tooling
+3. migration confusion between legacy licenses and Personal model -> explicit migration messaging
+
+## Out of scope for now
+
+- broad public community moderation/voting systems
+- heavy AI moderation pipelines for public contributions
+- major replatform that breaks current API contracts