docs: agree on public API changes before implementing them

[turnipdabeets]

Problem

On contributor PRs we sometimes only settle the public API after several rounds of implementation review. By then the contributor, or their agent, has built each suggestion along the way, and a late change of direction wastes their work.

Contributors' agents read AGENTS.md and CONTRIBUTING.md, but neither says anything about public API.

Changes

• CONTRIBUTING.md: new "Public API changes" section. Agree on the API shape on the issue before implementing, check existing hooks like before_send first, and treat a reviewer's API suggestion as a question rather than an instruction. Agents are told to stop and ask.
• AGENTS.md: one line pointing agents to that section. It's a pointer rather than a copy, since AGENTS.md asks to keep shared guidance in CONTRIBUTING.md.

This PR started as a workflow that labels PRs that change the public API. We dropped it: on fork PRs, CI waits for maintainer approval, so the label would only show up after the first review. The earliest points we can reach are the contributor's agent and the issue, and that's what this covers.

Release info Sub-libraries affected

Libraries affected

None. Docs only.

Checklist

• Tests for new code
• Accounted for the impact of any changes across different platforms
• Accounted for backwards compatibility of any changes (no breaking changes!)
• Took care not to unnecessarily increase the bundle size

If releasing new changes

• Ran pnpm changeset to generate a changeset file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

• Written with Claude Code, following a team discussion about agreeing on API direction internally, with one point of contact, before steering a contributor.
• A pull_request_target workflow that labels public API changes was built and dry-run against recent PRs, then removed. It only fires once the reference files are committed, which on fork PRs happens after CI is approved, so it can't beat the first review.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XxW4HJTg29pzv7iGnVBqwS

[github-actions]

📝 No Changeset Found

This PR doesn't include a changeset. A changeset is required to release a new version.

How to add a changeset

Run this command and follow the prompts:

pnpm changeset

Remember: Never use major version bumps for posthog-js as it's autoloaded by clients.

[greptile-apps]

Prompt To Fix All With AI

### Issue 1
CONTRIBUTING.md:292
**Reference changes are not definitive**

Generated reference files include non-API metadata beyond descriptions, such as each declaration's source `path`. Moving an unchanged declaration between files can therefore satisfy this rule and unnecessarily send contributors through the public API approval workflow. Treat the generated diff as a signal to inspect rather than proof that the API changed.

```suggestion
If `pnpm generate-references` changes anything other than descriptions in a `*-references-latest.json` file, inspect the generated diff to determine whether your change touches public API; these files also contain non-API metadata.
```

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "docs: point to SDK guidelines and sugges..." | Re-trigger Greptile}

[marandaneto]

bot has a comment otherwise lgm