upskill-event-manager/CLAUDE.md

# 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 system that enables independent trainers to manage their own events, sell tickets, and track performance without accessing the WordPress admin panel. It extends The Events Calendar (TEC) plugin suite with custom functionality for the HVAC training industry.

The system uses a Cloudways staging environment for development and testing, with comprehensive Playwright E2E tests and PHPUnit tests. The project has migrated from Docker-based local development to a staging-only workflow.

## Key Commands

### Testing
```bash
# Recommended test workflow (execute from wordpress-dev/)

# 1. Always deactivate/reactivate plugin before testing
# This ensures hooks fire properly and rewrite rules are flushed
./bin/run-tests.sh --e2e

# 2. Set up test users
./bin/create-test-users.sh

# 3. Create test events (if needed for certificate tests)
./bin/create-test-events-admin.sh

# Run complete trainer journey tests
npx playwright test tests/e2e/trainer-journey-final.test.ts

# Run with visual browser for debugging
npx playwright test tests/e2e/trainer-journey-final.test.ts --headed

# Run with Playwright debugger
npx playwright test tests/e2e/trainer-journey-final.test.ts --debug

# Run specific test types
./bin/run-tests.sh --unit
./bin/run-tests.sh --e2e
./bin/run-tests.sh --integration

# Debug certificate system
./bin/debug-certificate-system.sh

# Debug dashboard data directly on server
./bin/debug-dashboard-live.sh

# Run specific E2E test suites
./bin/run-tests.sh --e2e --grep @login
./bin/run-tests.sh --e2e --grep @dashboard
./bin/run-tests.sh --e2e --grep @create-event
./bin/run-tests.sh --e2e --grep @event-summary
./bin/run-tests.sh --e2e --grep @modify-event
./bin/run-tests.sh --e2e --grep @certificate

# Run certificate-specific tests
npx playwright test tests/e2e/certificates.test.ts
npx playwright test tests/e2e/certificate-generation-checked-in.test.ts

# Run certificate filtering tests with interactive script
./bin/test-certificate-filter.sh

# Optimize and analyze E2E testing infrastructure
./bin/optimize-e2e-tests.sh

# Run help system tests
npx playwright test tests/e2e/help-system-welcome-guide.test.ts
npx playwright test tests/e2e/help-system-tooltips.test.ts
npx playwright test tests/e2e/help-system-documentation.test.ts
npx playwright test tests/e2e/help-system-integration.test.ts

# Run all help system tests
npx playwright test tests/e2e/help-system-*.test.ts

# Run PHPUnit tests on staging
./bin/run-staging-unit-tests.sh
./bin/run-staging-unit-tests.sh --testsuite unit
./bin/run-staging-unit-tests.sh --coverage-html ./coverage-report
./bin/run-staging-unit-tests.sh --filter=test_get_total_events_count

# Setup staging test users and verification
./bin/setup-staging-test-users.sh
./tests/run-tests.sh setup
./tests/run-tests.sh verify
./tests/run-tests.sh teardown --force

# Common testing issues & solutions:
# 1. Missing plugin admin menu: Re-activate plugin and check error logs
# 2. Selector issues: Review the testing strategy for stable selector patterns
# 3. Login redirect issues: Ensure proper test user setup 
# 4. Test independence: Each test should create its own test data
# 5. Wait for page load: Use explicit waits with waitForLoadState('networkidle')
```

### Deployment & Staging
```bash
# Deploy plugin to staging
./bin/deploy-plugin.sh

# Deploy to production
./deploy.sh --config deploy-config.sh

# Deploy and run tests
./deploy.sh --config deploy-config.sh --run-tests

# Verify staging environment
./bin/verify-staging.sh

# Deploy config to staging
./bin/deploy-config-staging.sh

# Sync data from staging
./bin/sync-staging.sh

# Staging workflow sequence
deploy-config-staging.sh → configure-staging-tests.sh → run-staging-tests.sh
```

### Memory Management System
```bash
# Update knowledge graph after deployment
./deploy.sh --config deploy-config.sh --update-memory

# Generate action items after testing
cd tests && ./run-tests.sh --generate-action-items
```

## 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
- The deployment process now automatically clears Breeze cache after plugin activation through wp-cli. This ensures proper cache invalidation and prevents stale content issues.

## Help System Implementation

The HVAC Community Events plugin includes a comprehensive help system with three main components:

### Features
1. **Interactive Welcome Guide**: Modal with 4 cards that appears on first login, includes navigation controls and cookie-based dismissal
2. **Tooltips System**: Contextual help throughout custom pages with hover activation and positioning
3. **Documentation Page**: Complete step-by-step directions and FAQs accessible via dashboard navigation

### Files
- `includes/class-hvac-help-system.php`: Core help system functionality
- `assets/css/hvac-help-system.css`: Styling for modals, tooltips, and documentation
- `assets/js/hvac-help-system.js`: JavaScript for interactive elements and navigation
- `tests/e2e/help-system-*.test.ts`: Comprehensive E2E test suite (40+ test cases)

### Recent Fixes (2025-05-22)
- Removed duplicate 'My Events' button from dashboard navigation
- Removed duplicate 'Help' link while maintaining tooltip functionality
- Fixed 'Create Event' page showing shortcode instead of form by implementing custom shortcode handler
- Fixed 'Certificate Reports' critical error by removing problematic debug statements
- Enhanced dashboard with proper tooltips and contextual help

## Architecture Overview

[... rest of the file remains unchanged ...]