# CLAUDE.md

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

## Project Overview

HVAC Community Events is a WordPress plugin extending The Events Calendar (TEC) suite to create a trainer community platform. It provides custom user roles (`hvac_trainer`, `hvac_master_trainer`), event management, certificate generation, venue/organizer management, and Zoho CRM integration.

- **Entry Point**: `hvac-community-events.php`
- **Core Classes**: `includes/class-*.php` (all use singleton pattern)
- **Templates**: `templates/page-*.php`
- **TEC Integration**: Events, venues, organizers via The Events Calendar suite

## Commands

### Deployment
```bash
# Pre-deployment validation (ALWAYS run first)
scripts/pre-deployment-check.sh

# Deploy to staging
scripts/deploy.sh staging

# Deploy to production (requires explicit user request and confirmation)
scripts/deploy.sh production
```

### Testing
```bash
# Start Docker test environment
docker compose -f tests/docker-compose.test.yml up -d

# E2E tests (headless)
HEADLESS=true BASE_URL=http://localhost:8080 node test-master-trainer-e2e.js
HEADLESS=true BASE_URL=http://localhost:8080 node test-comprehensive-validation.js

# E2E tests (headed - requires display)
DISPLAY=:0 XAUTHORITY=/run/user/1000/.mutter-Xwaylandauth.U8VEB3 node test-master-trainer-e2e.js
```

### WordPress CLI (on server via SSH)
```bash
wp rewrite flush
wp eval 'HVAC_Page_Manager::create_required_pages();'
wp eval 'wp_set_password("Password123", USER_ID);'  # Reset password (more reliable than wp user update)
```

### Staging Environment
```bash
# SSH access
ssh roodev@146.190.76.204
cd /home/974670.cloudwaysapps.com/uberrxmprk/public_html

# Test account (staging)
Username: test_master | Password: TestPass123 | Role: hvac_master_trainer
```

## Architecture

### Singleton Pattern (MANDATORY)
All core classes use the singleton pattern. Never assume static methods exist:

```php
// CORRECT
echo HVAC_Breadcrumbs::instance()->render_breadcrumbs();
HVAC_Venues::instance()->get_venues();

// WRONG - will fail
HVAC_Breadcrumbs::render();
```

### Template Requirements
All page templates MUST include:
```php
<?php
defined('ABSPATH') || exit;
define('HVAC_IN_PAGE_TEMPLATE', true);
get_header();
// ... content ...
get_footer();
```

### Security Patterns
```php
// Input sanitization
$trainer_id = absint($_POST['trainer_id']);
$email = sanitize_email($_POST['email']);

// Output escaping
echo esc_html($trainer_name);
echo esc_url($profile_url);

// Nonce verification
wp_verify_nonce($_POST['nonce'], 'hvac_action');

// Role checking (use roles, not capabilities)
$user = wp_get_current_user();
if (!in_array('hvac_trainer', $user->roles)) {
    wp_die('Access denied');
}
```

### File Structure
```
includes/
├── class-hvac-plugin.php          # Main controller (singleton)
├── class-hvac-shortcodes.php      # Shortcode management
├── class-hvac-scripts-styles.php  # Asset management
├── class-hvac-route-manager.php   # URL routing
├── class-hvac-venues.php          # Venue CRUD (singleton)
├── class-hvac-organizers.php      # Organizer management (singleton)
├── class-hvac-training-leads.php  # Lead tracking (singleton)
├── admin/                         # Admin classes
├── certificates/                  # Certificate generation
├── communication/                 # Email templates
├── zoho/                          # Zoho CRM integration
└── find-trainer/                  # Public trainer directory

templates/page-*.php               # Page templates (hierarchical URLs)
assets/{css,js}/                   # Frontend assets
tests/                             # Docker environment and E2E tests
scripts/                           # Deployment and maintenance scripts
```

### URL Structure
- Trainer: `/trainer/dashboard/`, `/trainer/event/manage/`, `/trainer/certificate-reports/`
- Master Trainer: `/master-trainer/dashboard/`, `/master-trainer/trainers/`
- Public: `/training-login/`, `/find-a-trainer/`

## Critical Warnings

### NEVER Do
- Deploy to production without explicit user request
- Skip pre-deployment validation (`scripts/pre-deployment-check.sh`)
- Use static method calls without verifying singleton pattern
- Re-enable monitoring infrastructure (causes PHP segmentation faults)

