vibefast-cli 0.2.4 → 0.3.1

package/2/vf-agent/data/knowledge_base/frontend/ui-and-styling.md

@@ -0,0 +1,169 @@
+# UI & Styling Guidelines
+
+## 0. Visual Design Fundamentals (CRITICAL)
+
+### Soft, Harmonious Design
+
+- **NEVER** use harsh contrasts: `border-black` on white or `border-white` on dark
+- **ALWAYS** use soft borders: `border-neutral-200 dark:border-neutral-800`
+- **Default rounding:** `rounded-lg` for cards, `rounded-md` for buttons
+- **Soft text:** `text-neutral-900 dark:text-white` instead of pure black/white
+
+### Theme-Aware Styling (MANDATORY)
+
+**ALWAYS** style for both themes using `dark:` prefix:
+
+```tsx
+// ✅ CORRECT - Both themes covered
+<Text className="text-neutral-800 dark:text-white">
+<View className="bg-white dark:bg-gray-900 border border-neutral-200 dark:border-neutral-800">
+
+// ❌ WRONG - Only light theme
+<Text className="text-neutral-800">
+```
+
+**Essential combinations:**
+
+- Text: `text-neutral-800 dark:text-white` | `text-neutral-600 dark:text-neutral-300`
+- Backgrounds: `bg-white dark:bg-gray-900` | `bg-neutral-50 dark:bg-neutral-800`
+- Borders: `border-neutral-200 dark:border-neutral-800`
+
+### Anti-Boring Design
+
+When given creative freedom, add visual interest:
+
+- **Accent colors:** `bg-blue-50 dark:bg-blue-900/20 border-l-4 border-blue-500`
+- **Status colors:** Green (success), amber (warning), red (error), blue (info)
+- **Avoid:** All-gray interfaces - use purposeful color for engagement
+
+### Intentional Design (CRITICAL)
+
+**Don't blindly apply rules everywhere.** Be purposeful:
+
+- **Borders:** Only add when they serve a purpose (separation, emphasis, grouping)
+- **Backgrounds:** Use sparingly - not every element needs a background color
+- **Colors:** Each color should have meaning (brand, status, hierarchy)
+- **Shadows:** Only for elevation/layering, not decoration
+
+```tsx
+// ✅ INTENTIONAL - Borders serve clear purposes
+<View className="border-t border-neutral-200 dark:border-neutral-800 pt-4"> // Section divider
+<View className="border border-red-200 bg-red-50 rounded-lg p-3"> // Error container
+<TextInput className="border border-neutral-300 rounded-lg"> // Form field
+
+// ❌ OVER-DESIGNED - Unnecessary borders everywhere
+<Text className="border border-neutral-200 p-2">Just text</Text> // Why border this?
+<View className="bg-neutral-50 border border-neutral-300"> // Too much visual noise
+```
+
+**Ask yourself:** "Why am I adding this border/background/color? What problem does it solve?"
+
+### Mobile-First UX
+
+- **Touch targets:** Minimum `min-h-11 min-w-11` (44px)
+- **Screen padding:** `px-4` minimum, `gap-6` between sections
+- **Typography scale:** `text-2xl` (titles) → `text-lg` (sections) → `text-base` (body) → `text-sm` (secondary)
+
+## 1. Core Component Rules (MANDATORY)
+
+### Button Usage
+
+- **Button component:** Takes `label` prop, NEVER put `<Text>` inside
+- **Button layouts:** Stack vertically for long text (3+ words), row only for short text
+
+```tsx
+// ✅ CORRECT
+<Button label="Submit" onPress={handleSubmit} />
+<View className="gap-4">
+  <Button label="Start New Project" />
+  <Button label="View All Projects" />
+</View>
+
+// ❌ WRONG
+<Button><Text>Submit</Text></Button>
+```
+
+### Component Library
+
+- **MUST** use built-in components from `apps/native/src/components/ui/` (import via `@/components/ui`)
+- **Pressable** for complex interactive elements (icons, multi-line, custom layouts)
+- **Button** for simple text-only actions
+
+## 2. Smart UX Patterns
+
+### Dashboard Thinking
+
+Add value-driven widgets when appropriate:
+
+```tsx
+// ✅ User-focused dashboard
+<View className="gap-4">
+  <View className="flex-row gap-4">
+    <StatsCard title="Revenue" value="$12,450" trend="+15%" />
+    <StatsCard title="Users" value="1,284" trend="+8%" />
+  </View>
+  <ProgressCard title="Monthly Goal" current={75} total={100} />
+</View>
+```
+
+### Micro-Interactions & Feedback
+
+```tsx
+// Loading states - Use custom Spinner
+{loading ? <Spinner variant="pulse" size="sm" /> : <Text>Submit</Text>}
+
+// Success/Error - Use Toast notifications
+toast.success('Saved successfully!');
+toast.error('Failed to save');
+
+// Touch feedback
+<Pressable className="active:scale-95 active:bg-blue-600">
+```
+
+### Empty States
+
+Never show blank screens:
+
+```tsx
+{
+  items.length === 0 ? (
+    <View className="flex-1 justify-center items-center px-8">
+      <Text className="text-4xl mb-4">📝</Text>
+      <Text className="text-lg font-semibold mb-2">No items yet</Text>
+      <Text className="text-neutral-600 dark:text-neutral-300 mb-6">
+        Start by creating your first item
+      </Text>
+      <Button label="Create First Item" onPress={handleCreate} />
+    </View>
+  ) : (
+    <FlatList data={items} />
+  );
+}
+```
+
+## 3. Technical Requirements
+
+### Styling
+
+- **Primary:** NativeWind only, no inline styles
+- **Spacing:** Use `gap-*` for flex containers, avoid `space-*`
+- **Grid:** Not supported, use `flexbox` with wrapping
+- **Theme colors:** Use `text-primary`, `bg-primary` for brand colors
+- **Accessibility:** All interactive elements need `accessibilityRole`, `accessibilityLabel`
+
+### Performance
+
+- `SafeAreaView` or proper insets for screen layout
+- `FlashList` optimization: `estimatedItemSize` for better performance
+- Smooth interactions with proper touch targets and feedback
+
+## Quick Reference
+
+**Common Patterns:**
+
+- Cards: `bg-white dark:bg-gray-800 rounded-xl p-6 shadow-sm border border-neutral-200 dark:border-neutral-700`
+- Forms: Clear labels, validation feedback, proper keyboard types
+- Lists: Pull-to-refresh, swipe actions, skeleton loading
+- Navigation: Tab bar + stack, clear hierarchy
+
+**Remember:** User requirements always override these suggestions. These guidelines apply when you have creative freedom to enhance the UX.

