vibefast-cli 0.6.2 → 0.7.1

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

@@ -1,110 +0,0 @@
-# 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

@@ -1,28 +0,0 @@
-# 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

@@ -1,96 +0,0 @@
-# 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

@@ -1,148 +0,0 @@
-# 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

@@ -1,82 +0,0 @@
-> **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.