vibefast-cli 0.2.4 → 0.3.1

package/2/vf-agent/data/knowledge_base/starter-docs/image-generator-reference.md

@@ -0,0 +1,110 @@
+# Image Generator Reference
+
+> Frontend paths reference the Expo workspace (`apps/native/src/...`); backend paths reference `packages/backend/convex/...`.
+
+## Overview
+
+The Image Generator feature enables users to create images from textual prompts using AI models like OpenAI's DALL-E. The entire process, from handling user input to calling the AI service and storing the result, is managed through a clean, hook-based frontend and a secure Convex action on the backend.
+
+### Core Technologies
+
+- **[Vercel AI SDK](https://sdk.vercel.ai):** The `experimental_generateImage` function from the AI SDK is used on the backend to interact with image generation models in a standardized way.
+- **[Convex Actions](https://docs.convex.dev/functions/actions):** A public Convex `action` (`generateImageAction`) serves as the secure server-side endpoint that the client calls. This is crucial because it prevents exposing API keys to the client.
+- **[Convex File Storage](https://docs.convex.dev/file-storage):** After an image is generated, it is automatically uploaded to Convex File Storage for persistence.
+- **[React Hook Form](https://react-hook-form.com/) & [Zod](https://zod.dev):** Used on the frontend for robust form state management and validation.
+
+## Getting Started
+
+The feature is ready to use once you provide the necessary API keys in your environment variables.
+
+### Environment Variables
+
+To enable image generation, you must add your OpenAI API key to your `.env.local` file:
+
+```bash
+# For OpenAI Image Generation
+OPENAI_API_KEY="sk-..."
+```
+
+### Image Generation Flow
+
+1.  **User Input:** The user enters a prompt and selects a provider and model using the `ImageGeneratorForm`.
+2.  **Form Submission:** The `useImageGenerator` hook is called on form submission. It takes the form data and calls the `generateImageAction` Convex action.
+3.  **Backend Action (`generateImageAction`):**
+    - The action authenticates the user.
+    - It calls the Vercel AI SDK's `generateImage` function, passing the prompt and model details.
+    - The AI service returns the generated image as a buffer or base64 string.
+    - The action converts this into a data URI (`data:image/png;base64,...`) and returns it to the client.
+4.  **Display Image:** The `useImageGenerator` hook receives the data URI and updates its state, causing the `GeneratedImageDisplay` component to render the new image.
+5.  **Automatic Storage:**
+    - After the image is successfully received, the `useImageGenerator` hook calls the `useImageStorage` hook's `saveImage` function.
+    - `saveImage` fetches the image data from the data URI, converts it to a `Blob`, and uploads it to Convex File Storage using the `useUploadFile` hook.
+    - Finally, it calls the `saveImageRecord` internal mutation to save the prompt and the new `storageId` to the `generatedImages` database table.
+
+## Key Components & Hooks
+
+### Core Components
+
+- `ImageGeneratorLayout`: Provides the main screen structure.
+- `ImageGeneratorForm`: The central component that composes the form inputs and submission button.
+- `GeneratedImageDisplay`: A dedicated component to display the generated image, or loading/error states.
+- `ImagePromptInput`, `ProviderSelector`, `ModelSelector`: Reusable and validated form input components.
+
+### Core Hooks
+
+- `useImageGenerator`: The primary hook for the feature. It orchestrates the entire process: calling the generation action, handling loading/error states, and triggering the subsequent storage.
+- `useImageStorage`: A specialized hook responsible for uploading the generated image to Convex File Storage and saving its metadata to the database.
+- `useUploadFile` (from `@convex-dev/react-file-storage`): A low-level hook used by `useImageStorage` to handle the actual file upload.
+
+## How-To Guides
+
+### 1. Add a New Model (e.g., DALL-E 2)
+
+1.  **Update Frontend Component:** In `apps/native/src/features/image-generator/components/model-selector.tsx`, add the new model to the `models` object under the correct provider.
+
+    ```tsx
+    const models = {
+      openai: [
+        { value: 'dall-e-3', label: 'DALL-E 3' },
+        { value: 'dall-e-2', label: 'DALL-E 2' }, // Add new model
+      ],
+      // ...
+    };
+    ```
+
+2.  **Verify Backend Support:** Ensure the model name (`dall-e-2`) is accepted by the AI provider's API. The backend code in `generateImageAction` already passes the `model` string dynamically, so no backend changes are needed if the provider supports it.
+
+### 2. Add a New Provider (e.g., Stability AI)
+
+Adding a new provider is more involved.
+
+1.  **Install SDK:** Add the provider's official AI SDK (e.g., `@ai-sdk/stability`).
+2.  **Create Provider Instance:** In `packages/backend/convex/imageGeneratorFunctions.ts`, create an instance of the new provider, similar to `createOpenAI`.
+3.  **Update Action Logic:** Add a new `else if (provider === 'stability')` block inside the `generateImageAction`. This block will call the new provider's `generateImage` function.
+4.  **Update Frontend:**
+    - Add the new provider to the `ProviderSelector` component.
+    - Add the provider's models to the `ModelSelector` component.
+    - Update the `ImageGeneratorSchema` in `utils/generator-schemas.ts` to include the new provider in the enum.
+
+### 3. Change Image Size or Quality
+
+You can adjust the parameters sent to the AI model in the backend action.
+
+- Navigate to `packages/backend/convex/imageGeneratorFunctions.ts`.
+- In the `generateImageAction` handler, find the `generateImage` call.
+- Modify the parameters. For example, to change the size for DALL-E 3:
+
+  ```ts
+  const { image } = await generateImage({
+    model: openaiProvider.image(model),
+    size: '1792x1024', // Change size here
+    quality: 'hd', // Add quality parameter
+    prompt,
+  });
+  ```
+
+## Backend (Convex)
+
+- **`packages/backend/convex/imageGeneratorFunctions.ts`:** This file contains all the backend logic.
+  - `generateImageAction` (action): The public, secure endpoint that the frontend calls. It contains the logic for interacting with the AI SDK and is the main place to add or modify providers.
+  - `saveImageRecord` (internalMutation): A secure mutation for internal use only. It's called by the `useImageStorage` hook (via the `saveImage` function which runs on the client but calls this mutation) to write the final record to the database after the image has been uploaded to file storage. This two-step process (generate -> upload -> save record) is robust and ensures no orphaned files.

package/2/vf-agent/data/knowledge_base/starter-docs/index.md

@@ -0,0 +1,28 @@
+# VibeFast Starter Kit Documentation
+
+## Overview
+
+This section contains all architectural and feature-reference documents for the VibeFast starter kit. These documents provide a deep dive into the technical design, patterns, and decisions that govern the codebase. They are the primary source of truth for all planning and development. Paths reference the monorepo layout (`apps/native` for the Expo app, `packages/backend` for Convex, shared packages under `packages/*`).
+
+## 1. Core Architecture & Principles
+
+- **[Product Requirements (`prd.md`)]**: The functional and non-functional requirements of the starter kit itself.
+- **[Technology Stack (`tech-stack.md`)]**: The definitive list of all technologies, frameworks, and services used.
+- **[Unified Project Structure (`unified-project-structure.md`)]**: A complete guide to the project's file and folder organization.
+
+## 2. Features
+
+- **[Features Overview (`features-overview.md`)]**: A high-level summary of all pre-built features and their capabilities.
+- **[Feature Reference Index (`feature-reference-index.md`)]**: A quick-access index to the detailed documentation for every feature.
+
+## 3. Detailed Feature Documentation
+
+_For detailed implementation guides, see the specific files listed in the **[Feature Reference Index](./feature-reference-index.md)**._
+
+- **[Authentication](./authentication-reference.md)**
+- **[AI Chatbot](./chatbot-reference.md)**
+- **[AI Image Generator](./image-generator-reference.md)**
+- **[AI Image Analyzer](./image-analyzer-reference.md)**
+- **[Payments & Subscriptions](./payments-reference.md)**
+- **[Push Notifications](./push-notifications-reference.md)**
+- **[And many more...](./feature-reference-index.md)**

package/2/vf-agent/data/knowledge_base/starter-docs/onboarding-reference.md

@@ -0,0 +1,96 @@
+# Onboarding Feature Reference
+
+> Frontend paths reference the Expo workspace (`apps/native/src/...`).
+
+## Overview
+
+The Onboarding feature is a comprehensive, data-driven system designed to guide new users through the app. It is built around a reusable, swipeable UI component and includes a powerful, underlying analytics service to track user engagement and flow performance.
+
+### Core Components
+
+1.  **Reusable `Onboarding` Component:** A swipeable, horizontal `FlatList` that displays a series of screens. It is highly configurable and uses Lottie for rich animations.
+2.  **Analytics Service:** A dedicated service (`OnboardingAnalyticsService`) and React hook (`useOnboardingAnalytics`) to track user progress through any defined onboarding flow. This allows for detailed analysis of user drop-off points, completion rates, and A/B testing of different flows.
+3.  **Flow Configuration:** Onboarding flows are not hardcoded. They are defined in a central configuration file (`onboarding-flow-config.ts`), allowing developers to easily create, modify, or A/B test different onboarding experiences without changing UI code.
+
+### Core Technologies
+
+- **[React Native FlatList](https://reactnative.dev/docs/flatlist):** Used in `horizontal` and `pagingEnabled` mode to create the swipeable screen interface.
+- **[Lottie](https://lottiefiles.com/):** Used to render high-quality, lightweight animations on each onboarding screen.
+- **[Reanimated 2](https://docs.swmansion.com/react-native-reanimated/):** Used for smooth, performant animations, particularly for the scrolling pagination dots.
+- **[PostHog (Conceptual)](https://posthog.com/):** The analytics service is built to connect to a provider like PostHog via an adapter (`usePostHogAnalyticsAdapter`), allowing for powerful, event-based analytics.
+
+## Getting Started
+
+The main onboarding flow is defined in `apps/native/src/features/onboarding/demo-one/`. It is triggered for first-time users via the `useIsFirstTime` hook.
+
+### Onboarding Flow
+
+1.  **First-Time Check:** The app uses a hook like `useIsFirstTime` to determine if the user is opening the app for the first time.
+2.  **Render Onboarding:** If it is the user's first time, the `DemoOneOnboarding` screen is rendered.
+3.  **Component Display:** This screen uses the main `Onboarding` component, passing it the specific data for the main app onboarding flow (`AppOnboardingData`).
+4.  **User Interaction:** The user swipes through the screens or uses the "Next" button.
+5.  **Completion:** When the user presses "Get Started" on the final screen, the `onComplete` handler is called.
+6.  **Mark as Complete:** The `onComplete` handler calls `completeOnboarding()` from the `useIsFirstTime` hook, which persistently flags that the user has completed onboarding.
+7.  **Navigation:** The user is then navigated to the main part of the app (e.g., the login screen).
+
+## Analytics
+
+The analytics system is a key part of this feature. It is designed to be flexible and powerful.
+
+- **`OnboardingAnalyticsService`:** A class that encapsulates all tracking logic. It manages the session, calculates durations, and sends events to the analytics provider.
+- **`useOnboardingAnalytics`:** A React hook that provides a clean interface to the analytics service within your components.
+- **`OnboardingWithAnalytics`:** An enhanced component that automatically wraps the standard `Onboarding` component with analytics tracking, making it easy to monitor a flow's performance.
+- **Flow Configuration (`onboarding-flow-config.ts`):** This is where you define the steps for any given onboarding flow. The analytics service uses this configuration to know what steps to track.
+
+## How-To Guides
+
+### 1. Modify the Main Onboarding Flow
+
+To change the screens in the default onboarding flow:
+
+1.  **Edit Data File:** Open `apps/native/src/features/onboarding/demo-one/data.ts`.
+2.  **Add, Remove, or Edit Items:** Modify the `AppOnboardingData` array. Each object in the array represents one screen.
+    - To change text, edit the `title` and `description` properties.
+    - To change the animation, replace the `lottieAnim` value with a new `require()` call to a different Lottie JSON file in `assets/lottie-animations/`.
+
+### 2. Create a New Onboarding Flow (e.g., for a new feature)
+
+1.  **Define the Flow:** In `apps/native/src/features/onboarding/config/onboarding-flow-config.ts`, create a new configuration object for your flow.
+
+    ```ts
+    export const NEW_FEATURE_FLOW: OnboardingFlowConfig = {
+      flowId: 'new_feature_flow',
+      flowName: 'Onboarding for our cool new feature',
+      version: '1.0',
+      steps: [
+        { id: 'step_1', name: 'Explain Feature X', index: 0 },
+        { id: 'step_2', name: 'Show how to use it', index: 1 },
+      ],
+    };
+    ```
+
+2.  **Create the Data:** Create a new data array similar to `AppOnboardingData` with the titles, descriptions, and animations for your new flow.
+3.  **Create a Component:** Create a new component that uses the `Onboarding` UI component and passes your new data to it. You can also wrap it with `OnboardingWithAnalytics` to track its performance.
+
+### 3. A/B Test an Onboarding Flow
+
+The analytics configuration is already set up to support A/B testing.
+
+1.  **Define a Variant:** In `onboarding-flow-config.ts`, create a variant of an existing flow. Give it a new `flowId` and add or change steps.
+
+    ```ts
+    export const ONBOARDING_VARIANTS = {
+      // ... existing variants
+      demoOneExperimental: {
+        ...DEMO_ONE_ONBOARDING_FLOW,
+        flowId: 'demo_one_flow_experimental',
+        variant: 'experimental',
+        steps: [
+          // Add, remove, or reorder steps for the test
+        ],
+      },
+    };
+    ```
+
+2.  **Implement Logic:** In your app, implement logic to decide which users see which variant (e.g., using a remote config service like Firebase Remote Config, or a simple randomizer).
+3.  **Track in Analytics:** The `variant` property will be automatically tracked in all analytics events, allowing you to compare the performance of the `control` and `experimental` flows in your analytics platform (e.g., PostHog).

package/2/vf-agent/data/knowledge_base/starter-docs/payments-reference.md

@@ -0,0 +1,148 @@
+# Payments & In-App Purchases Reference
+
+> Frontend paths reference the Expo workspace (`apps/native/src/...`); backend paths reference `packages/backend/convex/...`.
+
+## Overview
+
+The VibeFast starter kit includes a mock implementation for in-app purchases (IAP), designed to be easily integrated with a real payment provider like [RevenueCat](https://www.revenuecat.com/). The system is set up to handle consumable products (e.g., credits) and display subscription options.
+
+### Core Technologies
+
+- **[RevenueCat (Conceptual)](https://www.revenuecat.com/):** The frontend hooks and services are structured to wrap a provider like RevenueCat. The `react-native-purchases` package is included in the service file, but the logic is currently mocked.
+- **[Convex Mutations & Queries](https://convex.dev):** The backend consists of Convex functions to securely record purchases made on the client and to query user credit balances and history.
+- **[React Native Modal](https://reactnative.dev/docs/modal):** Used to present the payment screen to the user in a non-intrusive way.
+
+## Getting Started
+
+The feature is currently a mock. To make it fully functional, you will need to:
+
+1.  **Sign up for RevenueCat:** Create an account and configure your app, products, and entitlements in the RevenueCat dashboard.
+2.  **Provide API Keys:** Add your RevenueCat public API keys to the `payment-service.ts` file.
+3.  **Un-mock the `usePayments` hook:** Replace the mock purchase logic with actual calls to the `react-native-purchases` SDK.
+
+### Environment & Configuration
+
+Update the API keys in `apps/native/src/features/payments/services/payment-service.ts`:
+
+```ts
+// apps/native/src/features/payments/services/payment-service.ts
+const API_KEYS = {
+  apple: 'your_revenuecat_apple_api_key',
+  google: 'your_revenuecat_google_api_key',
+};
+```
+
+### Payments Flow (Conceptual)
+
+1.  **User Action:** The user opens the `PaymentModal` to buy more credits.
+2.  **Initiate Purchase:** The `usePayments` hook's `purchaseProduct` function is called. **(This is the part you need to implement).**
+3.  **Provider Interaction:** The `paymentService` would call `Purchases.purchasePackage()` from the RevenueCat SDK.
+4.  **Verification:** The RevenueCat SDK handles the platform-specific (App Store / Play Store) purchase flow and verification.
+5.  **Record in Convex:** Upon successful purchase verification from RevenueCat, the `purchaseProduct` hook then calls the `recordConsumablePurchase` Convex mutation.
+6.  **Backend Mutation (`recordConsumablePurchase`):**
+    - Authenticates the user.
+    - Validates the purchase details.
+    - Increments the `credits` field on the user's document.
+    - Creates a new document in the `purchases` table to log the transaction.
+7.  **UI Update:** The `useUserCredits` hook automatically fetches the new credit balance, and the UI updates to reflect the purchase.
+
+## Key Components & Hooks
+
+### Core Components
+
+- `PaymentModal`: A modal screen that displays available products for purchase.
+- `ProductCard`: A component for displaying a single consumable product (e.g., a credit pack).
+- `SubscriptionCard`: A component for displaying a subscription tier.
+- `CreditBalance`: A small component, often placed in the app header, that displays the user's current credit total.
+- `PurchaseHistoryList`: A screen that lists all past transactions for the current user.
+
+### Core Hooks
+
+- `usePayments`: The primary hook for handling purchase logic. **This is currently mocked.** It's responsible for initiating the purchase with the payment provider and recording the transaction in Convex.
+- `useUserCredits`: A simple hook that provides a real-time query of the current user's credit balance.
+
+## How-To Guides
+
+### 1. Implement Real Purchases with RevenueCat
+
+The most critical step is to replace the mock logic in `usePayments`.
+
+**File to Edit:** `apps/native/src/features/payments/hooks/use-payments.ts`
+
+```ts
+// apps/native/src/features/payments/hooks/use-payments.ts
+
+// ... imports
+import { paymentService } from '../services/payment-service';
+
+export function usePayments() {
+  const [isPurchasing, setIsPurchasing] = useState(false);
+  const recordPurchase = useMutation(
+    api.paymentFunctions.recordConsumablePurchase,
+  );
+
+  const purchaseProduct = async ({ productId, quantity }: PurchaseParams) => {
+    setIsPurchasing(true);
+    try {
+      // 1. Find the correct RevenueCat package based on productId
+      const offerings = await paymentService.getOfferings();
+      // ... logic to find the package to purchase ...
+      const packageToPurchase = findPackageById(offerings, productId);
+
+      if (!packageToPurchase) {
+        throw new Error('Product not found.');
+      }
+
+      // 2. Call RevenueCat to initiate the purchase
+      const customerInfo =
+        await paymentService.purchasePackage(packageToPurchase);
+
+      // 3. Check if the purchase was successful (optional, but good practice)
+      if (customerInfo.entitlements.active['your_entitlement_id']) {
+        // 4. On successful purchase, record it in Convex
+        const result = await recordPurchase({ productId, quantity });
+
+        if (result.success) {
+          Toast.show(`Purchase successful!`, { type: 'success' });
+        } else {
+          throw new Error('Failed to record purchase in Convex.');
+        }
+      }
+    } catch (error: any) {
+      if (!error.userCancelled) {
+        Toast.show('Purchase failed. Please try again.', { type: 'danger' });
+      }
+    } finally {
+      setIsPurchasing(false);
+    }
+  };
+
+  return { purchaseProduct, isPurchasing };
+}
+```
+
+### 2. Add a New Credit Product
+
+1.  **RevenueCat Dashboard:** Create the new product in RevenueCat and attach it to an offering.
+2.  **Update Frontend Component:** In `apps/native/src/features/payments/components/payment-modal.tsx`, add the new product to the `products` array. Ensure the `id` matches the product identifier in RevenueCat.
+
+    ```tsx
+    const products = [
+      // ... existing products
+      {
+        id: 'credits_2500',
+        name: '2500 Credits',
+        price: '$12.99',
+        description: 'Super pack',
+      },
+    ];
+    ```
+
+3.  **Update Backend Logic (Optional):** If the new product should grant a different number of credits than its `quantity`, you can add custom logic to the `recordConsumablePurchase` mutation in `packages/backend/convex/paymentFunctions.ts`.
+
+## Backend (Convex)
+
+- **`packages/backend/convex/paymentFunctions.ts`:** This file contains the backend logic for crediting users after a purchase is confirmed by the client.
+  - `recordConsumablePurchase` (mutation): The core function that securely updates a user's credit balance and logs the transaction. This should only be called _after_ the payment provider has confirmed a successful payment.
+  - `getUserCredits` (query): A simple query to fetch the current user's credit count.
+  - `getPurchaseHistory` (query): Fetches a list of all transactions from the `purchases` table for the logged-in user.

package/2/vf-agent/data/knowledge_base/starter-docs/prd.md

@@ -0,0 +1,82 @@
+> **Note:** This document describes the requirements for the **VibeFast Starter Kit itself**, serving as a blueprint for its features. When creating a new application, this document serves as a reference for the starter's capabilities.
+
+# Product Requirements Document: VibeFast Starter Kit
+
+## 1. Introduction
+
+This document outlines the core functional and non-functional requirements for the VibeFast starter kit. It is intended to be a technical guide for developers and AI agents, defining _what_ the system does and the architectural principles it _must_ adhere to.
+
+## 2. Core Functional Requirements
+
+The VibeFast starter kit provides a suite of pre-built, production-ready features.
+
+### 2.1. Authentication
+
+The system must provide a comprehensive and swappable authentication module supporting:
+
+- **Email/Password:** Standard user registration and sign-in.
+- **Social Logins:** Google and GitHub OAuth providers.
+- **Apple Sign-In:** Native integration with Apple's authentication service.
+- **Passwordless:** Email-based OTP verification.
+- **Guest Sessions:** Anonymous access for new users, with a mechanism to convert to a registered account.
+- **Password Reset:** A secure flow for users to reset their forgotten passwords via email.
+
+### 2.2. Core Application Structure
+
+- **Tab Navigation:** A primary bottom tab navigator with the following screens:
+  - **Home:** A central dashboard showcasing available features.
+  - **Style:** A demo screen for UI components.
+  - **Profile:** User profile information.
+  - **Settings:** App-level settings.
+- **In-App Help System:** A help or documentation section that can render content from markdown files.
+
+### 2.3. AI-Powered Feature Modules
+
+The starter kit must include the following isolated and turnkey AI feature demos:
+
+- **AI Chatbot:** A conversational interface with support for text and image-based interactions.
+- **Image Generator:** A feature to generate images from text prompts using AI models.
+- **Image Analyzer:** A feature to upload images and receive a structured analysis based on a specified configuration (e.g., facial analysis, dashboard warning check).
+- **Voice Notes:** A feature for recording, storing, and playing back voice memos.
+
+### 2.4. Interactive Learning Modules
+
+- **Quiz System:** An interactive quiz feature supporting multiple question modes:
+  - **Auto-advance Mode:** Questions automatically progress after option selection
+  - **Manual-advance Mode:** Users control progression with continue/back buttons
+  - **Mixed Mode Support:** Individual questions can specify their own advancement behavior
+  - **Animated Transitions:** Smooth animations for option selection and navigation
+  - **Progress Tracking:** Visual progress indicator and completion screens
+  - **Configurable Behavior:** Centralized configuration for quiz appearance and functionality
+
+### 2.5. Monetization
+
+The system must include a pre-built monetization flow powered by an adapter (e.g., RevenueCat) that supports:
+
+- **Subscriptions:** Recurring billing for premium access.
+- **Consumable In-App Purchases:** A "credits" or "coins" system that can be purchased and consumed.
+- **Paywall Screen:** A dedicated UI to present purchase options to the user.
+
+### 2.6. User Settings & Personalization
+
+- **Theme Management:** Support for light, dark, and system themes.
+- **Language Selection:** Support for internationalization (i18n), with English and Arabic as default options.
+- **Push Notifications:** A settings toggle to enable or disable push notifications.
+
+## 3. Key Non-Functional Requirements (Architectural Principles)
+
+These principles are critical to maintaining the quality and integrity of the starter kit.
+
+- **Modularity:** Features must be built in isolation to allow for easy removal or modification via CLI tooling. This is enforced through strict module boundaries (`eslint-plugin-boundaries`).
+- **Vendor Agnosticism:** External services (e.g., authentication, payments) must be implemented behind a dedicated adapter pattern, allowing them to be swapped with minimal code changes.
+- **Code Quality:** The codebase must adhere to the defined linting (`ESLint`) and formatting (`Prettier`) rules. All code must be strongly typed using TypeScript.
+- **AI-Developer Friendliness:** Code must be clear, predictable, and well-documented. Patterns should be consistent and straightforward to enable efficient contributions from both human and AI developers.
+- **Extensibility:** The architecture must be designed to be easily extended with new features, components, and services without requiring significant refactoring of the core structure.
+
+## 4. Out of Scope
+
+This document explicitly excludes:
+
+- Target Audience Personas and Market Analysis.
+- Marketing and Go-to-Market Strategy.
+- Detailed Business Epics and User Stories.