### Disabled Systems (DO NOT RE-ENABLE)
The following monitoring systems are PERMANENTLY DISABLED due to causing PHP segmentation faults:
`HVAC_Background_Jobs`, `HVAC_Health_Monitor`, `HVAC_Error_Recovery`, `HVAC_Security_Monitor`, `HVAC_Performance_Monitor`, `HVAC_Backup_Manager`, `HVAC_Cache_Optimizer`

## Zoho CRM Integration

Located in `includes/zoho/`. Maps WordPress data to Zoho CRM:
- Events → Campaigns
- Trainers → Contacts
- Attendees → Contacts + Campaign Members
- RSVPs → Leads + Campaign Members

**Admin Page**: `/wp-admin/admin.php?page=hvac-zoho-sync`

**Important**: Staging environment blocks all write operations to Zoho CRM. Only production can sync data.

## Docker Test Environment

```bash
docker compose -f tests/docker-compose.test.yml up -d

# Services:
# WordPress 6.4 (PHP 8.2): http://localhost:8080
# MySQL 8.0: port 3307
# Redis 7: port 6380
# Mailhog: http://localhost:8025
# PhpMyAdmin: http://localhost:8081
```

## Technical Debt

### TEC Community Events Dependency
The plugin still relies on "The Events Calendar: Community" (TEC CE) for event creation/editing forms via `[tribe_community_events]` shortcode. While `HVAC_Event_Manager` has custom CRUD capabilities, production code paths use TEC CE.

**Removal estimate:** 9-14 days of development work.
**Details:** See [docs/reports/TEC-COMMUNITY-EVENTS-DEPENDENCY-ANALYSIS.md](docs/reports/TEC-COMMUNITY-EVENTS-DEPENDENCY-ANALYSIS.md)

**Status:** Deferred - Current implementation is functional and stable.

## Key Documentation

- **[Status.md](Status.md)** - Current project status and recent changes
- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** - System architecture details
- **[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** - Common issues and solutions
- **[docs/TESTING-GUIDE.md](docs/TESTING-GUIDE.md)** - Testing procedures

## AI Assistant Tools

### Zen MCP Tools (Use Throughout Every Session)
- **Zen Debug**: Use whenever you encounter an error or unexpected behavior
- **Zen Code Review**: Use whenever you finish a significant piece of code or feature
- **Zen Analyze**: Use before adding new features or making significant changes to existing code
- **Zen Deepthink**: Use when you have a complex problem to solve or need to brainstorm ideas
- **Zen Chat**: Use for general questions, clarifications, or when you need assistance with a task

**Important Context Reminder**: Remind the Zen tools that this is a small local environment with a single user, so security and scalability are not primary concerns.

### Clink Multi-Model Workflows (GPT-5, Gemini 3, Kimi K2.5)

Use `mcp__zen__clink` to get diverse AI perspectives via external CLIs. Available CLIs:
- **codex**: GPT-5 - Fast, precise code understanding
- **gemini**: Gemini 3 - Large context (1M tokens), thorough analysis
- **Kimi K2.5** (via `mcp__zen__chat` with OpenRouter) - Strong reasoning, excellent at complex logic

**Security Warning:** Files are sent to OpenAI, Google, and Moonshot AI. NEVER use on `.env`, credentials, or regulated data.

**When to Use Multi-Model:**
- Code reviews (catch different types of issues)
- Complex debugging (multiple hypotheses)
- Architecture decisions (diverse perspectives)
- Planning (compare approaches)

**Available Skills:**
- `/multi-review <files>` - Code review from all 3 models
- `/multi-plan <task>` - Planning perspectives from all 3 models
- `/multi-debug <issue>` - Parallel bug investigation
- `/multi-analyze <files>` - Comprehensive analysis

**Quick Usage** (all three calls in one message = parallel execution):
```python
review_prompt = "Review for bugs and security issues"
mcp__zen__clink(prompt=review_prompt, cli_name="codex", role="codereviewer", absolute_file_paths=["/absolute/path/file.py"])
mcp__zen__clink(prompt=review_prompt, cli_name="gemini", role="codereviewer", absolute_file_paths=["/absolute/path/file.py"])
mcp__zen__chat(prompt=review_prompt + " Use Kimi K2.5 via OpenRouter for this analysis.", absolute_file_paths=["/absolute/path/file.py"])
```

**Important:** Use absolute paths (not globs). Resolve patterns first: `find src -name "*.py" | xargs realpath`

**Synthesis Format:** After multi-model analysis, report:
1. **Consensus** - All models agree
2. **Majority** - 2/3 agree (note dissent)
3. **Unique insights** - Model-specific findings
4. **Recommended actions** - Prioritized by consensus

**Roles:** Each CLI supports `default`, `codereviewer`, `planner`