vibefast-cli 0.7.0 → 0.7.1

package/2/vf-agent/data/knowledge_base/coding-standards.md

@@ -1,253 +0,0 @@
-# Coding Standards and Conventions
-
-## Overview
-
-This document specifies the coding standards, formatting guidelines, and best practices that all developers (human and AI) MUST follow when contributing to the VibeFast project. Adherence to these standards is enforced through linting, pre-commit hooks, and CI workflows. Unless noted otherwise, frontend paths are relative to `apps/native/src/` and backend paths are relative to `packages/backend/convex/`.
-
-## 1. General Principles & Philosophy
-
-- **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.
-- **Absolute Imports:** **MUST use absolute imports** for all files within `apps/native/src/` (e.g., `import { Button } from '@/components/ui';`). This is configured in the root `tsconfig.json` and Expo/Babel config. Frontend code imports Convex generated helpers via `@vibefast/backend/_generated/...` instead of deep relative paths.
-
-## 2. File & Naming Conventions
-
-This project uses two different filename casing conventions depending on the location. This is strictly enforced by ESLint.
-
-- **Frontend (`apps/native/src/`):** All files and directories MUST use **`kebab-case`**.
-  - _Example:_ `apps/native/src/features/image-analyzer/components/results-header.tsx`
-
-- **Backend (`packages/backend/convex/`):** All files and directories MUST use **`camelCase`**.
-  - _Example:_ `packages/backend/convex/imageAnalysisFunctions.ts`
-
-- **Components (React):** Component functions and filenames MUST use **`PascalCase`**.
-  - _Example:_ `const MyComponent = () => ...;` in `MyComponent.tsx`
-
-- **Variables & Functions:** Use **`camelCase`**.
-- **Types & Interfaces:** Use **`PascalCase`**.
-- **Constants:** Use **`UPPER_SNAKE_CASE`** for constant values.
-
-## 3. Frontend Development Standards (React Native)
-
-### 3.1. UI & Styling (NativeWind)
-
-- **NativeWind:** This is the primary styling solution. Use semantic utility classes (e.g., `bg-primary`, `text-base`). Avoid inline styles unless absolutely necessary for dynamic properties.
-- **Core UI Components:** You **MUST** use the built-in UI components from `apps/native/src/components/ui/` (accessible via `@/components/ui`) as the base for all UIs to ensure consistency.
-
-#### 3.1.1. Button Component Usage (CRITICAL)
-
-- **Button Text:** The `Button` component from `@/components/ui` has a `label` prop for button text. **NEVER** put `<Text>` elements as children of `Button`.
-
-  ```tsx
-  // ✅ CORRECT
-  <Button label="Click Me" onPress={handlePress} />
-
-  // ❌ WRONG - Never do this
-  <Button onPress={handlePress}>
-    <Text>Click Me</Text>
-  </Button>
-  ```
-
-- **Complex Button Content:** If you need more than simple text (icons, multiple text elements, complex layouts), use `Pressable` from `@/components/ui` instead of `Button`.
-
-  ```tsx
-  // ✅ CORRECT for complex content
-  <Pressable onPress={handlePress} className="flex-row items-center p-4">
-    <Icon name="star" />
-    <Text>Complex Button</Text>
-    <Text className="text-sm text-neutral-500">Subtitle</Text>
-  </Pressable>
-  ```
-
-- **Button vs Pressable Decision:**
-  - Use `Button` for simple, single-label actions
-  - Use `Pressable` for complex layouts, multiple text elements, or custom designs
-
-- **Accessibility (A11y):** All interactive components MUST have appropriate `accessibilityRole`, `accessibilityLabel`, and `accessibilityState` props.
-- **Spacing:** Use `gap-x` and `gap-y` for spacing between elements instead of `space-x` and `space-y`. The latter may not always work as expected.
-- **Grid Layouts:** If `grid` does not work in NativeWind, use other layout techniques like flexbox to achieve the desired design.
-
-#### 3.1.2. Theme Color Usage (CRITICAL)
-
-- **NEVER** use hardcoded color names like `emerald`, `blue`, `red`, `green`, etc. for primary theme colors, use them only when appropriate and aren't being used as theme colors.
-- **ALWAYS** use semantic theme color classes that reference the app's design system
-- **Primary Theme Colors:** Use `text-primary`, `bg-primary`, `border-primary` for main brand colors
-- **Semantic Colors:** Use intensity-based classes like `text-primary-500`, `bg-primary-400`, `border-primary-600`
-
-  ```tsx
-  // ✅ CORRECT - Using theme colors
-  <Text className="text-primary">Primary text</Text>
-  <View className="bg-primary-500">Primary background</View>
-  <Button className="bg-primary text-primary-foreground">Primary button</Button>
-
-  // ❌ WRONG - Hardcoded colors
-  <Text className="text-emerald-600">Primary text</Text>
-  <View className="bg-emerald-500">Primary background</View>
-  <Button className="bg-emerald-600 text-white">Primary button</Button>
-  ```
-
-### 3.2. State Management
-
-- **Convex React Hooks (`useQuery`, `useMutation`):** The primary tool for server state and backend interactions.
-- **Zustand:** Used for global, client-side UI state only (e.g., theme, global notifications).
-- **Local Component State (`useState`):** The default for UI state that is confined to a single component.
-
-## 4. Backend Development Standards (Convex)
-
-### 4.1. Function Definitions
-
-- **Syntax:** ALWAYS use the new function syntax (e.g., `export const f = query({...});`).
-
-- **Visibility:** Use `query`, `mutation`, `action` for public API functions. Use `internalQuery`, `internalMutation`, `internalAction` for private functions that should not be callable from the client.
-
-- **Validators:** **ALWAYS** include argument (`args`) and return type (`returns`) validators for **ALL** Convex functions. For functions with no explicit return, use `returns: v.null()`.
-
-- **Node.js Actions:** For actions requiring Node.js-specific modules (e.g., `crypto`), add `"use node";` as the absolute first line of the file.
-
-- Use `getAuthUserId` for getting user ID, not `identity.subject`:
-
-  ```ts
-  import { getAuthUserId } from '@convex-dev/auth/server';
-  const userId = await getAuthUserId(ctx);
-  ```
-
-### 4.2. Schema & Database
-
-- **Schema Definition:** The single source of truth for the database schema is `packages/backend/convex/schema.ts`.
-- **Querying:**
-  - Do **NOT** use `.filter()` in queries. Define an index in `schema.ts` and use `.withIndex()` for efficient data retrieval.
-  - Use `.unique()` to get a single document. It will throw an error if multiple documents match.
-
-- **Mutations:**
-  - Use `ctx.db.patch` for shallow-merging updates into a document.
-  - Use `ctx.db.replace` to completely replace a document.
-
-### 4.3. HTTP Endpoints
-
-- **Definition:** HTTP endpoints are defined in `packages/backend/convex/http.ts` and exposed via `packages/backend/convex/router.ts`.
-- **Authentication:** All `httpAction`s that require user authentication MUST validate the session using `await ctx.auth.getUserIdentity();`. If the identity is `null`, the action must return a `401 Unauthorized` response.
-
-## 5. Testing Standards
-
-- **Frontend (Jest + RNTL):** Write unit tests for utilities, complex components, and core services. Test files must be co-located with the source and named `*.test.ts(x)`.
-- **Backend (Vitest):** Write unit tests for all Convex functions containing business logic. Tests are run via the `pnpm test:backend` script.
-- **E2E (Maestro):** Add `testID` props to key elements to support end-to-end testing flows.
-
-## 6. Git & Commit Standards
-
-- **Commit Messages:** Follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification (e.g., `feat:`, `fix:`, `chore:`). This is enforced by `commitlint`.
-- **Branching:** Direct commits to `main` or `master` are disallowed by pre-commit hooks. All work should be done on feature branches.
-
-## 7. Code Quality Rules
-
-### 7.1 React Patterns
-
-- Always place React hooks (`useState`, `useEffect`, etc.) at the top of components, before any conditional returns.
-- For JSX text content containing special characters (like >, <, ', "), always use template literals with backticks: {``} to include the string directly, rather than using HTML entities (e.g., &quot;, &gt;). Example: {`This string has special characters and doesn't give errors like ' > <`}
-
-- Never call hooks conditionally or after early returns.
-
-### 7.2 Import Patterns
-
-- Check for duplicate imports in the same import statement.
-- Consolidate multiple imports from the same module into a single import statement.
-
-### 7.3 TypeScript Patterns
-
-- Run TypeScript compilation check before considering implementation complete.
-- Address all TypeScript errors before proceeding to the next task.
-
-### 7.4 Linting Patterns
-
-- Use template literals with backticks (`{``}`) for special characters in JSX text content.
-- Follow React hooks rules strictly — hooks must be called in the same order every render.
-
-### 7.5 Critical UI Component Patterns (MUST READ BEFORE CODING)
-
-#### Button Component Usage
-
-- **NEVER** use `<Text>` as children of `<Button>` component
-- **ALWAYS** use the `label` prop for button text
-- **Example:**
-
-  ```tsx
-  // ✅ CORRECT
-  <Button label="Save Changes" onPress={handleSave} />
-
-  // ❌ WRONG - This violates our standards
-  <Button onPress={handleSave}>
-    <Text>Save Changes</Text>
-  </Button>
-  ```
-
-#### When to Use Button vs Pressable
-
-- **Use Button:** For simple, single-text actions with our design system styling
-- **Use Pressable:** For complex layouts, multiple text elements, icons with text, or custom designs
-- **Example of Pressable usage:**
-  ```tsx
-  <Pressable onPress={handlePress} className="flex-row items-center gap-2 p-4">
-    <Icon name="star" />
-    <View>
-      <Text className="font-semibold">Primary Text</Text>
-      <Text className="text-sm text-neutral-500">Secondary text</Text>
-    </View>
-  </Pressable>
-  ```
-
-#### Button Layout Rules (CRITICAL)
-
-- **Single Row Layout:** ONLY use `flex-row` for multiple buttons when button text is SHORT (1-2 words max)
-- **Vertical Stack Layout:** ALWAYS use vertical stacking (`gap-4` in parent View) when button text is LONG (3+ words)
-- **Example of CORRECT button layouts:**
-
-  ```tsx
-  // ✅ CORRECT - Short text, can use flex-row
-  <View className="flex-row gap-4">
-    <Button label="Save" onPress={handleSave} className="flex-1" />
-    <Button label="Cancel" onPress={handleCancel} className="flex-1" />
-  </View>
-
-  // ✅ CORRECT - Long text, use vertical stack
-  <View className="gap-4">
-    <Button label="Start Conversation" onPress={handleStart} />
-    <Button label="End Conversation" onPress={handleEnd} />
-  </View>
-
-  // ❌ WRONG - Long text in flex-row causes truncation
-  <View className="flex-row gap-4">
-    <Button label="Start Conversation" onPress={handleStart} className="flex-1" />
-    <Button label="End Conversation" onPress={handleEnd} className="flex-1" />
-  </View>
-  ```
-
-### 7.6 Logging & Error Reporting (CRITICAL)
-
-- Use the core logger API from `@/core/logging` — never use `console.*` in app code under `apps/native/src/**`.
-  - Allowed exceptions: test files and explicit debug utilities under `apps/native/src/components/ui/extras/debug-*`.
-- Always include a `feature` tag in the logging context to categorize events (e.g., `auth.login`, `notifications.register`, `chatbot.file_upload`, `convex.http`).
-- Pass an `Error` object to `error()` whenever available to preserve stack traces: `error(err, { feature, ... })`.
-- Prefer `handleError()` from `@/components/ui` for user-visible failures; it logs using the core logger and shows a toast. Avoid duplicating logs when `handleError` is used — only add additional `info` when it adds necessary context.
-- Avoid logging PII. Truncate or hash sensitive values (e.g., use token prefixes), or redact via a custom transport in `apps/native/src/core/logging/custom-transports.ts`.
-
-Examples:
-
-```ts
-import { info, warn, error, debug } from '@/core/logging';
-import { handleError } from '@/components/ui';
-
-info('Push token recorded', { feature: 'notifications.register', tokenPrefix });
-warn('Retrying upload', { feature: 'chatbot.file_upload', attempt });
-error(new Error('Missing config'), { feature: 'convex.http' });
-
-try {
-  await doThing();
-} catch (err) {
-  handleError(err, {
-    feature: 'settings.share',
-    fallbackMessage: 'Unable to share app',
-  });
-}
-```

package/2/vf-agent/data/knowledge_base/frontend/full-guidelines.md

@@ -1,254 +0,0 @@
----
-description:
-globs:
-alwaysApply: true
----
-
-# **Developer & AI Agent Coding Guidelines**
-
-**You are an expert Full Stack Developer specializing in TypeScript, React Native, Expo, NativeWind, and Convex.** Your primary goal is to write clean, maintainable, modular, and performant code adhering to the architectural decisions and guidelines for the "vibefast" starter kit.
-
-**Every time you choose to apply a rule(s) from this document, explicitly state the rule(s) in your output. You can abbreviate the rule description to a single word or phrase.**
-
-## Project Context & Philosophy
-
-- **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.
-- **Backend:** Convex (Auth, DB, Functions, Storage, Cron).
-- **Frontend:** React Native with Expo.
-
-## Code Style and Structure (General)
-
-- **Conciseness & Clarity:** Write concise, technically sound TypeScript code with accurate examples where applicable.
-- **Functional & Declarative:** Strongly prefer functional components (React) and declarative programming patterns. Avoid classes.
-- **Modularity & DRY:** Prioritize iteration and modularization over code duplication. Ensure components and services are modular, reusable (where appropriate), and maintainable.
-- **Component Granularity:** Break down UI components into smaller, reusable pieces. Keep components focused on a single responsibility. Aim for components **≤ 80 lines of code** (excluding imports/ JSDoc), and services/functions **≤ 250 LOC per file**; extract helpers if longer.
-- **Descriptive Naming:** Use descriptive variable, function, and component names. Use auxiliary verbs for boolean flags (e.g., `isLoading`, `hasError`, `isFeatureEnabled`).
-- **Absolute Imports:** **MUST use absolute imports** for all files within `apps/native/src/` (e.g., `import { Button } from '@/components/ui';` never `../../components/ui/Button`). Frontend code MUST import Convex generated helpers via `@vibefast/backend/_generated/...` rather than relative paths.
-- **No Direct Vendor Calls (Abstraction):** External SDKs or vendor-specific logic (e.g., for RevenueCat, Sentry, PostHog, specific AI providers) **MUST be touched only through adapter layers or dedicated service implementations** within their respective feature modules (e.g., `apps/native/src/features/payments/services/revenuecat-adapter.ts`) or Convex `lib/` adapters (e.g., `packages/backend/convex/lib/ai/openaiAdapter.ts`). The core application logic should interact with our defined service interfaces in `apps/native/src/core/`.
-- **Comments:** **Don't write excessive code comments.** Focus on JSDoc for public APIs/interfaces and comments for _why_ complex or non-obvious logic exists, not _what_ the code is doing.
-- **Atomic Commits/Diffs:** **Keep diffs atomic.** Each commit or PR should represent one logical change.
-- **Review EsLint Rules** and follow these rules.
-
-## Naming Conventions
-
-- **General Files & Directories (e.g., in `apps/native/src/`):** `kebab-case` (e.g., `user-profile.tsx`, `auth-service.ts`).
-- **Convex Backend Files (`packages/backend/convex/` directory):** **`camelCase`** (e.g., `otpAuth.ts`, `chatbotFunctions.ts`). This is an ESLint override.
-- **React Components (Functions):** `PascalCase` (e.g., `UserProfileCard.tsx`).
-- **Variables & Functions/Methods:** `camelCase`.
-- **Types, Interfaces, Enums (const objects):** `PascalCase`.
-- **Constants:** `UPPER_SNAKE_CASE`.
-- **Exports:** Favor named exports for components, utilities, and services.
-
-## TypeScript Usage
-
-- **Strict Mode:** **Code MUST compile with `tsc --noEmit` under strict mode.** (as per `tsconfig.json`).
-- **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/numeric literal unions:
-  ```typescript
-  export const UserRoles = { Admin: 'ADMIN', User: 'USER' } as const;
-  export type UserRole = (typeof UserRoles)[keyof typeof UserRoles];
-  ```
-- **Functional Components:** Use functional components with typed props.
-- **Explicit Return Types:** Use explicit return types for all non-trivial functions and all exported functions.
-- **`@typescript-eslint/consistent-type-imports`:** Adhere to this rule (prefer `import type`).
-- **Avoid `any`:** Use `unknown` or define specific types. Justify any use of `any`.
-- **Discriminated Unions:** Implement proper TypeScript discriminated unions for message types or state variants.
-
-## State Management (Frontend)
-
-- **Convex React Hooks (`useQuery`, `useMutation`, `useAction`):** Primary for server state and backend interactions.
-- **Zustand:** For global, client-side UI state (e.g., theme, global notifications).
-- **MMKV (via Core Cache Service):** For persistent local storage (guest data, user preferences).
-- **Local Component State (`useState`, `useReducer`):** Default for UI state confined to a component.
-- **`useEffect` Cleanup:** Implement proper cleanup functions in `useEffect` hooks to prevent memory leaks.
-
-## UI and Styling (Frontend - NativeWind)
-
-- **Things to follow:** Whenever you have to show loading state don't do "Loading..." use an actual loader.
-- **Regarding Themeing:**
-- **NativeWind:** Primary styling solution. Use semantic utility classes (`bg-primary`, `text-base`). **Avoid inline styles** unless absolutely necessary for dynamic properties not easily handled by NativeWind. In Nativewind space-2, space-x-4, gap-y-8 don't work you have to use gap-2, gap-x-2, gap-y-8 (these are example values to explain the rule). Grid also doesn't work don't use grid use someother way when needed.
-- **Core UI Components:** **MUST use built-in UI components** from `apps/native/src/components/ui/` (or via the `@/components/ui` alias) as the base for UIs.
-- **Accessibility (A11y):** Ensure high accessibility standards. All interactive components MUST have appropriate `accessibilityRole`, `accessibilityLabel`, `accessibilityHint`, and `accessibilityState`. Refer to `front-end-architecture.md#AccessibilityAXImplementationDetails`.
-- **Animations & Gestures:** Leverage `react-native-reanimated` and `react-native-gesture-handler` for performant animations and gestures.
-- **Performance:** Avoid unnecessary re-renders (use `React.memo`, `useCallback`, `useMemo` judiciously). Use `@shopify/flash-list` for long lists.
-- **Theme Adherence:** Ensure UI elements use colors and fonts defined in `tailwind.config.js`.
-- **Cross-Platform Consistency:** Test UI on both iOS and Android. Use `Platform.select` for minor stylistic differences if NativeWind utilities don't fully abstract them (e.g., complex shadows).
-
-## Convex Backend Development
-
-- **Filename Convention:** **`camelCase`** for all `.ts` files in `convex/`.
-- **New Function Syntax:** **ALWAYS use the new function syntax** for queries, mutations, and actions (e.g., `export const myQuery = query({ args: {}, handler: async (ctx, args) => { ... } });`).
-- **Validators:** **ALWAYS include argument and return type validators** (`v` object from `convex/values`) for all Convex functions (public and internal). Use `v.null()` for functions that don't explicitly return a value.
-- **Public vs. Internal:** Use `query`, `mutation`, `action` for public API functions. Use `internalQuery`, `internalMutation`, `internalAction` for functions not meant to be called from the client.
-- **Schema (`convex/schema.ts`):** Define all database tables and indexes here. System fields (`_id`, `_creationTime`) are automatic. Follow index naming conventions (e.g., `by_field1_and_field2`).
-- **API Design:** Organize functions logically in files.
-- **Error Handling:** Catch errors from third-party API calls within Convex actions. Return standardized error objects/messages to the client. Do not leak raw external API errors.
-- **Security:** Validate ALL inputs from the client in Convex functions. Implement authorization logic to protect data access. Store API keys and secrets as Convex environment variables (`npx convex env set KEY VALUE`).
-- **Import Path:** **Frontend MUST consume Convex generated helpers via `@vibefast/backend/_generated/...`** (and internal code within the backend uses relative paths). Never reach into `packages/backend/convex` with lengthy relative imports from the app.
-
-## Error Handling (General)
-
-- **Core Logging Service:** Use the `Logger` from `apps/native/src/core/logging/` (via `@/core/logging`) for all client-side logging.
-- **User-Friendly Messages:** Provide clear, user-friendly error messages in the UI. Log detailed technical errors for debugging.
-- **`try...catch`:** Avoid excessive `try...catch` blocks for flow control. Use them for genuine exceptional circumstances or around external calls that might fail. Let errors propagate to a higher-level handler where appropriate.
-
-## Testing
-
-- **Unit Tests (Jest & RNTL for Frontend, Convex Test Framework for Backend):** Write unit tests for utilities, complex components, core services, and all Convex functions with business logic.
-- **Test File Naming:** `component-name.test.tsx` or `functionName.test.ts`, co-located.
-- **No Tests for Simple Presentational Components:** Focus testing effort on logic and interaction.
-- **Coverage:** Aim for high coverage of critical logic.
-- **E2E Tests (Maestro):** Ensure `testID`s are added to key elements to support E2E testing.
-
-## Git Usage
-
-- **Commit Message Prefixes:** `fix:`, `feat:`, `perf:`, `docs:`, `style:`, `refactor:`, `test:`, `chore:`.
-- **Rules:** Lowercase messages, concise summary line (max 100 chars), reference issue numbers.
-
-## Documentation
-
-- **JSDoc:** **JSDoc every exported function, type, and prop interface.**
-- **READMEs:** Maintain a clear main `README.md`. Feature modules should have their own brief READMEs.
-- **Architecture Docs:** Refer to `architecture.md`, `front-end-architecture.md`, etc. in `docs/`.
-
-## AI Agent Specific Instructions (MUST FOLLOW)
-
-1.  **Adherence to Guidelines:** You MUST strictly follow all guidelines in this document and other architectural documents referenced in the story.
-2.  **Story as Primary Work Order:** The `*.story.md` file is your primary instruction set.
-3.  **Consult Reference Docs:** You SHOULD consult `architecture.md`, `front-end-architecture.md`, `prd.md`, and `operational-guidelines.md` (this doc) for context, standards, and patterns. If a story's "Dev Technical Guidance" conflicts with a general guideline, the story's specific guidance takes precedence _for that story_.
-4.  **Four Strikes Rule for Blockers:** If you attempt to solve a specific technical blocker (e.g., persistent lint error, failing test, tool command error) four times without success, you MUST stop, clearly document the issue, what you tried, and ask the human user for guidance. Do not loop indefinitely.
-5.  **Progress Marking:** Mark progress in `ai/implementation-plan.md` as specified in story ACs.
-6.  **Clarity in Communication:** When asking for clarification or reporting issues, be precise about the problem, what you've tried, and what information you need.
-
-### **🔍 Category 1: Investigation & Setup Rules**
-
-**Rule 1.1: Prioritize Existing Patterns for Consistency**
-
-- **When to Use:** _Before writing any new test file or complex test suite._
-- **Guideline:**
-  1.  Look for similar tests in the codebase (e.g., tests for similar components, hooks, or services).
-  2.  Observe and adopt established mocking patterns, import structures, and test organization (e.g., `beforeEach` setup, `describe` block structure).
-  3.  Review `jest.config.js` and `jest-setup.ts` to understand global test configurations and setup.
-  4.  Check the `apps/native/src/__mocks__/` directory for any pre-defined global mocks for libraries.
-  5.  **Assumption:** The existing testing setup (`jest-expo` preset) is generally functional. Investigate existing working tests before assuming the setup is broken for new tests.
-
-**Rule 1.2: Perform Thorough Dependency Tracing for Mocks**
-
-- **When to Use:** _Before attempting to mock any dependency for a component or function under test._
-- **Guideline:**
-  1.  Open the source file of the component/function being tested. List ALL its direct imports.
-  2.  For each custom import (e.g., starting with `@/` from within our project), briefly inspect what that imported module itself imports or relies on, if relevant to the test.
-  3.  Identify ALL external dependencies (libraries, other project modules/services, React Native APIs, Expo APIs, Convex hooks) that the unit under test _directly or indirectly through its immediate custom imports_ uses and whose behavior needs to be controlled for the test.
-  4.  Mock only the necessary dependencies to isolate the unit under test. Use `jest.mock('path/to/module', () => ({ ...mockedExports... }));` for each module whose functions/components need to be mocked.
-
-### **🔧 Category 2: TypeScript & Mocking Precision Rules**
-
-**Rule 2.1: Ensure Type-Accurate Data Mocks (Especially for Convex/Database)**
-
-- **When to Use:** _When creating mock data for props, hook return values, or function arguments, particularly for data originating from or structured like Convex database documents._
-- **Guideline:**
-  1.  For Convex data, refer to `convex/schema.ts` for table structures and `convex/_generated/dataModel.d.ts` for exact `Doc<"tableName">` and `Id<"tableName">` types.
-  2.  Mock objects MUST include ALL required fields as per their TypeScript definition, including system fields for Convex documents (e.g., `_id: "mockId" as Id<"users">`, `_creationTime: Date.now()`).
-  3.  Use correct types for all fields. For Convex `Id` types in mocks, casting a string (e.g., `"mockId" as Id<"tableName">`) is acceptable.
-  4.  For mocked hooks or functions, ensure the _entire return object structure_ (including all properties, even if some are just `jest.fn()`) matches what the actual hook/function returns.
-
-**Rule 2.2: Implement Complete & Accurate Mocks for Hooks/Services**
-
-- **When to Use:** _When mocking custom hooks, services, or complex functions from external libraries (e.g., `@ai-sdk/react`, `@convex-dev/auth/react`)._
-- **Guideline:**
-  1.  Inspect the actual implementation or type definition of the hook/service to understand its full return signature (all properties, methods, and their types).
-  2.  The `jest.mock()` factory for the module MUST return a mock that provides ALL properties/methods the component under test will try to access.
-  3.  For functions within the mocked object, use `jest.fn()`. If these functions are expected to return values, mock their implementation accordingly (e.g., `mockedFunction: jest.fn(() => 'mockReturnValue')`).
-  4.  Use meaningful mock data that matches expected types for return values.
-
-### **⚛️ Category 3: React Native Specific Testing Rules (RNTL)**
-
-**Rule 3.1: Correctly Simulate React Native User Events**
-
-- **When to Use:** _When testing user interactions like button presses or text input changes using React Native Testing Library._
-- **Guideline:**
-  1.  For `Pressable` or `Button` `onPress` events, use `fireEvent.press(element)`. If the component's handler expects an event object (e.g., for `event.preventDefault()`), you may need to pass a mock event: `fireEvent.press(element, { nativeEvent: {} /* or more specific if needed */ });`. (The AI's fix of `const mockEvent = { preventDefault: jest.fn() }; fireEvent.press(sendButton, mockEvent);` was good for a case where `preventDefault` was explicitly called).
-  2.  For `TextInput` `onChangeText` events, use `fireEvent.changeText(inputElement, 'new text')`.
-  3.  For other events, use the appropriate `fireEvent` method (e.g., `fireEvent.scroll`).
-  4.  Always check the component's prop signature to understand what event arguments it expects.
-
-**Rule 3.2: Verify User-Visible State Changes and Accessibility Props**
-
-- **When to Use:** _When testing how a component's internal state or props affect what the user sees or how assistive tech interacts with it._
-- **Guideline:**
-  1.  Prioritize asserting on what the user would experience:
-      - Use `screen.getByText('Visible Text')` or `screen.queryByText('Text Should Not Be Visible')`.
-      - Check for changes in `accessibilityState` (e.g., `expect(button).toHaveAccessibilityState({ disabled: true })`).
-      - Verify `accessibilityLabel` and `accessibilityRole`.
-  2.  When checking dynamic states like `disabled` from `accessibilityState`, be mindful of optional chaining if the state might not always be present: `element.props.accessibilityState?.disabled`.
-  3.  Test the _outcome_ of state changes (e.g., different text displayed, button becomes disabled) rather than directly inspecting internal component state variables.
-
-### **🏗️ Category 4: Mock Structure & Strategy Rules**
-
-**Rule 4.1: Mock External Library Dependencies Effectively**
-
-- **When to Use:** _When dealing with substantial external libraries that have complex internal state or side effects not relevant to the unit under test (e.g., `@ai-sdk/react`, `@shopify/flash-list`, navigation libraries)._
-- **Guideline:**
-  1.  Mock the entire module at the top of your test file using `jest.mock('module-name', () => ({ ...mockedExports... }));`.
-  2.  For complex hooks from these libraries (like `useChat`), provide a mock implementation that returns a complete object covering all properties your component will access during the test scenario.
-  3.  For UI components from these libraries (e.g., `FlashList`), if their internal rendering is complex and irrelevant to your component's logic, provide a simple mock implementation (e.g., a `View` that just renders `data.map(renderItem)`).
-  4.  If you need to access original parts of a module while mocking others, use `const actualModule = jest.requireActual('module-name');` within your mock factory and spread `...actualModule` before overriding specific exports.
-
-**Rule 4.2: Handle Problematic UI Component Mocks**
-
-- **When to Use:** _If specific UI components (especially those with native code, animations, or deep context dependencies like `FocusAwareStatusBar`) cause issues in the Jest/RNTL test environment._
-- **Guideline:**
-  1.  Identify components that are problematic for unit tests (e.g., they throw errors unrelated to your component's logic because their required native environment isn't fully present).
-  2.  Create a specific mock for that component path in your `jest.mock()` call, returning a simple placeholder (e.g., `jest.mock('@/components/ui/focus-aware-status-bar', () => () => null);` or a simple `<View />`).
-  3.  This is for _unit/component tests_ of _other_ components that _use_ the problematic one. The problematic component itself should have its own dedicated tests where its specific dependencies are handled or mocked appropriately.
-
-### **🐛 Category 5: Debugging Test Failures Rules**
-
-**Rule 5.1: Adhere to the Three-Strikes Debugging Protocol**
-
-- **When to Use:** _When encountering any persistent test failure or error during test implementation._
-- **Guideline:**
-  1.  **First Attempt:** Review your test logic, component interaction, and basic mock setup. Check for typos or simple errors.
-  2.  **Second Attempt:** Verify TypeScript types of mocks against actual component props/hook signatures. Ensure mock objects are complete and accurately represent all accessed properties/methods. Double-check dependency tracing.
-  3.  **Third Attempt:** Simplify the test case to its absolute minimum to isolate the problematic interaction. Try testing a simpler aspect of the component first.
-  4.  **After 3 Unsuccessful Attempts:** **STOP.** Clearly document:
-      - The specific error message(s).
-      - The component/function being tested.
-      - What you have tried.
-      - Your hypothesis about the root cause.
-      - Ask the human user for guidance.
-  5.  **DO NOT loop indefinitely** trying to fix the same issue without making clear progress or understanding the root cause.
-
-**Rule 5.2: Systematically Analyze Test Error Messages**
-
-- **When to Use:** _Whenever a test fails._
-- **Guideline:**
-  1.  **"not a function" (e.g., `TypeError: X is not a function`):** Usually means a property or method you're trying to call on a mocked object/hook return value hasn't been defined in your mock. Check your `jest.mock()` factory for that module/hook.
-  2.  **"Cannot read properties of undefined (reading 'X')":** A variable or an object is `undefined`, and you're trying to access a property `X` on it. This often points to an incomplete mock (a hook didn't return the expected object structure) or a logic error where a variable isn't initialized before use.
-  3.  **"Type 'X' is not assignable to type 'Y'":** A TypeScript error indicating your mock data or function signature doesn't match the expected type. Refer to the actual type definitions.
-  4.  **Component Rendering Errors (e.g., from deep within a library):** Often indicates a missing mock for a crucial provider (like Navigation, Theme, Convex) or a native module that the component relies on. Ensure your test setup (`render` helper from `test-utils.tsx`) includes all necessary global providers.
-  5.  **Examine Line Numbers:** Pay close attention to the line numbers in the error stack trace, both in your test file and the component's source code, to pinpoint where the error originates.
-
-### **📋 Category 6: Test Organization & Focus Rules**
-
-**Rule 6.1: Follow Consistent Test File Structure & Hoisting**
-
-- **When to Use:** _When creating any new test file._
-- **Guideline:**
-  1.  **Imports First (Generally):** Standard React, testing-library, and the component under test.
-  2.  **`jest.mock()` Calls:** All `jest.mock('module-path', ...)` calls MUST appear at the very top of the file, before any `import` statements, to ensure mocks are hoisted and applied correctly by Jest.
-  3.  **Import Mocked Functions (if needed for spying/resetting):** If you need to reference the mocked functions themselves (e.g., `const { useChat } = require('@ai-sdk/react'); (useChat as jest.Mock).mockReturnValue(...)`), do this _after_ the `jest.mock()` calls.
-  4.  **`describe`, `beforeEach`, `it/test` Structure:** Use `describe` to group related tests. Use `beforeEach` to reset mocks (`jest.clearAllMocks()`) and set up common mock return values for a suite. Use `it` or `test` for individual test cases.
-  5.  **Happy Path First:** Test the primary, successful functionality of a component/function first. Then, add tests for alternative paths, edge cases, and error handling.
-
-**Rule 6.2: Maintain Focused Test Coverage**
-
-- **When to Use:** _When deciding what aspects of a component/function to test._
-- **Guideline:**
-  1.  **Component Renders Without Crashing:** A basic smoke test.
-  2.  **User Interactions:** Test key interactions (button clicks, text input, form submissions) and verify they trigger the expected callbacks or state changes _visible to the user_.
-  3.  **State Changes:** Verify that changes in props or internal state lead to the correct UI updates (different text, elements appearing/disappearing, styles changing if critical to behavior).
-  4.  **Props & Hook Configuration:** Test how different prop values or different return values from mocked hooks affect the component's rendering and behavior.
-  5.  **Avoid Over-Testing Implementation Details:** Focus on testing the component's public API (props) and its user-observable behavior, not its internal private functions or state structure directly unless absolutely necessary.
-  6.  **Accessibility Props:** Verify key accessibility props are set correctly.

