# Kingly Vault

> Kingly Vault is an all-in-one learning + tooling platform for hustlers, solopreneurs, and creators who want to build automated income sources. It combines AI & n8n automation courses, a no-code builder suite (agents, forms, chatbots, linktrees), AI chat and image generation, a prompt library, gamified learning (XP, levels, challenges, leaderboard), and a community — all in one vault. Three tiers: Free, Starter ($7/mo), CEO ($47/mo). Billing is handled by Whop. Auth is handled by Clerk. Data is stored in Supabase.

Kingly Vault pairs structured **education** (courses, lessons, quizzes) with **execution tools** (agent vault, builders, AI chat, image generation) so a learner can go from "watched a lesson" to "shipped a working automation" without leaving the app. The brand voice is purple→pink gradient, glass-morphism HUD, sci-fi operator — the product positions itself as a "vault" or "forge" for ambitious builders rather than a passive course library.

## Product

- [Home](https://kinglyvault.com/): Landing + dashboard; public course catalog, feature overview, upgrade CTA.
- [Billing & Plans](https://kinglyvault.com/?view=billing): Current plan, Whop-hosted checkout, payment history, upgrade/downgrade.
- [Help Center](https://kinglyvault.com/?view=help): Docs, FAQs, support widget; Starter+ users can submit support tickets, CEO tier gets priority response.
- [Bug Tracker](https://kinglyvault.com/?view=bugs): Users report issues; admins triage severity and status.
- [Mentor Help](https://kinglyvault.com/?view=mentor): Submit a question to community mentors; asynchronous Q&A surface.

## Plans & Pricing

- **Free** ($0/mo): Browse all courses, take free courses, interactive walkthroughs, leaderboard + XP, task manager, basic AI chat (15 msgs/day), prompt library (read-only).
- **Starter** ($7/mo, Most Popular): Everything in Free **plus** all premium courses, image generation, image processing (upscale/enhance), agent vault browse, AI tools browse, prompt scorer, unlimited AI chat.
- **CEO** ($47/mo): Everything in Starter **plus** agent builder (publish to vault), form builder with webhooks, chatbot builder, linktree builder, website extractor, n8n prompt generator, unlimited image generation, priority support, beta feature access.

Subscriptions are processed by Whop (Standard Webhooks → Supabase edge function). On successful payment the user's `profiles.subscription_plan` is updated atomically via the `apply_subscription` RPC; a full-screen "Access Granted" modal celebrates the upgrade and the new feature set unlocks instantly without a reload. Downgrades and cancellations are managed inside the Whop customer portal.

## Learning

- [Courses](https://kinglyvault.com/?view=courses): Browse by category and difficulty; chapter + lesson structure with markdown content, embedded video, and per-lesson quizzes. Free courses open to all; premium courses require Starter.
- [AI Automation Masterclass](https://kinglyvault.com/?view=courses): Flagship onboarding course — n8n fundamentals, AI integrations, building your first automation pipeline.
- [Interactive Walkthroughs](https://kinglyvault.com/?view=courses): Guided product tours for new features (WalkthroughProvider-driven); separate from courses.
- [Blog](https://kinglyvault.com/?view=blogs): Articles on AI tooling, automation patterns, creator economy.

Course progress is tracked per-user; completing a lesson or passing a quiz awards XP, feeds the leaderboard, and counts toward daily/weekly challenges.

## AI Tools

- [AI Chat](https://kinglyvault.com/?view=ai-chat): Multi-mode chat powered by Gemini; chat modes are DB-driven (`chat_modes` table) with custom system prompts. Free tier is capped at 15 messages/day; Starter+ is unlimited. Session context window is capped at 20 messages per conversation.
- [Image Generator](https://kinglyvault.com/?view=image-generator): Text-to-image via Replicate edge-function proxy. Starter tier has a monthly quota; CEO tier is unlimited. Supports multiple models (incl. nano-banana variants).
- [Image Processing](https://kinglyvault.com/?view=image-processing): Upscale and enhance uploaded images. Starter+.
- [Prompt Library](https://kinglyvault.com/?view=prompt-library): Curated prompts with categories, tags, and images. Free tier can browse; paid tiers can save and remix.
- [Prompt Scorer](https://kinglyvault.com/?view=prompt-scorer): Rubric-based prompt quality evaluator that returns a score + suggested rewrites. Starter+.
- [AI Tools Marketplace](https://kinglyvault.com/?view=ai-tools): Catalog of vetted AI tools and integrations with deep-linked launch. Starter+.

## Builders (CEO Tier)

- [Agent Builder](https://kinglyvault.com/?view=agent-builder): Compose AI agents with system prompts, tools, and webhooks; publish to the agent vault so other users can clone them.
- [Agent Vault](https://kinglyvault.com/?view=agent-vault): Browse community-published agents (Starter+); only CEO tier can publish. Each agent has a description, use-case tag, and clone button.
- [Form Builder](https://kinglyvault.com/?view=form-builder): Drag-and-drop form builder with webhook delivery — wire submissions into n8n, Zapier, or any HTTP endpoint.
- [Chatbot Builder](https://kinglyvault.com/?view=chatbot-builder): Configure a branded chatbot (system prompt, welcome message, theme), get an embed snippet.
- [LinkTree Builder](https://kinglyvault.com/?view=linktree): Multi-link landing page with custom styling and analytics; alternative to linktr.ee.
- [Website Extractor](https://kinglyvault.com/?view=website-extractor): Scrape and structure content from a target URL — headings, copy, links, images — formatted for reuse in prompts or content pipelines.
- [N8N Prompt Generator](https://kinglyvault.com/?view=n8n-prompt-generator): Describe an automation in plain English; returns a ready-to-import n8n workflow JSON or a high-quality prompt for an n8n-aware LLM.

## Gamification

- [Leaderboard](https://kinglyvault.com/?view=leaderboard): Global XP-ranked user list with avatars and level badges.
- [Task Manager](https://kinglyvault.com/?view=task-manager): Personal to-do list; completing tasks awards XP.
- **XP & Levels**: Earned from daily login (with streak multiplier), lesson completion, quiz passes, and challenge completion. `GamificationProvider` emits a level-up modal on tier transitions.
- **Challenges**: Curated daily/weekly objectives (e.g. "complete 3 lessons", "publish an agent"); idempotent award RPCs prevent double-counting.
- **Upgrade Celebration**: Full-screen confetti modal with plan-specific copy on `free → starter`, `free → ceo`, or `starter → ceo` transitions, driven by entitlement change detection.

## Onboarding

- **Guest onboarding**: localStorage-gated intro flow before login (3 default slides).
- **Authed onboarding**: DB-backed (`onboarding_steps`, `onboarding_progress`) 5-step flow — welcome, profile capture (display name, business type, goals), first-course pick, community join, AI tools intro. Required steps are `welcome`, `profile`, `first_course`; the other two are optional.
- **Completion state**: Both `localStorage` and Supabase agree that onboarding is done, so dismiss-with-X doesn't re-prompt.

## Account & Billing Mechanics

- **Auth**: Clerk (email/password, OAuth). Clerk JWTs are verified against JWKS in edge functions that need user identity (e.g. `whop-checkout`).
- **Profiles**: `profiles` row per Clerk user ID (text); stores `subscription_plan`, `subscription_status`, `whop_membership_id`, `subscription_expires_at`, `role` (`admin` | null).
- **Checkout**: `whop-checkout` edge function creates a Whop `checkout_configurations` session with inline plan (title, price, billing period), passes the Clerk user ID in metadata, and returns a `purchase_url` for redirect.
- **Webhook**: `whop-webhook` edge function verifies Standard-Webhooks HMAC-SHA256 signatures (supports `whsec_`/`ws_` prefixes, multiple signatures, ±5 min skew), then dispatches on `payment.succeeded`, `payment.failed`, `membership.activated`, `membership.deactivated`, etc. Successful payments call the `apply_subscription` Postgres function (atomic, creates a shell profile if one doesn't exist) and upsert a `payments` row (deduped on `(provider, provider_payment_id)`). Failed payments write a `failed_payments` row and flip `subscription_status` to `past_due`. Recovery is auto-detected on the next success.
- **Feature gating**: `useEntitlements()` hook + `planHasFeature(plan, feature)` + `minimumPlanFor(feature)` gate UI and API surfaces; `UpgradeGate` component wraps premium components and renders a `PricingModal` when a gated feature is accessed.

## Community & Support

- **Mentor Questions**: Users post questions; mentors reply; answered Q&A is reusable knowledge base content.
- **Support Tickets**: Admin Support Manager panel for triage; SLA expectations vary by plan (priority on CEO tier).
- **Bug Tracker**: Structured bug reports (severity, repro, screenshots) with admin status workflow.
- **Discord**: 15,000+ member community invited during onboarding; not gated by plan.

## Admin Surface

Role-gated by `profiles.role = 'admin'`. Not publicly linked.

- **KPI Dashboard**: DAU/WAU/MAU, retention, funnel metrics (derived from `analytics_events`).
- **Revenue Dashboard**: MRR, churn, lifetime spend, recent payments (built on `kpi_revenue_summary` view).
- **User Manager**: Search, plan override, suspend, audit log of admin actions.
- **Course Manager**: CRUD courses, chapters, lessons, quizzes.
- **Chat Mode Manager**: Edit system prompts for AI chat modes without redeploying.
- **AI Tools Manager**: Publish/retire entries in the AI Tools catalog.
- **Bug Tracker Admin**: Triage and close reported issues.
- **Support Manager**: Assign and resolve tickets.

## Technical Stack

- **Frontend**: Vite + React + TypeScript, Tailwind CSS, Lucide icons, LiquidEther shader background, glass-morphism HUD design language.
- **Auth**: Clerk (React SDK + edge JWKS verify).
- **Backend**: Supabase (Postgres, RLS, edge functions in Deno).
- **Edge Functions**: `whop-checkout`, `whop-webhook`, `chat-modes`, `replicate-proxy`.
- **Payments**: Whop (Standard Webhooks, `checkout_configurations` API).
- **AI providers**: Gemini (chat), Replicate (image generation).
- **Analytics**: `analytics_events` table with attribution capture (UTM, referrer, feature tags) and admin-surfaced KPI summaries.
- **Error tracking**: custom `errorTrackingService` writes to `analytics_events`.
- **Hosting**: Netlify (SPA; `/*` → `/index.html` fallback; static files like `robots.txt`, `sitemap.xml`, `llms.txt` served directly from `/public`).

## Optional

- [Whop — Payments Partner](https://whop.com/): Subscription processing and customer portal.
- [Clerk — Auth Partner](https://clerk.com/): Identity, session management, OAuth.
- [Supabase — Backend](https://supabase.com/): Database, auth bridge, edge functions.