docs: rewrite README

README.md

@@ -1,209 +1,224 @@
----
-title: FlowState
-emoji: 🚀
-colorFrom: yellow
-colorTo: gray
-sdk: static
-pinned: false
+# FlowState
+
+> **The autonomous retention engine for Solana protocols.**
+> Detect wallet churn before it happens. Fire the right incentive at the right moment. Watch users come back.
+
+[![Built with Torque](https://img.shields.io/badge/Built%20with-Torque-FCD535?style=flat-square)](https://torque.so)
+[![Next.js](https://img.shields.io/badge/Next.js-14-black?style=flat-square)](https://nextjs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5-3178C6?style=flat-square)](https://typescriptlang.org)
+
 ---
 
-# FlowState — AI-Powered Anti-Churn Engine for Solana
+## The Problem
 
-> Autonomous retention layer for onchain protocols. Detects at-risk wallets in real time, fires live Torque campaigns, tracks every ingestion ID.
+DeFi protocols bleed users silently. A wallet goes quiet for 10 days — nobody notices. By day 30, they're gone. There's no CRM, no lifecycle email, no second chance. Just an address that stopped showing up.
 
-## Live Integration Proof
+**FlowState fixes this.**
 
-Real events fired and confirmed ACCEPTED by Torque ingest during development:
+---
+
+## How It Works
+
+FlowState watches wallet behavior across Solana in real time. When it detects a churn signal — inactivity, volume drop, streak broken — it scores the risk, picks the optimal Torque incentive, and fires it. Automatically.
 
 ```
-✓ b3f2a1c9  churn_risk_high    7xKp3...Bm9q  score=91  source=scan    ACCEPTED
-✓ 4e8d7f02  churn_risk_high    3nRt8...Wk2p  score=88  source=manual  ACCEPTED
-✓ 9a1c3b44  churn_risk_medium  5mQs1...Yx7r  score=67  source=scan    ACCEPTED
-✓ 7f4e2d81  streak_maintained  2pLv6...Nj4t  score=12  source=manual  ACCEPTED
-✓ 2b9a6c13  comeback_detected  8kHz9...Cs3u  score=34  source=scan    ACCEPTED
+MONITOR wallets  →  SCORE churn risk  →  DECIDE incentive  →  EXECUTE via Torque  →  TRACK recovery
 ```
 
-Events visible at [platform.torque.so](https://platform.torque.so)
+The AI engine runs a 5-signal model on every wallet:
+
+```typescript
+score += daysInactive >= 30 ? 40 : daysInactive >= 14 ? 25 : daysInactive >= 7 ? 15 : 0
+score += volumeDropPct >= 80 ? 30 : volumeDropPct >= 50 ? 20 : volumeDropPct >= 25 ? 10 : 0
+score += uniqueProtocols <= 1 ? 15 : uniqueProtocols <= 3 ? 8 : 0
+score += currentStreak === 0 ? 10 : 0
+score += hasLiquidation ? 5 : 0
+// critical ≥80  ·  high ≥60  ·  medium ≥40  ·  low ≥20  ·  safe <20
+```
+
+Score determines the response:
+
+| Risk | Action | Torque Primitive |
+|------|--------|-----------------|
+| Critical (≥80) | Send a gift — keep them | Gift / Bounty |
+| High (≥60) | Enter them in a raffle | Raffle |
+| Medium (≥40) | Activate a rebate | Rebate / Trial |
+| Returning | Welcome back reward | Comeback campaign |
+| Streak active | Reinforce the habit | Leaderboard |
 
 ---
 
-## What It Does
+## Live Proof — Real Events Fired
 
-FlowState monitors wallet activity across Solana, scores churn risk via a 5-signal AI model, and fires live Torque campaigns (gifts, raffles, rebates, leaderboards) to retain at-risk users.
+These are real ingestion IDs returned by `ingest.torque.so` during development. Not mocked.
 
 ```
-MONITOR → DETECT (AI score) → DECIDE (incentive) → EXECUTE (Torque) → TRACK (live events)
+✓ b3f2a1c9  churn_risk_high    7xKp3...Bm9q  score=91  ACCEPTED
+✓ 4e8d7f02  churn_risk_high    3nRt8...Wk2p  score=88  ACCEPTED
+✓ 9a1c3b44  churn_risk_medium  5mQs1...Yx7r  score=67  ACCEPTED
+✓ 7f4e2d81  streak_maintained  2pLv6...Nj4t  score=12  ACCEPTED
+✓ 2b9a6c13  comeback_detected  8kHz9...Cs3u  score=34  ACCEPTED
 ```
 
+All 7 custom event schemas are live on Torque. Campaign and project created. Events verified on [platform.torque.so](https://platform.torque.so).
+
 ---
 
-## Torque Primitives Used
+## Torque Integration
+
+All 4 primitives wired to real trigger events:
 
-| Primitive | Campaign | Trigger |
-|-----------|----------|---------|
-| Leaderboard | Weekly Volume Champions — `SUM(swap_volume)` | `volume_milestone` |
-| Raffle | Comeback Raffle — streak multiplier entry | `comeback_detected` |
-| Gift / Bounty | Anti-Churn Gift Drop — critical-risk wallets | `churn_risk_high` |
-| Rebate / Trial | Streak Multiplier — 7+ day active users | `streak_maintained` |
+| Primitive | Campaign | Trigger Event |
+|-----------|----------|--------------|
+| **Leaderboard** | Weekly Volume Champions — `SUM(swap_volume)` | `volume_milestone` |
+| **Raffle** | Comeback Raffle — streak multiplier entry | `comeback_detected` |
+| **Gift / Bounty** | Anti-Churn Gift Drop — score ≥80 wallets | `churn_risk_high` |
+| **Rebate / Trial** | Streak Multiplier — 7+ day active users | `streak_maintained` |
 
-### 7 Custom Event Schemas (live on Torque)
+**7 custom event schemas registered on Torque:**
 
 ```
-churn_risk_high       critical/high risk — score ≥80, inactive ≥14d
-churn_risk_medium     medium risk — rebate activation trigger
+churn_risk_high       score ≥80, inactive ≥14d — triggers gift campaign
+churn_risk_medium     score ≥40 — triggers rebate activation
 comeback_detected     wallet returns after 7+ days silence
 streak_maintained     7+ consecutive active days
-volume_milestone      wallet crosses $10K / $50K / $100K lifetime
-inactivity_detected   wallet goes quiet — soft nudge trigger
-referral_from_saved   a retained wallet referred a new user
+volume_milestone      crosses $10K / $50K / $100K lifetime volume
+inactivity_detected   wallet goes quiet — soft nudge
+referral_from_saved   retained wallet refers a new user
 ```
 
 ---
 
-## Novel Features
+## Features
 
-### Auto-Scan Mode
-Toggle on the Dashboard fires real Torque events every 30 seconds autonomously. Countdown timer shows next scan. One click activates fully autonomous retention.
+### Autonomous Scan Engine
+Hit **Scan Now** or enable **Auto Mode** — FlowState scores every wallet and fires Torque events for at-risk users without any manual input. Auto mode runs every 30 seconds with a live countdown.
 
 ### Bulk Rescue
-"Rescue All Critical" button on the Wallets page fires `churn_risk_high` events for every at-risk wallet in a single parallel batch call (`POST /api/torque/bulk-fire`). Progress counter updates live: `3/7 fired`.
+One button fires `churn_risk_high` for every critical wallet in parallel. Live progress counter: `3/7 fired`. Ingestion IDs appear inline next to each wallet address as confirmation.
 
-### Toast Notification System
-Every Torque event that fires — whether from Scan Now, per-wallet Intervene, or Bulk Rescue — triggers a toast in the bottom-right corner showing event name, wallet address, and first 10 chars of the ingestion ID. Visual proof of live activity.
+### Toast Notifications
+Every event that hits Torque surfaces as a bottom-right toast: event name, wallet address, first 10 chars of the ingestion ID. Visual proof, not just logs.
 
-### Keyboard Shortcut
-Press `S` anywhere on the Dashboard to trigger a wallet scan. No mouse needed.
+### Per-Wallet Intervention
+Filter wallets by risk tier. Each critical/high/medium row has a contextual action button — Send Gift, Enter Raffle, Activate Rebate — that fires directly to Torque ingest and shows the returned ingestion ID.
 
-### Real-Time Status in Topbar + Sidebar
-Topbar polls `/api/torque/status` every 8s — shows "TORQUE LIVE" (green pulse) or "TORQUE OFFLINE" (red). Sidebar shows live session event count from the in-memory event store, refreshing every 5s.
+### Live Event Feed
+The dashboard AI Agent Feed injects real Torque events at the top with a LIVE badge and green border as they arrive, alongside ambient mock activity showing system scale.
 
-### Per-Wallet Intervene Buttons
-Each at-risk wallet row has a contextual action button:
-- Critical → "Send Gift" → `churn_risk_high`
-- High → "Enter Raffle" → `churn_risk_high`
-- Medium → "Activate Rebate" → `churn_risk_medium`
-
-Fires to real Torque ingest, shows ingestion ID inline.
+### Real-Time Status
+Topbar shows **TORQUE LIVE** (green pulse) or **TORQUE OFFLINE** based on actual credential check, polling every 8s. Sidebar shows live session event count refreshing every 5s.
 
 ### Create Campaign Modal
-Full campaign creation form wired to `POST /api/torque/campaigns`: choose type (Leaderboard / Raffle / Gift / Rebate), name, budget, trigger event. Shows campaign ID on success.
+Full campaign creation form — type, name, description, budget, trigger event — wired to `POST /api/torque/campaigns`. Returns campaign ID on success.
 
-### In-Memory Event Store
-Session-wide singleton tracking every ingestion ID returned by Torque. Feeds the live events strip on the dashboard, the sidebar counter, and the topbar event badge. No database needed — restarts clean.
+### Keyboard Shortcut
+Press `S` on the Dashboard to trigger a scan instantly.
 
 ---
 
 ## Architecture
 
 ```
-┌─────────────────────────────────────────────────────────┐
-│                     FlowState UI                        │
-│  Dashboard · Wallets · Campaigns · Analytics · Agent    │
-│                                                         │
-│  Auto-scan (30s) · Bulk Rescue · Toast Notifications    │
-└──────────────┬──────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────┐
+│                    FlowState UI                      │
+│  Dashboard · Wallets · Campaigns · Analytics · Agent │
+│  Auto-scan · Bulk Rescue · Toast · Keyboard shortcut │
+└──────────────┬───────────────────────────────────────┘
                �� Next.js API Routes
-     ┌─────────┴───────────┐
-     │                     │
-┌────▼──────┐    ┌─────────▼────────┐
-│ AI Engine │    │  Event Store     │
-│ 5-signal  │    │  in-memory,      │
-│ churn     │    │  session-wide    │
-│ scoring   │    │  tracks IDs      │
-└────┬──────┘    └─────────┬────────┘
-     └─────────┬───────────┘
+     ┌─────────┴──────────┐
+     │                    │
+┌────▼──────┐   ┌─────────▼───────┐
+│ AI Engine │   │   Event Store   │
+│ 5-signal  │   │  in-memory      │
+│ churn     │   │  tracks IDs     │
+│ scoring   │   │  session-wide   │
+└────┬──────┘   └─────────┬───────┘
+     └─────────┬──────────┘
                │
-     ┌─────────▼────────────┐
-     │    torque-mcp.ts     │
-     │                      │
-     │  ingest.torque.so    │  ← x-api-key (tq_ key)
-     │  server.torque.so    │  ← Authorization: Bearer JWT
-     └──────────────────────┘
-```
-
-### Churn Scoring Model (5 signals)
-
-```typescript
-score += daysInactive >= 30 ? 40 : daysInactive >= 14 ? 25 : daysInactive >= 7 ? 15 : 0
-score += volumeDropPct >= 80 ? 30 : volumeDropPct >= 50 ? 20 : volumeDropPct >= 25 ? 10 : 0
-score += uniqueProtocols <= 1 ? 15 : uniqueProtocols <= 3 ? 8 : 0
-score += currentStreak === 0 ? 10 : 0
-score += hasLiquidation ? 5 : 0
-// critical ≥80  high ≥60  medium ≥40  low ≥20  safe <20
+     ┌─────────▼──────────────┐
+     │     torque-mcp.ts      │
+     │                        │
+     │  ingest.torque.so      │  ← x-api-key: tq_...
+     │  server.torque.so      │  ← Authorization: Bearer JWT
+     └────────────────────────┘
 ```
 
 ---
 
 ## Pages
 
-| Page | Features |
-|------|---------|
-| Dashboard | Live events strip, Scan Now, auto-scan toggle (30s), real Torque status badge, toast on fire |
-| Wallets | Per-wallet Intervene buttons, Bulk Rescue All Critical, ingestion ID inline confirmation |
-| Campaigns | Campaign cards + Create Campaign modal → real `POST /api/torque/campaigns` |
-| Leaderboard | Top-3 podium, sortable rankings, scoring formula display |
-| Analytics | Retention cohort heatmap, custom event breakdown, KPI charts |
-| AI Agent | Start/pause, live feed with real scan results, threshold config |
+| Page | What's There |
+|------|-------------|
+| **Dashboard** | Live events strip, Scan Now + Auto Mode, Torque status badge, agent feed with real LIVE entries |
+| **Wallets** | Risk table, per-wallet Intervene buttons, Bulk Rescue All Critical, inline ingestion ID confirmation |
+| **Campaigns** | Campaign cards + Create Campaign modal → real Torque API |
+| **Leaderboard** | Top-3 podium, sortable rankings, scoring formula |
+| **Analytics** | Retention cohort heatmap, custom event breakdown, KPI charts |
+| **AI Agent** | Start/pause, live feed with real scan results, detection thresholds |
 
 ---
 
 ## Run Locally
 
 ```bash
-git clone https://github.com/YOUR_USERNAME/flowstate
-cd flowstate && npm install
-
+git clone https://github.com/MUTHUKUMARAN-K-1/flowstate
+cd flowstate
+npm install
 cp .env.example .env.local
-# Add both credentials (see below)
+# fill in your two Torque credentials
 npm run dev
 ```
 
-Get credentials at [platform.torque.so/settings](https://platform.torque.so/settings)
+### Two Credentials — Both Required
 
-### Two Credentials Required
+Torque uses separate credentials for its REST API and event ingest. Get both from [platform.torque.so](https://platform.torque.so):
 
-| Variable | Format | Endpoint |
+| Variable | Format | Used for |
 |----------|--------|---------|
-| `TORQUE_API_KEY` | `eyJ...` JWT | `server.torque.so` (REST API) |
-| `TORQUE_INGEST_KEY` | `tq_...` | `ingest.torque.so` (event ingest) |
+| `TORQUE_API_KEY` | `eyJ...` JWT | `server.torque.so` — campaign creation, leaderboards |
+| `TORQUE_INGEST_KEY` | `tq_...` | `ingest.torque.so` — firing custom events |
 
 ---
 
-## Tech Stack
+## Stack
 
-Next.js 14 · TypeScript · Tailwind CSS · Recharts · Lucide · Torque MCP
+**Next.js 14** · **TypeScript** · **Tailwind CSS** · **Recharts** · **Lucide** · **Torque MCP**
 
 ---
 
 ## Friction Log
 
-### What Worked Well
-- Custom events are the superpower — any signal maps to any campaign type instantly
-- Four primitives cover every DeFi retention play — nothing missing
-- Formula engine is perfect for `SUM(swap_volume)` leaderboards
-- Ingest endpoint is fast — all 10 test events confirmed in under 2s
-- MCP server makes campaign creation scriptable from any LLM
+Honest account of what we hit building this. Torque's primitives are genuinely powerful — these are sharp edges worth filing down.
+
+### What Worked
+
+- **Custom events are the superpower.** Any signal → any campaign type. The mapping is clean and expressive.
+- **Four primitives cover every DeFi retention play.** Nothing missing for the gift/raffle/rebate/leaderboard loop.
+- **Formula engine is perfect for leaderboards.** `SUM(swap_volume)` just works.
+- **Ingest endpoint is fast.** 10 test events all returned ACCEPTED in under 2 seconds.
+- **MCP server makes campaign creation scriptable.** Great fit for AI agents.
 
 ### What Could Be Better
 
 **1. Two credentials, no joint setup docs**
-JWT and `tq_` ingest key serve different endpoints and are obtained separately. Discovered by testing, not documentation. A single "Setup" page listing both with which endpoint uses which would save 30+ min for every builder.
+JWT and `tq_` ingest key serve different endpoints, obtained in different places. Discovered by testing, not docs. One unified setup guide listing both would save builders 30+ minutes.
 
-**2. Custom event schema must be pre-created before ingest**
-Events silently drop if the schema hasn't been registered via MCP first. No error message explains why. A `422 Unprocessable: event schema not found` response would surface this immediately.
+**2. Custom event schema required before ingest — silent failure**
+Events silently drop if the schema isn't pre-registered via MCP. No error message. A `422 Unprocessable: event schema not found` response would surface this in seconds instead of hours.
 
-**3. No batch ingest endpoint**
-Scanning 10,000 wallets = 10,000 sequential HTTP calls. A `POST /events/batch` accepting an array is critical for any production-scale retention use case.
+**3. No batch ingest**
+Scanning 10,000 wallets = 10,000 HTTP calls. A `POST /events/batch` taking an array is table stakes for production retention at scale.
 
 **4. Campaign creation API undocumented**
-`POST server.torque.so/campaigns` exists but has no public schema. Had to infer parameter names from MCP tool signatures. A REST reference page would unblock builders.
+`POST server.torque.so/campaigns` works but has no public schema. Had to infer fields from MCP tool signatures. A REST reference would unblock builders immediately.
 
-**5. MCP auth is stateful with no built-in retry**
-Must call `auth()` before any other MCP tool. No automatic re-auth on token expiry. A token refresh mechanism or clearer expiry handling would prevent silent failures.
+**5. MCP auth is stateful, no auto-retry**
+Must call `auth()` before anything else. No automatic re-auth on token expiry. Silent failures until you realize the token is stale.
 
-**6. No webhook callbacks on campaign events**
-No way to know when a raffle winner is drawn or a gift is claimed without polling. Webhooks would enable real closed-loop retention (detect churn → fire event → get callback when reward claimed → record recovery).
+**6. No webhook callbacks**
+No way to know when a raffle is drawn or a gift is claimed without polling. Webhooks would close the loop: detect churn → fire event → get callback when reward is claimed → mark user recovered.
 
 ---
 
-Built for the Torque Hackathon · [platform.torque.so](https://platform.torque.so)
+*Built for the Torque Hackathon · [torque.so](https://torque.so) · [platform.torque.so](https://platform.torque.so)*