package/2/vf-agent/data/knowledge_base/frontend/image-handling.md

@@ -1,48 +0,0 @@
-# Image Handling Rules
-
-## 1. Dynamic Local Images
-
-- **The Problem:** React Native's bundler cannot handle dynamic paths in `require()`. Code like `require(\`./images/${name}.png\`)` will **CRASH** the app.
-- **The Solution:** You **MUST** use a static map object to pre-load all possible dynamic images. Use a variable as a key to look up the correct pre-required image at runtime.
-
-- **Implementation:**
-
-  ```ts
-  // 1. Define the static map at the top level of your file.
-  const IMAGE_MAP = {
-      front: require('@/assets/images/guide-front.png'),
-      side: require('@/assets/images/guide-side.png'),
-  };
-
-  // 2. Use the map in your component.
-  const MyComponent = ({ view }: { view: 'front' | 'side' }) => {
-      return <Image source={IMAGE_MAP[view]} />;
-  };
-  ```
-
-## 2\. General Image Component Usage
-
-- You **MUST** use the custom `<Image />` component from `@/components/ui` for all images. Do not use the default `react-native` Image component. Our component is a wrapper around `expo-image` which provides superior performance and caching.
-
-## 3\. Image Accessibility
-
-- All images that convey information (i.e., are not purely decorative) **MUST** have a descriptive `accessibilityLabel` prop for screen readers.
-
-## 4\. Image Optimization Before Upload
-
-- Before uploading any user-selected image to Convex, you **MUST** process it with the `expo-image-manipulator` library.
-
-- This is critical for resizing and compressing images to reduce upload time, save bandwidth, and lower storage costs.
-
-- **Example:**
-
-  ```typescript
-  import * as ImageManipulator from 'expo-image-manipulator';
-
-  const result = await ImageManipulator.manipulateAsync(
-    originalImageUri,
-    [{ resize: { width: 1024 } }], // Resize to a reasonable width
-    { compress: 0.7, format: ImageManipulator.SaveFormat.JPEG },
-  );
-  // Upload the file at result.uri to Convex Storage.
-  ```

