[eli-r-ph]

💡 Motivation and Context

A review of the v2 migration guide against the v1 code found upgrade risks the guide didn't mention, a changeset that contradicts the code, and two rule gaps. The biggest guide gap: DefaultEventOptions, request-context options and a $process_person_profile default now reach Identify, Alias and GroupIdentify, so a personless default makes PostHog drop those events with no Callback report.

Changes

• Guide: warn about the personless default on person-only messages, whitespace-only ids returning FieldError, log text changes, AI lane settings that are not inherited, Alias/Backoff no longer comparable with ==, and the proxy Authorization rule.
• Changeset: replace "429 is no longer retried" with the real retry list (404, 408, 429, 500, 502, 503, 504 and network errors).
• A panicking BeforeSend now logs the event name and the panic's type, never the panic value, which can hold the data the hook was removing.
• Config.Validate rejects a negative CaptureAIBatchUploadTimeout (it meant no timeout) and CaptureAIMaxQueueSize (it quietly became the default).

💚 How did you test it?

• New test for the panic log across all five message types; it fails on the old code.
• TestConfigRejectsNegativeKnobs covers both new fields.
• go test ./..., go vet ./..., gofmt, go mod tidy and make api-diff pass.

📝 Checklist

• All commits are signed (see Commit signing)
• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran pnpm changeset to generate a changeset file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

• Written with Claude Code (claude-opus-5-5) from a review of the guide and changesets against v1 and the capture service.

🤖 Generated with Claude Code

[marandaneto]

The code looks good; no qualifying findings. Verdict: correct.