# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Quick Reference & Best Practices

### 📚 Documentation
For comprehensive information, see:
- **[docs/README.md](docs/README.md)** - Overview and navigation
- **[docs/CONFIGURATION.md](docs/CONFIGURATION.md)** - System configuration and architecture
- **[docs/DEVELOPMENT-GUIDE.md](docs/DEVELOPMENT-GUIDE.md)** - Development standards and workflow
- **[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** - Common issues and solutions
- **[docs/API-REFERENCE.md](docs/API-REFERENCE.md)** - Complete API documentation

### 🚀 Deployment Guidelines
- **ALWAYS** use `scripts/deploy.sh staging` for staging deployments
- **NEVER** deploy to production without explicit user request
- **ALWAYS** run `bin/pre-deployment-check.sh` before any deployment
- **ALWAYS** verify deployment with `scripts/verify-plugin-fixes.sh`
- Production deployments require double confirmation

### 🎯 WordPress Best Practices

#### Security First
```php
// Always escape output
echo esc_html($user_input);
echo esc_url($link);
echo esc_attr($attribute);

// Always sanitize input
$clean_data = sanitize_text_field($_POST['data']);
$clean_email = sanitize_email($_POST['email']);

// Always verify nonces
wp_verify_nonce($_POST['nonce'], 'action_name');

// Always check capabilities
if (!current_user_can('required_capability')) {
    wp_die('Insufficient permissions');
}
```

#### Code Standards
- Follow WordPress Coding Standards
- Use prefixed function/class names (`HVAC_`)
- Never use PHP namespaces (WordPress compatibility)
- Always include WordPress header/footer in templates
- Use singleton pattern for main classes

#### Performance
- Cache expensive queries with `wp_cache_get/set`
- Load assets only on plugin pages
- Use conditional loading in `HVAC_Scripts_Styles`
- Optimize database queries

#### Theme Integration
- Plugin includes Astra theme integration
- All plugin pages force full-width layout
- Sidebar removal handled automatically
- Body classes added: `hvac-plugin-page`, `hvac-astra-integrated`

### 🔧 Development Workflow

#### Making Changes
1. Create feature branch: `git checkout -b feature/description`
2. Follow commit conventions: `feat:`, `fix:`, `docs:`, etc.
3. Test thoroughly on staging
4. Update documentation if needed
5. Deploy to staging: `scripts/deploy.sh staging`

#### Testing
- Use Playwright E2E tests: `npm test`
- Manual testing checklist in docs/DEVELOPMENT-GUIDE.md
- Always test with different user roles
- Verify mobile responsiveness

#### User Roles
- **hvac_trainer**: Standard trainer capabilities
- **hvac_master_trainer**: Advanced trainer with aggregate reporting
- **Dual-role users**: Show only master trainer navigation (prevents duplicates)

### 🐛 Common Issues & Quick Fixes

#### Pages Not Found (404)
```bash
wp rewrite flush
wp eval 'HVAC_Page_Manager::create_required_pages();'
```

#### Missing CSS/Styling
- Check if `HVAC_Scripts_Styles` is loading
- Verify `is_plugin_page()` detection
- Ensure template has `HVAC_IN_PAGE_TEMPLATE` constant

#### Sidebar Still Showing
- Check Astra integration is active
- Force no-sidebar via post meta update
- Clear all caches

#### Profile Page Issues
```bash
# Update template assignment
wp post meta update [PAGE_ID] _wp_page_template templates/page-trainer-profile.php
```

### 📝 Critical Reminders

#### Template Requirements
- ALL templates MUST include `get_header()` and `get_footer()`
- ALL templates MUST define `HVAC_IN_PAGE_TEMPLATE` constant
- Use `container` class for consistent styling

#### URL Structure
- Hierarchical URLs: `/trainer/dashboard/`, `/trainer/profile/`, etc.
- Legacy URLs automatically redirect with 301 status
- Master trainer URLs: `/master-trainer/master-dashboard/`

#### Asset Management
- CSS/JS loaded conditionally via `HVAC_Scripts_Styles`
- jQuery in no-conflict mode always
- AJAX uses `hvac_ajax` object with proper nonces

#### Error Handling
- Always return proper AJAX responses (`wp_send_json_success/error`)
- Log errors appropriately (staging vs production)
- Use error codes from docs/API-REFERENCE.md

### 🚨 Never Do This
- ❌ Deploy to production without user request
- ❌ Skip pre-deployment validation
- ❌ Use `echo` without escaping
- ❌ Create standalone fixes outside plugin deployment
- ❌ Add debug code to production
- ❌ Modify core WordPress or theme files
- ❌ Use hardcoded paths or URLs

### ✅ Always Do This
- ✅ Run pre-deployment checks
- ✅ Test on staging first
- ✅ Escape all output
- ✅ Sanitize all input
- ✅ Verify user capabilities
- ✅ Use WordPress coding standards
- ✅ Update documentation when needed
- ✅ Clear caches after deployment

For detailed information on any topic, refer to the comprehensive documentation in the `docs/` directory.

## Memory Entries

- Do not make standalone 'fixes' which upload separate from the plugin deployment. Instead, always redeploy the whole plugin with your fixes. Before deploying, always remove the old versions of the plugin. Always activate and verify after plugin upload
- Always use the deployment scripts to upload, activate and verify plugins for code changes
- The deployment process now automatically clears Breeze cache after plugin activation through wp-cli. This ensures proper cache invalidation and prevents stale content issues.
- Communication Templates system uses a modal interface with JavaScript override after wp_footer() to ensure external JS doesn't conflict. Scripts load on communication-templates page only.
- When testing the UI, use playwright + screenshots which you inspect personally to verify that your features are working as intended.
- URL Structure: The plugin now uses hierarchical URLs (/trainer/, /master-trainer/) implemented in June 2025. All navigation, authentication, and template loading updated accordingly. Backward compatibility maintained with 301 redirects.
- **CSS Prevention System**: ALWAYS run bin/pre-deployment-check.sh before any deployment. This prevents broken templates from reaching users. All templates MUST have get_header()/get_footer() calls.
- **Deployment and Verification (2025-06-17)**: Use `scripts/deploy-to-staging.sh` for deployments. Always run `scripts/verify-plugin-fixes.sh` after deployment. Plugin must be reactivated to create missing pages. Legacy redirects working at 100% success rate. Certificate reports 404 issue resolved.
- **Plugin Fixes Status**: Certificate reports 404 error FIXED, legacy URL redirects enhanced and working 100%, duplicate shortcode registration removed, template URLs updated to hierarchical structure, comprehensive testing suite implemented.
- **Master Dashboard CSS Fix (2025-06-18)**: Master dashboard CSS was broken due to missing get_header()/get_footer() calls in template. FIXED by adding WordPress integration, comprehensive CSS variables framework (--hvac-spacing-*, --hvac-radius-*), 200+ lines of master dashboard styles, proper AJAX handlers, and responsive design. Prevention system implemented with template validation scripts.
- **Directory Reorganization (2025-06-18)**: Root directory reorganized for maintainability. Development artifacts moved to `archive/` directory with structured subdirectories. Essential files (.env, core plugin files) restored to root. Deployment scripts moved to `scripts/` directory. Plugin redeployed successfully after reorganization - all functionality verified working.
- **Test Data Seeding (2025-07-10)**: Updated all test data creation scripts to include JoeMedosch@gmail.com as a master trainer (password: JoeTrainer2025@) and joe@measurequick.com with both trainer and master trainer roles. Use `bin/create-comprehensive-test-data.sh` for complete staging setup. The main staging script `bin/create-staging-test-data.sh` also includes both Joe accounts. All seeding scripts now create test_trainer (regular trainer), JoeMedosch@gmail.com (master trainer), and assign dual roles to joe@measurequick.com automatically during staging deployment.
- **Complete End-to-End Testing (2025-07-15)**: Comprehensive testing suite implemented and verified on staging server. Event creation workflow fully functional with 6/6 essential form elements accessible, form submission working without errors, and data persistence verified. Certificate generation workflow 100% operational with 16 events available, 3 active download links returning HTTP 200 status, and complete event-certificate integration. All tests pass including authentication (100%), certificate interface (100%), event creation (form accessibility and submission), and data persistence across sessions. System production-ready with 85-90% test coverage achieved.
- **Master Dashboard User Role Fix (2025-07-23)**: Resolved critical issue where 11 HVAC trainers with legacy `event_trainer` roles were not appearing in the master dashboard. Root cause: master dashboard code only queried for `hvac_trainer` and `hvac_master_trainer` roles, missing users with the legacy `event_trainer` role from previous development. Solution: Migrated all 11 users from `event_trainer` to `hvac_trainer` role, increasing visible trainers from 4 to 15 in master dashboard. All legacy role artifacts cleaned up. Master dashboard now shows complete trainer statistics (15 total trainers, 16 total events) and all trainer data is properly accessible to master trainer users.
- **Admin Bar and Zoho CRM Enhanced Fixes (2025-07-23)**: Implemented robust fixes for admin bar hiding and Zoho CRM integration issues. Admin bar: Added multiple hook points (after_setup_theme, init, wp), centralized hiding function with global constant, PHP_INT_MAX priority filters, and user meta updates. Zoho CRM: Enhanced production detection with URL parsing, aggressive OAuth rewrite rule flushing with cache clearing, and improved refresh token handling. Both fixes include extensive debug logging. Deployed to staging.
- **Event Manage Page Toolbar (2025-07-23)**: Added navigation toolbar to /trainer/event/manage/ page to match other trainer pages. Includes Dashboard, Certificate Reports, and Generate Certificates buttons with consistent styling and responsive design. Uses hierarchical URL structure.
- **Trainer Page Redirects and Admin Bar Removal (2025-07-23)**: Added 301 redirects from /trainer/ to /trainer/dashboard/ and /master-trainer/ to /master-trainer/dashboard/. Removed admin bar hiding code as it's now handled by The Events Calendar plugin. Updated toolbar Dashboard link to use /trainer/dashboard/.
- **Production Error Fixes (2025-07-24)**: Fixed production logging issues: Removed all debug error_log statements, added duplicate checking for OAuth query vars to prevent 153+ additions, optimized admin script loading to specific page only. Significantly reduces log noise and improves performance.
- **Production Deployment Support (2025-07-24)**: Updated deployment infrastructure to support both staging and production environments. Use `scripts/deploy.sh staging` for staging deployments and `scripts/deploy.sh production` only when explicitly requested by the user. Production deployments require double confirmation to prevent accidental deployment. IMPORTANT: Only deploy to production when the user explicitly asks for production deployment.
- **Plugin Architecture Refactoring (2025-07-28)**: Implemented modular architecture with single-responsibility classes. Created HVAC_Shortcodes for centralized shortcode management, HVAC_Scripts_Styles for asset management, and HVAC_Route_Manager for URL routing. Eliminated duplicate functionality between HVAC_Plugin and HVAC_Community_Events. All components now use singleton pattern to prevent duplicate initialization. Fixed jQuery selector errors and duplicate content issues. See docs/ARCHITECTURE.md for details.
- **Master Dashboard URL Fix (2025-07-29)**: Fixed critical issue where master dashboard was showing trainer dashboard content. Root cause: Both trainer and master dashboards had the same page slug "dashboard", causing WordPress to load the wrong page. Solution: Changed master dashboard URL from `/master-trainer/dashboard/` to `/master-trainer/master-dashboard/`, updated all code references, removed conflicting legacy redirects. Master dashboard now correctly displays master trainer content with aggregate statistics and trainer performance analytics.
- **Event Manage Page CSS and Header Fix (2025-07-30)**: Resolved persistent CSS override and duplicate header issues on the trainer/event/manage/ page. Root causes: CSS specificity conflicts with theme styles, header being added via both template and tribe hook. Solution: Scoped all CSS rules to `.hvac-event-manage-wrapper`, moved navigation header directly into page template, disabled duplicate tribe hook, added theme override styles. Page now displays correctly with single header, proper 1200px max-width layout, 20px padding, and consistent styling matching other dashboard pages.
- **Major Plugin Update - Registration Refactor and New Trainer Pages (2025-07-30)**: Implemented comprehensive updates to HVAC plugin. Registration form refactored: moved Application Details to Personal Information, renamed Business Information to Training Organization Information with TEC integration, added required Organization Logo upload, added Headquarters location fields, created conditional Training Venue section. New trainer pages created: Training Venues system (/trainer/venue/list, /trainer/venue/manage) with full CRUD operations and TEC venue integration; Trainer Profile system (/trainer/profile, /trainer/profile/edit) with photo upload, certifications, stats tracking; Training Organizers system (/trainer/organizer/list, /trainer/organizer/manage) with logo upload and headquarters tracking. All systems use AJAX forms, real-time validation, responsive design, and proper WordPress/TEC integration.
- **Navigation Menu and Breadcrumb Systems (2025-07-30)**: Added comprehensive navigation system (class-hvac-trainer-navigation.php) with hierarchical menus, dropdown support, keyboard navigation, mobile hamburger menu, and active page highlighting. Implemented automatic breadcrumb system (class-hvac-breadcrumbs.php) with SEO-friendly Schema.org markup, URL-based trail generation, and multiple style options. Both systems ready for template integration.
- **Staging Deployment and Testing (2025-07-30)**: Successfully deployed all trainer features to staging. Created test users (test_trainer/TestTrainer123!, test_master/TestMaster123!). Registration form changes verified live. 71% test pass rate with 4/7 trainer pages accessible. Outstanding issues: HQ fields not visible on registration, some pages need manual creation, navigation/breadcrumb template integration required.
- **Navigation and Layout Fixes (2025-08-01)**: Resolved three critical UI issues: (1) Dual-role users now show only master trainer navigation to prevent duplicate menus, implemented in HVAC_Menu_System by detecting master trainer role and always returning master menu structure. (2) Removed 2-column sidebar layout on all dashboard pages through enhanced HVAC_Astra_Integration with aggressive CSS overrides, forced no-sidebar meta updates, and complete sidebar removal filters. (3) Fixed profile page template assignment to use new template with proper navigation and breadcrumbs. All fixes deployed to staging and verified through automated tests - dashboard shows single navigation in full-width layout, profile page uses new template with correct styling.
- **Role Field and Certification System Implementation (2025-08-01)**: Added comprehensive user role field to registration, profile display, and profile edit with 10 role options (technician, installer, supervisor, manager, trainer, consultant, sales representative, engineer, business owner, other). Implemented advanced certification tracking system with three meta fields: date_certified (date picker), certification_type (dropdown with "Certified measureQuick Trainer" and "Certified measureQuick Champion"), and certification_status (status badges for Active/Expired/Pending/Disabled). Features sophisticated role-based access control where regular trainers see read-only certification fields while administrators and master trainers have full edit access. All 25 users automatically migrated with appropriate default values during plugin activation. System includes professional CSS styling with color-coded status badges, comprehensive server-side validation, and complete E2E test coverage. Documentation updated with access control patterns and API reference.
- **Certificate Pages Template System Fix (2025-08-01)**: Resolved critical issue where certificate pages (/trainer/certificate-reports/, /trainer/generate-certificates/) were completely bypassing WordPress template system, showing only bare shortcode content without theme headers, navigation, or styling. Root cause: load_custom_templates() method in class-hvac-community-events.php was loading content-only templates from templates/certificates/ instead of proper page templates. Solution: Updated template paths to use templates/page-certificate-reports.php and templates/page-generate-certificates.php with full WordPress integration. Fixed duplicate breadcrumbs by adding aggressive Astra theme breadcrumb disable filters in HVAC_Astra_Integration class. Resolved missing navigation menu by removing problematic HVAC_NAV_RENDERED constant checks in page templates. Certificate pages now display with complete theme integration: proper headers/footers, single set of breadcrumbs, full navigation menu, and consistent styling. All fixes deployed to staging and verified working.

[... rest of the existing content remains unchanged ...]