# BW Lead Attribution Intelligence — Claude Development Guide

**Version:** 1.0.1 | **Last Updated:** 2026-04-13

## What this plugin does

Capture traffic source, attribute it to every lead, and understand where your leads are coming from.

## Before making changes

1. Read `docs/SESSION-LOG.md` for recent context.
2. Read `docs/HANDOFF-NOTES.md` for any pending async messages.
3. Read `docs/SPEC.md` for current requirements.
4. Check `docs/KNOWN-ISSUES.md` for active bugs and workarounds.

## Versioning Protocol

- **Patch (X.Y.Z):** Bug fix or small iteration within a task.
- **Minor (X.Y.0):** New feature or task completion.
- **Major (X.0.0):** Breaking change or major release.

Bump via: `../../tools/bump-version.sh bw-lead-ai <new-version>`

Every version bump must update:
1. Plugin header `Version:` field in `bw-lead-ai.php`
2. `BW_LEAD_AI_VERSION` constant
3. `CHANGELOG.md` entry
4. `CLAUDE.md` header (this file)

The release script will refuse to release if these don't match.

## Session Protocol

- **Session start:** read this file, `docs/SESSION-LOG.md`, `docs/HANDOFF-NOTES.md`.
- **During session:** record significant changes, decisions, blockers in `docs/SESSION-LOG.md`.
- **Session end:** update `docs/SESSION-LOG.md` with a summary.

## Architecture Quick Reference

- Main file: `bw-lead-ai.php`
- Core classes: `includes/class-bw-lead-ai-*.php`
- Admin UI: `admin/`
- Frontend assets: `assets/`
- Docs: `docs/`
- Vendored libs: `vendor/`

## Release Checklist

See `../../docs/RELEASE-PROCESS.md` for the full process. Summary:

1. Bump version (`../../tools/bump-version.sh bw-lead-ai <version>`)
2. Update `CHANGELOG.md` with the actual changes
3. Run `../../tools/cleanup-scan.sh bw-lead-ai` until clean
4. Run `../../tools/security-scan.sh bw-lead-ai` until clean
5. Run `../../tools/test-plugin.sh bw-lead-ai` until clean
6. Run `../../tools/release.sh bw-lead-ai <version>`

## Never

- Edit `vendor/` (third-party code).
- Commit secrets to any file.
- Release with a dirty cleanup-scan.
- Modify release manifests on the dist host directly.