Improved docs for future AI

README.md

@@ -0,0 +1,74 @@
+# MotoVaultPro - AI Onboarding Guide
+
+## For AI Assistants: Instant Codebase Understanding
+
+To efficiently understand and maintain this codebase, follow this exact sequence:
+
+### 1. Load Core Context (Required - 2 minutes)
+```
+Read these files in order:
+1. AI_PROJECT_GUIDE.md - Complete project overview and architecture
+2. .ai/context.json - Loading strategies and feature metadata
+3. docs/README.md - Documentation navigation hub
+```
+
+### 2. Understand the Architecture (30 seconds)
+**Modified Feature Capsules**: Each feature in `backend/src/features/[name]/` is 100% self-contained with everything needed in one directory. No shared business logic.
+
+### 3. For Specific Tasks
+
+#### Working on a Feature
+Load entire feature directory: `backend/src/features/[feature-name]/`
+- Start with README.md for complete API and business rules
+- Everything needed is in this single directory
+
+#### Cross-Feature Work  
+Load each feature's `index.ts` and `README.md`
+
+#### Database Work
+Load `docs/database-schema.md` for complete schema overview
+
+#### Testing Work
+Load `docs/testing.md` for Docker-based testing workflow
+
+### 4. Development Environment (1 command)
+```bash
+make dev  # Starts complete Docker environment
+```
+
+### 5. Key Principles
+- **Docker-First**: All development in containers, no local installs
+- **Feature Independence**: Each feature is completely isolated
+- **Single Directory Context**: Load one directory for complete understanding
+- **User-Scoped Data**: All data isolated by user_id
+
+### 6. Common Tasks
+```bash
+# Test specific feature
+npm test -- features/vehicles
+
+# Run migrations  
+make migrate
+
+# View logs
+make logs
+
+# Container shell access
+make shell-backend
+```
+
+### 7. Feature Status
+- **vehicles**: Complete (primary entity, VIN decoding)
+- **fuel-logs**: Implemented (depends on vehicles)
+- **maintenance**: Scaffolded (depends on vehicles) 
+- **stations**: Partial (Google Maps integration)
+
+## Architecture Summary
+Vehicle management platform using Modified Feature Capsule design where each feature is self-contained with API, domain logic, database layer, migrations, external integrations, tests, and documentation in a single directory. Built for AI maintainability with Docker-first development.
+
+## Quick Navigation
+- **Setup**: AI_PROJECT_GUIDE.md
+- **Features**: backend/src/features/[name]/README.md  
+- **Database**: docs/database-schema.md
+- **Testing**: docs/testing.md
+- **Security**: docs/security.md