package/2/vf-agent/data/knowledge_base/frontend/react-native-main.md

@@ -1,24 +0,0 @@
-# React Native - Core Concepts
-
-## 1. State Management Strategy
-
-The project uses a clear, multi-layered approach to state management. Use the right tool for the job.
-
-- **Server State:** Use **Convex React Hooks (`useQuery`, `useMutation`, `useAction`)** for all data that lives on the backend. This is the default and should be your first choice. It provides real-time updates, caching, and optimistic updates out of the box.
-- **Global Client State:** Use **Zustand** for global UI state that is _not_ persisted on the server. Examples include: the current theme (dark/light), the state of a global notification toast, or the status of a multi-step modal.
-- **Local Component State:** Use **React Hooks (`useState`, `useReducer`)** for all state that is confined to a single component or its immediate children. This should be your default for managing UI interactions, form inputs, and component-specific loading states.
-- **Persistent Local Storage:** Use the core cache service, which is a wrapper around **MMKV**, for storing simple key-value data that needs to persist across app launches (e.g., user preferences, if they've seen the onboarding flow).
-
-## 2. Component Design
-
-- **Component Granularity:** Break down UI into small, reusable components with a single responsibility. Aim for components **≤ 80 lines of code** (excluding imports and JSDoc).
-- **`useEffect` Cleanup:** ALWAYS implement a proper cleanup function in `useEffect` hooks to prevent memory leaks, especially when dealing with subscriptions, timers, or event listeners.
-
-## 3. Performance
-
-- Avoid unnecessary re-renders. Use `React.memo`, `useCallback`, and `useMemo` judiciously where performance bottlenecks are identified.
-- For long lists of data, **MUST** use `@shopify/flash-list` instead of `FlatList` for significantly better performance.
-
-```
-
-```