gh-jamshu-jamshi-marketplace-plugins-odoo-pwa-generator/commands/help.md

Display comprehensive help and documentation for the Odoo PWA Generator plugin.

## What this command does:
- Provides overview of the plugin and its capabilities
- Lists all available commands with descriptions
- Explains the plugin's skills and when to use them
- Shows common usage patterns and workflows
- Links to detailed documentation

## Plugin Overview:
The **odoo-pwa-generator** plugin helps you create offline-first Progressive Web Apps with Odoo Studio backend integration. It supports SvelteKit, React, and Vue frameworks.

### Key Features:
✨ **Quick Project Generation** - Create complete PWAs in minutes
📱 **Offline-First** - Smart caching with background sync
🔄 **Odoo Integration** - Seamless Odoo Studio connectivity
🚀 **Production Ready** - Pre-configured deployment setups
⚡ **Framework Support** - SvelteKit, React, and Vue

### Core Capabilities:
- Automatic CRUD operations for Odoo models
- Smart caching with localStorage + IndexedDB
- Incremental sync (only fetch new records)
- Optimistic UI updates
- Partner/relation resolution
- PWA installability
- Offline functionality

## Available Commands:

### 🎯 Skill Shortcuts (Project Generation)
Create new PWA projects:
- `/new-svelte-pwa` - Generate SvelteKit PWA
- `/new-react-pwa` - Generate React PWA
- `/new-vue-pwa` - Generate Vue PWA
- `/add-model` - Add Odoo model to existing PWA
- `/create-cache-store` - Create cache store for a model

### 🔧 Workflow Commands
Development and deployment:
- `/init-project` - Initialize new PWA project
- `/setup-env` - Configure environment variables
- `/test-connection` - Test Odoo API connection
- `/deploy-vercel` - Deploy to Vercel
- `/deploy-github` - Deploy to GitHub Pages

### 📚 Documentation Commands
Help and reference:
- `/help` - This help document (you are here!)
- `/examples` - Real-world usage examples
- `/architecture` - Explain PWA architecture
- `/api-reference` - Odoo API client documentation
- `/troubleshoot` - Common issues and solutions

### 🛠 Maintenance Commands
Project management:
- `/update-deps` - Update project dependencies
- `/fix-sync` - Diagnose and fix sync issues
- `/clear-cache` - Clear application caches
- `/add-deployment` - Add new deployment target
- `/optimize` - Run optimization checks

## Common Workflows:

### 1️⃣ Starting a New Project
```
1. /new-svelte-pwa (or /new-react-pwa or /new-vue-pwa)
2. Provide project details (name, model, etc.)
3. /init-project
4. Start coding!
```

### 2️⃣ Setting Up Environment
```
1. /setup-env
2. Provide Odoo credentials
3. /test-connection
4. Verify everything works
```

### 3️⃣ Adding More Models
```
1. /add-model
2. Specify model name and details
3. Test CRUD operations
4. Customize UI as needed
```

### 4️⃣ Deploying to Production
```
1. /deploy-vercel (recommended)
   OR /deploy-github
2. Configure environment variables
3. Test deployed application
4. Set up custom domain (optional)
```

### 5️⃣ Troubleshooting Issues
```
1. /test-connection - Check Odoo connectivity
2. /troubleshoot - Find specific solutions
3. /fix-sync - Diagnose sync problems
4. /clear-cache - Reset if needed
```

## Quick Start Guide:

### Step 1: Generate a New PWA
Choose your framework and run the appropriate command:
```
/new-svelte-pwa
```

### Step 2: Provide Project Details
When prompted, provide:
- **Project name**: e.g., "expense-tracker"
- **Odoo model**: e.g., "expense" (without x_ prefix)
- **Display name**: e.g., "Expense"
- **Deployment target**: e.g., "vercel" (optional)

### Step 3: Initialize the Project
```
cd your-project-name
/init-project
```

### Step 4: Configure Odoo Connection
```
/setup-env
```
Provide your Odoo URL, database, API key, and username.

### Step 5: Test Everything
```
/test-connection
```
Verify your Odoo connection works correctly.

### Step 6: Start Developing
The dev server should be running. Open your browser and start customizing!

### Step 7: Deploy (when ready)
```
/deploy-vercel
```
Follow the prompts to deploy to production.

## Plugin Skills:

### create-odoo-pwa
Generates a complete PWA project from scratch.