package/2/vf-agent/data/knowledge_base/general-principles.md

@@ -0,0 +1,26 @@
+# General Principles & Philosophy
+
+## Project Context
+
+- **Project:** "vibefast" - A modular React Native Expo starter kit for AI-powered mobile applications.
+- **Core Philosophy:** Modularity, AI-IDE friendliness, swappable services, developer efficiency, LLM-friendly codebase.
+- **Repository Layout:** pnpm/Turborepo monorepo (`apps/native` for Expo, `packages/backend` for Convex, shared packages under `packages/*`).
+- **Backend:** Convex (Auth, DB, Functions, Storage, Cron) packaged as `@vibefast/backend`.
+- **Frontend:** React Native with Expo (`apps/native`).
+
+## Core Principles
+
+- **Modularity & DRY:** Prioritize iteration and modularization over code duplication. Components and services should be reusable and maintainable.
+- **Clarity over Cleverness:** Write concise, readable, and technically sound TypeScript code.
+- **Functional & Declarative:** Strongly prefer functional components (React) and declarative programming patterns. Avoid classes.
+- **Abstraction:** External SDKs or vendor-specific logic (e.g., RevenueCat, AI providers) **MUST** be accessed only through adapter layers or dedicated service implementations. Core application logic should interact with our defined interfaces, not directly with vendor SDKs.
+- **Atomic Commits:** Keep diffs atomic. Each commit or PR should represent one logical change.
+- **Documentation:** Use JSDoc for every exported function, type, and prop interface. Maintain clear READMEs.
+- **TypeScript Usage Guidelines:** - **Strict Mode:** All code **MUST** compile with `tsc --noEmit`. - **Types over Interfaces:** Prefer `type` for defining object shapes, props, etc., unless interface-specific features like declaration merging are needed. - **Avoid Enums:** Use `as const` objects for string or numeric literal unions:
+  ```typescript
+    export const UserRoles = { Admin: 'ADMIN', User: 'USER' } as const;
+    export type UserRole = (typeof UserRoles)[keyof typeof UserRoles];
+**Error Handling & Logging:**
+    - **Core Logging Service:** For all client-side logging, you **MUST** use the `Logger`from`apps/native/src/core/logging/`(via the`@/core/logging`alias). Do not use`console.log` directly in application logic outside of temporary debugging.
+    - **User-Friendly Messages:** In the UI, always provide clear, user-friendly error messages. Log detailed technical errors to the monitoring service (e.g., Sentry) for debugging, but do not expose stack traces or technical jargon to the user.
+    - **`try...catch`Blocks:** Avoid using`try...catch` for flow control. Use them for genuine exceptional circumstances or when wrapping external API calls that are expected to fail under certain conditions. Let errors propagate to a higher-level handler where appropriate. - **Backend Error Handling:** Catch any errors from third-party API calls within Convex actions. Return standardized error objects or messages to the client. Do not leak raw external API errors or sensitive information.

package/2/vf-agent/data/knowledge_base/master-rulebook.md

@@ -0,0 +1,42 @@
+# VibeFast Master Rulebook
+
+This is the central knowledge base for the VibeFast project. All agents MUST adhere to the principles and rules outlined in the documents linked below. This is the immutable source of truth for the VibeFast architecture and development standards.
+
+## 1. Core Principles & Architecture
+
+- **[General Philosophy & High-Level Principles](./general-principles.md)**
+- **[Official Tech Stack](./starter-docs/tech-stack.md)**
+- **[Unified Project Structure](./starter-docs/unified-project-structure.md)**
+
+## 2. Universal Standards (Apply to both Frontend & Backend)
+
+- **[Coding Style & Naming Conventions](./coding-standards.md)**
+- **[Testing Guidelines](./testing-guidelines.md)**
+- **[Image Handling Rules](./frontend/image-handling.md)**
+
+## 3. Backend Development (Convex)
+
+- **[Convex - Core Concepts](./backend/convex-main.md)** (Functions, Visibility, Validators, API Design)
+- **[Convex - Database & Schema](./backend/convex-database.md)** (Schema, Queries, Mutations, Search)
+- **[Convex - Advanced Features](./backend/convex-advanced.md)** (HTTP Actions, Scheduling, File Storage)
+- **[Convex Full Guidelines](./backend/full-guidelines.md)** (Additional Convex-specific rules)
+
+## 4. Frontend Development (React Native & Expo)
+
+- **[React Native - Core Concepts](./frontend/react-native-main.md)** (State Management, Component Design)
+- **[UI & Styling Guidelines](./frontend/ui-and-styling.md)** (NativeWind, Core UI Components, CRITICAL Button Rules)
+- **[Image Handling Rules](./frontend/image-handling.md)**
+- **[Frontend Guidelines](./frontend/full-guidelines.md)** (Additional React Native rules)
+
+## 5. Testing Strategy
+
+- **[Overall Testing Strategy](./testing/testing-strategy.md)**
+- **[Frontend Testing Patterns (Jest & RNTL)](./testing/frontend-testing.md)**
+- **[Backend Testing Patterns (Vitest)](./testing/backend-testing.md)**
+
+## 6. Project Structure & Reference
+
+- **[Starter Kit Documentation](./starter-docs/)**
+- **[Feature Reference Index](./starter-docs/feature-reference-index.md)**
+- **[Tech Stack Reference](./starter-docs/tech-stack.md)**
+- **[Unified Project Structure](./starter-docs/unified-project-structure.md)**

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

@@ -0,0 +1,98 @@
+# Audio Recorder Reference
+
+> Frontend paths reference the Expo workspace (`apps/native/src/...`).
+
+## Overview
+
+The Audio Recorder feature provides a complete solution for capturing, storing, and playing back audio within the app. It leverages the powerful `expo-av` library for client-side recording and playback, and uses Convex for persistent storage and metadata management.
+
+### Core Technologies
+
+- **[Expo AV](https://docs.expo.dev/versions/latest/sdk/av/):** The core of the feature, used for accessing the device microphone, managing recording sessions, and playing back audio.
+- **[Convex File Storage](https://docs.convex.dev/file-storage):** The recorded audio files are uploaded as blobs and stored securely in Convex.
+- **[Convex Mutations & Queries](https://docs.convex.dev/functions):** Used to create, update, list, and delete recording metadata in the database.
+- **[Moti](https://moti.fyi/):** Used for creating the smooth animations in the `AudioVisualizer` component.
+
+## Getting Started
+
+The Audio Recorder feature is ready to use out-of-the-box and does not require any external API keys. It will request microphone permissions from the user on first use.
+
+### Audio Recording Flow
+
+1.  **User Initiates Recording:** The user presses the record button in the `AudioRecorderControls` component, which calls the `startRecording` function from the `useAudioRecorder` hook.
+2.  **Permissions & Setup:** The hook requests microphone permissions if not already granted and sets the `Audio` mode for recording.
+3.  **Recording State:** `expo-av` begins recording. The `useAudioRecorder` hook tracks the state, including duration and metering data for the visualizer.
+4.  **User Stops Recording:** The user presses the stop button, calling the `stopRecording` function.
+5.  **File Upload & Finalization:**
+    - The hook gets the local file URI of the completed recording.
+    - It first calls the `createRecordingDraft` Convex mutation to get a new `recordingId`.
+    - It then fetches the audio data from the local URI, creates a `Blob`, and uploads it to Convex File Storage using the `useUploadFile` hook.
+    - Once the file is uploaded, it calls the `finalizeRecording` mutation, updating the database record with the file's storage ID, final duration, and metering data.
+6.  **UI Update:** The `RecordingList` component, which uses the `useRecordingsList` hook, automatically updates to show the newly saved recording.
+
+## Key Components & Hooks
+
+### Core Components
+
+- `AudioRecorderControls`: The main UI for starting, pausing, resuming, and stopping a recording.
+- `RecordingList`: Displays a list of all the user's past recordings.
+- `RecordingListItem`: Renders a single item in the list, containing the `AudioPlayer` and controls for renaming or deleting the recording.
+- `AudioPlayer`: A component for playing back a recorded audio file, which includes an `AudioVisualizer`.
+- `AudioVisualizer`: Displays the audio waveform or playback progress using animated bars.
+- `Timer`: A simple component to display the recording or playback duration.
+
+### Core Hooks
+
+- `useAudioRecorder`: The primary hook for handling the entire recording process. It manages permissions, recording state (start, stop, pause, resume), and the logic for saving the final file to Convex.
+- `useAudioPlayer`: A hook for managing the playback of a single audio file. It handles loading the sound, play/pause state, and tracking playback progress.
+- `useRecordingsList`: A hook that fetches all of the user's recordings and provides the mutations for deleting or renaming them.
+
+## How-To Guides
+
+### 1. Change the Audio Quality
+
+You can change the quality of the audio recordings by modifying the preset used in the `useAudioRecorder` hook.
+
+**File to Edit:** `apps/native/src/features/audio-recorder/hooks/use-audio-recorder.ts`
+
+```ts
+// ... inside startRecording function
+const { recording: newRecording } = await Audio.Recording.createAsync(
+  // Change preset here. Options: HIGH_QUALITY, LOW_QUALITY
+  Audio.RecordingOptionsPresets.LOW_QUALITY,
+  (status) => {
+    // ...
+  },
+);
+```
+
+### 2. Customize the Visualizer
+
+The `AudioVisualizer` can be easily customized.
+
+**File to Edit:** `apps/native/src/features/audio-recorder/components/audio-visualizer.tsx`
+
+- **Number of Bars:** Change the `NUM_BARS` constant to increase or decrease the resolution of the visualizer.
+- **Bar Height:** Modify the `getBarHeight` function to change the sensitivity or maximum height of the bars.
+- **Colors:** The colors are controlled by Tailwind CSS classes (`bg-primary`, `bg-muted-foreground`). You can change these to match your app's theme.
+
+### 3. Add Transcription (Conceptual)
+
+To add audio transcription:
+
+1.  **Create a New Action:** Create a new Convex `action` (e.g., `transcribeRecording`).
+2.  **Trigger the Action:** After a recording is successfully finalized, you could modify the `stopRecording` function in `useAudioRecorder` to call this new action, passing the `storageId` of the audio file.
+3.  **Backend Logic:**
+    - The `transcribeRecording` action would fetch the audio file from storage.
+    - It would then send the audio data to a third-party transcription service (e.g., OpenAI's Whisper API).
+    - Upon receiving the transcript, it would call an `internalMutation` to save the text to the corresponding recording's document in the database.
+4.  **Display Transcript:** Update the `RecordingListItem` to display the new transcript field if it exists.
+
+## Backend (Convex)
+
+- **`packages/backend/convex/recordingFunctions.ts`:** This file contains all the necessary database operations for the feature.
+  - `createRecordingDraft` (mutation): Creates a placeholder record to get an ID before the file upload begins.
+  - `finalizeRecording` (mutation): Updates the draft record with the final file URI, duration, and other metadata after the upload is complete.
+  - `deleteRecording` (mutation): Deletes a recording record from the database.
+  - `updateRecordingName` (mutation): Allows users to rename their recordings.
+  - `listRecordings` (query): Fetches all of a user's completed recordings.

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

@@ -0,0 +1,155 @@
+# Authentication Reference
+
+> Frontend paths reference the Expo workspace (`apps/native/src/...`); backend paths reference `packages/backend/convex/...`.
+
+## Overview
+
+The VibeFast starter kit provides a robust and secure authentication system out-of-the-box. It supports email/password, social sign-on (OAuth), and passwordless flows, built on a foundation of Convex and Auth0. This document serves as a comprehensive guide for developers to understand, use, and extend the authentication features.
+
+### Core Technologies
+
+- **[Convex](https://convex.dev):** Handles all backend logic, including user management, session control, and database interactions. The `@convex-dev/auth` package provides the core authentication primitives.
+- **[Auth0](https://auth0.com):** Used as the primary OAuth provider to easily integrate social logins (Google, Apple, GitHub). It can be configured via environment variables.
+- **[React Native / Expo](https://reactnative.dev):** The frontend is built with React Native and Expo, using custom hooks and components to interact with the authentication system.
+- **[Zod](https://zod.dev):** Used for schema validation on all authentication forms, ensuring data integrity.
+
+## Getting Started
+
+The authentication feature is pre-configured and works out of the box. The primary setup required is adding your Auth0 and other OAuth provider credentials to your environment variables.
+
+### Environment Variables
+
+To enable social logins, you must configure the following variables in your `.env` file (e.g., `.env.local`):
+
+```bash
+# Auth0 Credentials (for social login)
+AUTH_AUTH0_DOMAIN="..."
+AUTH_AUTH0_CLIENT_ID="..."
+
+# OAuth Provider Credentials (used by Convex)
+AUTH_GOOGLE_ID="..."
+AUTH_APPLE_CLIENT_ID="..."
+AUTH_GITHUB_ID="..."
+
+# Convex Site URL (ensure this matches your deployment)
+CONVEX_SITE_URL="http://localhost:8000"
+```
+
+### Authentication Flow
+
+1.  **UI Interaction:** The user interacts with components in `apps/native/src/features/authentication/components`, such as `SignInForm`, `SignUpForm`, or `OAuthProviders`.
+2.  **Hook-based Logic:** UI events trigger hooks like `useSignIn()` or `useSignUp()`. These hooks handle form state using `react-hook-form` and Zod schemas for validation.
+3.  **Convex Mutations:** The hooks call Convex mutations (e.g., `api.auth.signIn`).
+4.  **Session Management:** Upon successful authentication, Convex generates a session token. The `useAuthHandler` hook stores this token securely on the client using `convex.setAuth()`.
+5.  **Authenticated State:** The application state updates, and `useConditionalAuth` or `AuthConditionalRender` can be used to show/hide UI elements based on the user's authentication status.
+
+## Key Components & Hooks
+
+The authentication feature is modular and built for easy extension.
+
+### Core Components
+
+- `AuthConditionalRender`: A wrapper that conditionally renders child components based on whether the user is authenticated.
+- `OAuthProviders`: Renders social login buttons (Apple, Google, GitHub) and handles the Auth0 `authorize` flow.
+- `AuthFormContainer`, `AuthFormWrapper`, `AuthFormHeader`: UI components for building consistent authentication screens.
+- `FormTextInput`: A `react-hook-form` integrated text input with built-in validation and error display.
+
+### Core Hooks
+
+- `useConditionalAuth()`: The primary hook to check if a user is currently authenticated. Returns `isAuthenticated` and `isLoading` booleans.
+- `useSignIn()` / `useSignUp()`: Hooks that provide form management, validation, and submission logic for email/password sign-in and sign-up.
+- `usePasswordReset()`: Provides `useForgotPassword` and `useResetPassword` for handling password recovery flows.
+- `useAuthHandler()`: A crucial hook that orchestrates the post-authentication process, storing the session token and navigating the user to the appropriate next screen.
+- `useAuthNavigation()`: Determines the next screen after a successful login (e.g., to the main app or to an email verification screen).
+
+## How-To Guides
+
+### 1. Check if a User is Logged In
+
+Use the `useConditionalAuth` hook anywhere in your component tree.
+
+```tsx
+import { useConditionalAuth } from '@/features/authentication';
+import { Text, View } from '@/components/ui';
+
+function MyComponent() {
+  const { isAuthenticated, isLoading } = useConditionalAuth();
+
+  if (isLoading) {
+    return <Text>Loading...</Text>;
+  }
+
+  return (
+    <View>
+      {isAuthenticated ? (
+        <Text>Welcome, user!</Text>
+      ) : (
+        <Text>Please sign in.</Text>
+      )}
+    </View>
+  );
+}
+```
+
+### 2. Protect a Route or Screen
+
+While you can use `useConditionalAuth` to conditionally render UI, route protection is best handled at the layout level in Expo Router. You can create a layout that checks for authentication and redirects if necessary.
+
+```tsx
+// app/(protected)/_layout.tsx
+import { useConditionalAuth } from '@/features/authentication';
+import { Redirect, Slot } from 'expo-router';
+import { FullScreenLoader } from '@/components/ui';
+
+export default function ProtectedLayout() {
+  const { isAuthenticated, isLoading } = useConditionalAuth();
+
+  if (isLoading) {
+    return <FullScreenLoader />;
+  }
+
+  if (!isAuthenticated) {
+    // Redirect to the sign-in screen
+    return <Redirect href="/(routes)/auth/sign-in" />;
+  }
+
+  return <Slot />;
+}
+```
+
+### 3. Add a New Social Provider
+
+To add a new OAuth provider (e.g., Facebook):
+
+1.  **Add Provider to Auth0:** Configure the new provider in your Auth0 dashboard.
+2.  **Update `OAuthProviders.tsx`:** Add the new provider to the `providers` array and handle its `connection` name.
+3.  **Update Convex `auth.config.ts`:** If you were connecting directly through Convex, you would add the provider configuration here. With the current Auth0 setup, this is not necessary unless you are bypassing Auth0.
+
+### 4. Customize User Schema
+
+The user schema is defined in `packages/backend/convex/schema.ts`. To add a new field to the user document (e.g., `username`):
+
+1.  **Update Schema:**
+    ```ts
+    // packages/backend/convex/schema.ts
+    export default defineSchema({
+      users: defineTable({
+        // ... existing fields
+        username: v.optional(v.string()),
+      }).index('by_email', ['email']),
+      // ... other tables
+    });
+    ```
+2.  **Update Sign-Up Form:** Add the `username` field to the `SignUpSchema` in `apps/native/src/features/authentication/utils/auth-schemas.ts` and to the sign-up form component.
+3.  **Update Convex Function:** Modify the Convex function that creates the user to accept and store the new `username` field.
+
+## Backend (Convex)
+
+The backend logic resides in the `packages/backend/convex/` directory.
+
+- **`auth.config.ts`:** Configures the authentication providers that Convex will trust.
+- **`auth.ts`:** The core file for `@convex-dev/auth`. It initializes the `convexAuth` helper, which provides `auth`, `signIn`, `signOut`, etc. It also includes important callbacks like `afterUserCreatedOrUpdated` for handling side effects like initializing user credits.
+- **`users.ts`:** Contains mutations and queries related to user data that are not directly part of the authentication flow itself, such as creating a user with initial device credits.
+- **Password Reset & OTP:** Files like `authPasswordReset.ts` and `authOtp.ts` contain the logic for passwordless and password recovery flows.
+
+By leveraging the `@convex-dev/auth` library, the backend code is kept minimal and declarative, while providing a powerful and secure foundation.

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

@@ -0,0 +1,149 @@
+# Charts Feature Reference
+
+> Frontend paths reference the Expo workspace (`apps/native/src/...`).
+
+## Overview
+
+The Charts feature is a powerful, self-contained library for rendering animated and interactive charts in React Native. It provides a set of common chart types, including Bar, Line, Pie, and Donut charts, built with a focus on customizability and performance.
+
+This feature is currently a **frontend-only** library. It comes with mock data to demonstrate the capabilities of each chart type. To use in a production scenario, you would provide your own data fetched from a backend like Convex.
+
+### Core Technologies
+
+- **[React Native SVG](https://github.com/react-native-svg/react-native-svg):** The fundamental library used to draw the shapes (lines, arcs, circles) that make up the charts.
+- **[D3.js (d3-shape)](https://d3js.org/d3-shape):** A powerful library used for calculating the complex path data required for lines, areas, and pie chart arcs. The starter kit uses only the `d3-shape` module to keep the bundle size small.
+- **[Reanimated 2](https://docs.swmansion.com/react-native-reanimated/):** Powers all the animations, from bars growing to their height to lines being drawn on the screen. This ensures the animations are smooth and performant.
+
+## Getting Started
+
+The chart components are ready to be used anywhere in your application. You can see a preview of all available charts on the `ChartPreviewScreen` located at `apps/native/src/features/charts/app/preview.tsx`.
+
+To use a chart, import it and provide it with a `data` prop in the correct format.
+
+### Basic Usage: Bar Chart
+
+```tsx
+import { BarChart, ChartCard } from '@/features/charts';
+
+// Data format: an array of objects with id, label, and value.
+const mySalesData = [
+  { id: '1', label: 'Jan', value: 3500 },
+  { id: '2', label: 'Feb', value: 4200 },
+  { id: '3', label: 'Mar', value: 5300 },
+];
+
+function SalesDashboard() {
+  return (
+    <ChartCard title="Monthly Sales">
+      <BarChart data={mySalesData} height={250} />
+    </ChartCard>
+  );
+}
+```
+
+## Chart Components
+
+### 1. `BarChart`
+
+- **Description:** A standard bar chart that can be rendered either vertically (default) or horizontally.
+- **Key Props:**
+  - `data`: `Array<{ id, label, value, color? }>`
+  - `horizontal`: `boolean` - Renders bars horizontally if true.
+  - `barWidth`: `number` - Manually set the width of each bar.
+  - `gap`: `number` - The space between bars.
+
+### 2. `LineChart`
+
+- **Description:** A flexible line chart that can show trends over time. It supports curved lines, area fills, and data point dots.
+- **Key Props:**
+  - `data`: `Array<number>` - An array of numerical values.
+  - `labels`: `Array<string>` - An array of labels for the x-axis.
+  - `curved`: `boolean` - Renders the line with a Catmull-Rom curve.
+  - `showArea`: `boolean` - Shows a filled area beneath the line.
+  - `showDots`: `boolean` - Shows a dot for each data point.
+
+### 3. `PieChart`
+
+- **Description:** A classic pie chart for showing proportions. It includes a legend and can handle presses on individual sections.
+- **Key Props:**
+  - `data`: `Array<{ id, label, value, color? }>`
+  - `radius`: `number` - The outer radius of the pie.
+  - `showLegend`: `boolean` - Toggles the display of the legend below the chart.
+  - `onSectionPress`: `(item) => void` - A callback function when a pie slice is pressed.
+
+### 4. `DonutChart`
+
+- **Description:** A variant of the `PieChart` with a hole in the center. It is a wrapper around the `PieChart` component.
+- **Key Props:**
+  - Accepts all `PieChart` props.
+  - `innerRadiusRatio`: `number` (from 0 to 1) - The size of the center hole as a percentage of the `radius`. Defaults to `0.6`.
+
+### Wrapper Component
+
+- **`ChartCard`:** A styled container card with a title and subtitle, designed to wrap any chart component for a consistent look and feel.
+
+## How-To Guides
+
+### 1. Provide Live Data
+
+To use the charts with your own data, replace the mock data with data fetched from your Convex backend.
+
+```tsx
+import { useQuery } from 'convex/react';
+import { api } from '@vibefast/backend/_generated/api';
+import { BarChart, ChartCard } from '@/features/charts';
+import { FullScreenLoader } from '@/components/ui';
+
+function LiveSalesDashboard() {
+  // Assume you have a query `getSalesData` in `packages/backend/convex/sales.ts`
+  const salesData = useQuery(api.sales.getSalesData);
+
+  if (!salesData) {
+    return <FullScreenLoader />;
+  }
+
+  // Ensure the fetched data is mapped to the format the chart expects
+  const chartData = salesData.map((sale) => ({
+    id: sale._id,
+    label: sale.month,
+    value: sale.revenue,
+  }));
+
+  return (
+    <ChartCard title="Live Monthly Sales">
+      <BarChart data={chartData} height={250} />
+    </ChartCard>
+  );
+}
+```
+
+### 2. Customize Chart Colors
+
+You can override the default color palette by passing a `colors` array prop to the `BarChart` or `PieChart`.
+
+```tsx
+const myColors = ['#ff6384', '#36a2eb', '#ffce56'];
+
+<PieChart data={myData} colors={myColors} />;
+```
+
+For the `LineChart`, you can customize individual elements:
+
+```tsx
+<LineChart
+  data={myData}
+  strokeColor="#ff6384"
+  fillColor="#ff638433" // Stroke color with some transparency
+  dotColor="#ff6384"
+/>
+```
+
+### 3. Create a New Chart Type
+
+While the library provides common charts, you can use its building blocks to create new ones. The general process is:
+
+1.  **Create a new component file** in `apps/native/src/features/charts/components/`.
+2.  **Use React Native SVG** as the canvas for your chart.
+3.  **Use D3.js** if you need complex shape calculations.
+4.  **Use Reanimated** to animate the properties of your SVG elements (e.g., path length, position, size).
+5.  **Accept a `data` prop** and other configuration props to make your new chart reusable.