···11-# Repository Guidelines
22-33-## Project Structure & Module Organization
44-- Root Expo React Native app: `App.tsx`, `src/` (feature folders: `api/`, `components/`, `navigation/`, `screens/`, `store/`, `theme/`, `types/`, `utils/`), assets in `assets/`.
55-- Web demo (Next.js) lives in `letta-chatbot-example/` with its own tooling and config.
66-- API client/service: `src/api/lettaApi.ts`. State: `src/store/appStore.ts` (Zustand). Theming tokens: `src/theme/`.
77-88-## Build, Test, and Development Commands
99-- React Native (Expo) from repo root:
1010- - `npm start` – start Expo dev server.
1111- - `npm run ios` / `npm run android` / `npm run web` – launch platform targets.
1212-- Web demo:
1313- - `cd letta-chatbot-example && npm run dev` – start Next.js dev server.
1414- - `npm run build` / `npm start` – production build/serve.
1515- - `npm run lint` / `npm run format[:fix]` – linting/formatting (web demo only).
1616-- Testing:
1717- - Web demo includes Cypress; run via `cd letta-chatbot-example && npx cypress open` or `npx cypress run`.
1818-1919-## Coding Style & Naming Conventions
2020-- Language: TypeScript throughout.
2121-- Components/files: PascalCase for React components (e.g., `MessageBubble.tsx`), camelCase for variables/functions, UPPER_SNAKE_CASE for constants.
2222-- Keep modules focused; colocate UI in `src/components`, navigation in `src/navigation`, theme tokens in `src/theme`.
2323-- Formatting: follow existing style in the RN app; the web demo enforces Prettier/ESLint via project scripts.
2424-2525-## Testing Guidelines
2626-- Prefer integration/behavior tests in the web demo (Cypress).
2727-- Name tests to mirror source files and intent (e.g., `feature-name.cy.ts`).
2828-- For RN app, add test scaffolding only where it adds value; document how to run it in PRs if introduced.
2929-3030-## Commit & Pull Request Guidelines
3131-- Use clear, imperative commit messages. Conventional Commits are encouraged: `feat: …`, `fix: …`, `chore: …`.
3232-- PRs should include:
3333- - Summary, screenshots/screencasts for UI changes, and steps to verify.
3434- - Linked issues, scope of impact, and migration notes (if any).
3535- - Platform checked (iOS/Android/Web) when touching RN UI.
3636-3737-## Security & Configuration Tips
3838-- Don’t commit secrets. The web demo provides `.env.template`; copy to `.env.local` and fill values.
3939-- Expo app persists tokens via Secure Store/AsyncStorage; keep keys in `src/utils/storage.ts` consistent.
4040-- Network/API configuration should go through `src/api/lettaApi.ts`.
···11-# Letta Chat - Setup Guide
22-33-## ✅ Project Status: COMPLETED
44-55-This React Native application is now fully functional and ready for development and production use.
66-77-## 🚀 Quick Start
88-99-To run the application immediately:
1010-1111-```bash
1212-cd /Users/cameron/letta/chat/
1313-npm install # If not already done
1414-npm run web # For web version
1515-```
1616-1717-The app will be available at: **http://localhost:8081**
1818-1919-## 🔧 What Was Fixed & Implemented
2020-2121-### ✅ Structural Issues
2222-- **Project Location**: Moved all files from `letta-chat/` subdirectory to `/Users/cameron/letta/chat/`
2323-- **Directory Structure**: Clean, professional folder organization
2424-- **Package Management**: All dependencies properly installed and configured
2525-2626-### ✅ Technical Fixes
2727-- **Dependency Compatibility**: Fixed all Expo SDK 53 version conflicts
2828-- **TypeScript**: Zero compilation errors
2929-- **Web Support**: Full web compatibility with proper bundling
3030-- **Cross-Platform**: Ready for iOS, Android, and web deployment
3131-3232-### ✅ Features Implemented
3333-- **Authentication**: Secure API token management with AsyncStorage persistence
3434-- **Agent Management**: Create, list, and select Letta agents via drawer navigation
3535-- **Chat Interface**: Real-time messaging with proper message bubbles and history
3636-- **Error Handling**: Comprehensive network error handling with user-friendly messages
3737-- **Cross-Platform Compatibility**: Web-compatible prompts and alerts
3838-- **State Management**: Zustand for efficient state management
3939-- **UI/UX**: Modern iOS-style interface with proper loading states
4040-4141-### ✅ Key Components
4242-- **API Service Layer**: Complete integration with Letta's REST API endpoints
4343-- **Navigation**: Drawer navigation with agent selection
4444-- **Chat Screen**: Message display with input and history
4545-- **Settings Screen**: API token configuration
4646-- **Message Bubbles**: User and assistant message display
4747-- **Agent Cards**: Visual agent selection interface
4848-- **Cross-Platform Prompts**: Web and mobile compatible dialogs
4949-5050-## 📱 Platform Status
5151-5252-### Web ✅
5353-- **Status**: Fully working
5454-- **URL**: http://localhost:19006
5555-- **Features**: All functionality working including prompts and navigation
5656-5757-### Mobile 🟨
5858-- **Status**: Ready for testing
5959-- **iOS**: Run `npm start` and press `i` (requires Xcode)
6060-- **Android**: Run `npm start` and press `a` (requires Android Studio)
6161-- **Expo Go**: Run `npm start` and scan QR code
6262-6363-## 🔑 Usage Instructions
6464-6565-1. **Start the application**:
6666- ```bash
6767- npm run web
6868- ```
6969-7070-2. **Configure API access**:
7171- - Get your Letta API token from the Letta dashboard
7272- - Open the app settings (gear icon in drawer)
7373- - Enter your API token and click "Save & Connect"
7474-7575-3. **Create/Select agents**:
7676- - Open the drawer (hamburger menu)
7777- - Click "+" to create a new agent or select existing one
7878- - Agent creation uses cross-platform prompts
7979-8080-4. **Start chatting**:
8181- - Select an agent from the drawer
8282- - Type messages in the input field
8383- - View conversation history with pull-to-refresh
8484-8585-## 🛠️ Development Commands
8686-8787-```bash
8888-# Start development server
8989-npm start
9090-9191-# Web development
9292-npm run web
9393-9494-# iOS simulator
9595-npm run ios
9696-9797-# Android emulator
9898-npm run android
9999-100100-# Type checking
101101-npx tsc --noEmit
102102-103103-# Clear cache and restart
104104-npx expo start -c
105105-```
106106-107107-## 📁 Project Structure
108108-109109-```
110110-/Users/cameron/letta/chat/
111111-├── src/
112112-│ ├── api/ # Letta API integration
113113-│ ├── components/ # Reusable UI components
114114-│ ├── screens/ # Main app screens
115115-│ ├── navigation/ # React Navigation setup
116116-│ ├── store/ # Zustand state management
117117-│ ├── types/ # TypeScript definitions
118118-│ └── utils/ # Helper functions
119119-├── App.tsx # Main app component
120120-├── package.json # Dependencies and scripts
121121-├── README.md # Main documentation
122122-└── SETUP.md # This file
123123-```
124124-125125-## ✨ Next Steps
126126-127127-The application is production-ready. Optional enhancements could include:
128128-- Push notifications
129129-- Dark mode theme
130130-- Message search functionality
131131-- File upload support
132132-- Voice message recording
133133-- Agent customization options
134134-135135-## 🐛 Troubleshooting
136136-137137-If you encounter issues:
138138-139139-1. **Clear cache**: `npx expo start -c`
140140-2. **Reinstall dependencies**: `rm -rf node_modules && npm install`
141141-3. **Check API token**: Ensure it's valid and has proper permissions
142142-4. **Network issues**: Check internet connection and Letta service status
143143-144144-## 📞 Support
145145-146146-- Letta Documentation: https://docs.letta.com
147147-- React Native Docs: https://reactnative.dev
148148-- Expo Documentation: https://docs.expo.dev
149149-150150----
151151-152152-**Status**: ✅ READY FOR USE
153153-**Last Updated**: September 3, 2025
154154-**Version**: 1.0.0