**When to use**: Starting a new project

**What it generates**:
- Base configuration (package.json, vite.config, etc.)
- Odoo API client
- Cache stores with smart syncing
- Server-side API proxy
- UI components (forms, lists)
- PWA manifest and service worker
- Deployment configurations
- Complete documentation

### add-odoo-model
Adds integration for additional Odoo models.

**When to use**: Adding new data models to existing project

**What it generates**:
- Cache store for the new model
- API methods in Odoo client
- Form and list pages (optional)
- Navigation updates

### create-cache-store
Creates a standalone cache store.

**When to use**: Need custom caching logic

**What it generates**:
- Framework-specific cache store
- Smart caching logic
- Background sync
- Optimistic updates

## Best Practices:

### Security
- ✅ Keep API keys in `.env` file (never commit)
- ✅ Use different credentials for dev and production
- ✅ Set environment variables in hosting platform
- ✅ Rotate API keys periodically

### Development
- ✅ Test Odoo connection before coding
- ✅ Use version control (Git)
- ✅ Test offline functionality regularly
- ✅ Read generated CLAUDE.md for patterns

### Deployment
- ✅ Build and test locally first
- ✅ Use Vercel/Netlify for full functionality
- ✅ Set up continuous deployment from Git
- ✅ Monitor performance and errors

### Maintenance
- ✅ Keep dependencies updated
- ✅ Monitor Odoo API changes
- ✅ Test after Odoo upgrades
- ✅ Clear caches when schema changes

## Getting More Help:

### Example prompts to use this command:
- `/help` - Show this help document
- User: "How do I use the Odoo PWA plugin?"
- User: "What commands are available?"

### In Generated Projects:
- `README.md` - Getting started guide
- `CLAUDE.md` - Architecture patterns
- `API.md` - API client reference

### External Resources:
- Odoo API Documentation: https://www.odoo.com/documentation/
- SvelteKit: https://kit.svelte.dev/
- React: https://react.dev/
- Vue: https://vuejs.org/
- PWA Guide: https://web.dev/progressive-web-apps/

### Troubleshooting:
If you encounter issues:
1. Run `/test-connection` to diagnose
2. Check `/troubleshoot` for common solutions
3. Review browser console for errors
4. Verify Odoo configuration
5. Check generated documentation

### Support:
For bugs or feature requests:
- Check existing issues
- Review documentation thoroughly
- Provide detailed error messages
- Include environment details

## Framework-Specific Notes:

### SvelteKit (Recommended)
- Uses Svelte 5 runes syntax
- Server-side API routes work perfectly
- Best offline functionality
- Smallest bundle size
- Easiest to deploy

### React
- Modern React 18+ hooks
- Context API for state management
- Wide ecosystem support
- Popular and familiar

### Vue
- Vue 3 Composition API
- Pinia for state management
- Great developer experience
- Progressive framework

## Architecture Highlights:

### Data Flow
```
Component → Cache Store → API Client → Server Route → Odoo
```

### Caching Strategy
1. **Load from cache** (instant, may be stale)
2. **Check if stale** (> 5 minutes)
3. **Background sync** (fetch new data)
4. **Update cache** (localStorage + IndexedDB)
5. **Reactive update** (UI updates automatically)

### Sync Strategy
1. **Incremental fetch** - Only `id > lastRecordId`
2. **Partner resolution** - Batch fetch related records
3. **Optimistic updates** - UI updates before server
4. **Error recovery** - Graceful offline handling

## Tips and Tricks:

💡 **Use the right command for the job**
- Quick start? `/new-svelte-pwa`
- Need help? `/help` or `/troubleshoot`
- Deploy ready? `/deploy-vercel`

💡 **Test early and often**
- Run `/test-connection` after setup
- Test offline mode frequently
- Verify sync works correctly

💡 **Read the generated docs**
- CLAUDE.md has architecture details
- API.md has client method docs
- README.md has setup instructions

💡 **Customize to your needs**
- Start with generated code
- Modify UI components
- Add business logic
- Extend with new features

💡 **Deploy with confidence**
- Test build locally first
- Use environment variables properly
- Monitor after deployment
- Set up error tracking

## Summary:
The odoo-pwa-generator plugin makes it easy to create production-ready PWAs with Odoo integration. Use the commands above to generate, develop, deploy, and maintain your applications.

For more details on any command, just run that command and follow the prompts!

Happy coding! 🚀