# CLAUDE.md

Follow `AGENTS.md` for repository policy. Keep this file synced with `AGENTS.md` when repo-wide guidance changes.

## Source Of Truth
- This is a WordPress plugin. Use `seo-ai-audit-tool.php`, `functions.php`, `includes/`, and `readme.md` for detailed implementation context.
- Before changing third-party API/SDK code, use Ref MCP first. For WordPress, Google Search Console, Ahrefs, OpenAI, DataTables, and Chart.js behavior, use official vendor docs if Ref is unavailable and cite the fallback.

## Stack
- WordPress plugin bootstrapped by `seo-ai-audit-tool.php`.
- Namespaced PHP classes under `SEO_Audit_Tool` with a loader, DB layer, models, views, controllers, services, helpers, utils, and traits.
- Assets are traditional plugin JS/CSS served from `assets/`; there is no repo-local JS build system documented here.
- Main integrations: Google Search Console imports, Ahrefs imports, OpenAI-powered analysis, Yoast metadata compatibility, DataTables, and Chart.js.

## Commands
- There is no documented root build/test pipeline; edit PHP/CSS/JS directly and validate in WordPress.
- Syntax check touched PHP files: `php -l path\\to\\file.php`
- If PHPCS is available in the host environment: `phpcs --standard=WordPress path\\to\\file.php`
- Manual validation is required in a local/staging WP site with the plugin activated.

## Repo Map
- `seo-ai-audit-tool.php`: plugin bootstrap, constants, class loading, activation/migration hooks, and initialization checks.
- `functions.php`: shared helpers, sanitization/HTML allowlists, and file-version helpers.
- `includes/class-seo-audit-db.php`: custom DB tables and versioned migrations.
- `includes/class-seo-audit-loader.php`: WordPress hooks/filter registration.
- `includes/controllers/class-seo-audit-controller.php`: admin flow coordination.
- `includes/class-seo-audit-ajax.php`: AJAX handlers.
- `includes/class-seo-bulk-fix-dashboard.php`: bulk-fix workflows.
- `includes/class-seo-audit-*-finder.php`, `*-analyzer.php`, `*-optimizer.php`: feature modules such as keyword finder, CTR booster, backlinks, prune finder, and AI bot optimizer.
- `includes/models/`, `includes/views/`, `includes/services/`, `includes/utils/`, `includes/helpers/`, `includes/traits/`: supporting app layers.

## Hard Guardrails
- Start PHP files with the existing WordPress direct-access guard.
- Keep `SEOAUDP_DB_VERSION` changes paired with the actual DB create/migration logic; do not bump the version constant without the migration path.
- Preserve the plugin bootstrap's required-class checks so missing files fail with an admin notice rather than a fatal.
- Protect AJAX/admin mutations with nonce verification plus capability checks.
- Use `$wpdb->prepare()` for dynamic SQL, sanitize request data, and escape output in views.
- Treat Google Search Console, Ahrefs, OpenAI, and Yoast integration points as external contracts. Verify current field names and request/response behavior before changing them.
- Keep debug logging behind the existing `SEOAUDP_DEBUG_ENABLED` / option gates.
- Do not paste sample SEO datasets, imported CSV rows, API keys, tokens, or customer/site data into docs, fixtures, or logs.

## Common Workflows
- DB/table change: update `includes/class-seo-audit-db.php`, any callers, and the version/migration path together; verify activation/upgrade on a copy of site data.
- Admin/AJAX change: update controller/view/AJAX handlers together and test both happy-path and unauthorized/invalid-nonce flows.
- Feature-module change: update the module plus any shared model/view/helper code it relies on, then smoke the linked admin page.
- Asset/UI change: edit the plugin asset directly, then confirm it loads on the intended admin screen without cached stale files.

## Developer QA Checklist
- Run `php -l` on every touched PHP file.
- In a local/staging WP site, load the affected admin pages and confirm no PHP warnings/fatals are written to the WP debug log.
- For DB changes, deactivate/reactivate or run the normal upgrade path and verify the expected tables/columns/options exist afterward.
- For import/AI/integration changes, test one known data import or analysis flow end-to-end and confirm failures surface clearly in the admin UI.