docs: Refresh and simplify SDK agent guidance

[marandaneto]

💡 Motivation and Context

The review rule can incorrectly flag an external API change that already has an API-defining published SDK spec. The contributor-guide inventory also repeats guidance available through its link.

Clarify that an API-defining published SDK spec satisfies the external contributor review agreement. Remove the contributor-guide section inventory while retaining maintainer verification, issue consent, and changed-behavior-only spec checks.

💚 How did you test it?

Checked local Markdown links, exact Git path casing, anchors, code fences, whitespace, changed-file scope, and preservation of the API approval and scoped spec-review rules. SDK runtime builds and tests were not run for this documentation-only change. Autoreview was skipped because every changed file is documentation.

📝 Checklist

• I reviewed the submitted changes.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

No SDK code changes. Runtime tests and release changesets are not needed for this documentation-only PR.

If releasing new changes

• Ran pnpm changeset to generate a changeset file

Not applicable. This PR does not release SDK changes.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Tools: Pi, Git, and GitHub CLI. The SDK-wide documentation audit used Pi subagents for implementation and independent reviews. The human driver approved the audit and simplification plan. Useful details were moved to focused local guides rather than deleted. Human review is still required. No public session link is available.

[greptile-apps]

[Low risk] Updates guidance text in the agent instructions document.

The documentation change appears safe to merge.

_{Reviews (1) · Last reviewed commit: "docs: Refresh and simplify SDK agent gui..."}

[github-actions]

posthog-ruby-sync Compliance Report

Date: 2026-10-05T08:50:16.482140+00:00
Duration: 94069ms

⚠️ Some Tests Failed

45/47 tests passed, 2 failed

---

Capture Tests

⚠️ 29/30 tests passed, 1 failed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	10ms
Format Validation.Event Has Uuid	✅	7ms
Format Validation.Event Has Lib Properties	✅	6ms
Format Validation.Distinct Id Is String	✅	10ms
Format Validation.Token Is Present	✅	7ms
Format Validation.Custom Properties Preserved	✅	7ms
Format Validation.Event Has Timestamp	✅	8ms
Format Validation.Non Utc Event Timestamp Is Converted To Utc	✅	7ms
Retry Behavior.Retries On 503	✅	5352ms
Retry Behavior.Does Not Retry On 400	✅	2010ms
Retry Behavior.Does Not Retry On 401	✅	2010ms
Retry Behavior.Respects Retry After Header	✅	8014ms
Retry Behavior.Implements Backoff	✅	15246ms
Retry Behavior.Retries On 500	✅	5149ms
Retry Behavior.Retries On 502	✅	5145ms
Retry Behavior.Retries On 504	✅	5161ms
Retry Behavior.Max Retries Respected	✅	15480ms
Deduplication.Generates Unique Uuids	✅	22ms
Deduplication.Preserves Uuid On Retry	✅	5144ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	10241ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	5121ms
Deduplication.No Duplicate Events In Batch	✅	19ms
Deduplication.Different Events Have Different Uuids	✅	9ms
Compression.Sends Gzip When Enabled	✅	6ms
Batch Format.Uses Proper Batch Structure	✅	7ms
Batch Format.Flush With No Events Sends Nothing	✅	3ms
Batch Format.Multiple Events Batched Together	❌	17ms
Error Handling.Does Not Retry On 403	✅	2008ms
Error Handling.Does Not Retry On 413	✅	2010ms
Error Handling.Retries On 408	✅	5145ms

Failures

batch_format.multiple_events_batched_together

Expected 1 requests, got 5

Feature_Flags Tests

⚠️ 16/17 tests passed, 1 failed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	8ms
Request Payload.Flags Request Uses V2 Query Param	✅	7ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	6ms
Request Payload.Flags Request Omits Authorization Header	✅	7ms
Request Payload.Token In Flags Body Matches Init	✅	7ms
Request Payload.Groups Round Trip	✅	7ms
Request Payload.Groups Default To Empty Object	✅	7ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	8ms
Request Payload.Disable Geoip Omitted Defaults To False	❌	8ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	8ms
Request Lifecycle.No Flags Request On Init Alone	✅	3ms
Request Lifecycle.No Flags Request On Normal Capture	✅	6ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	10ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	6ms
Retry Behavior.Retries Flags On 502	✅	110ms
Retry Behavior.Retries Flags On 504	✅	159ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	9ms

Failures

request_payload.disable_geoip_omitted_defaults_to_false

Field 'geoip_disable' not found in /flags request body at path 'geoip_disable'. Available keys: ['distinct_id', 'groups', 'person_properties', 'group_properties', 'flag_keys_to_evaluate', 'token']

[github-actions]

posthog-ruby-async Compliance Report

Date: 2026-10-05T08:50:18.696040+00:00
Duration: 98372ms

⚠️ Some Tests Failed

46/47 tests passed, 1 failed

---

Capture Tests

✅ 30/30 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	9ms
Format Validation.Event Has Uuid	✅	106ms
Format Validation.Event Has Lib Properties	✅	109ms
Format Validation.Distinct Id Is String	✅	106ms
Format Validation.Token Is Present	✅	106ms
Format Validation.Custom Properties Preserved	✅	106ms
Format Validation.Event Has Timestamp	✅	106ms
Format Validation.Non Utc Event Timestamp Is Converted To Utc	✅	8ms
Retry Behavior.Retries On 503	✅	5310ms
Retry Behavior.Does Not Retry On 400	✅	2111ms
Retry Behavior.Does Not Retry On 401	✅	2109ms
Retry Behavior.Respects Retry After Header	✅	8116ms
Retry Behavior.Implements Backoff	✅	15623ms
Retry Behavior.Retries On 500	✅	5212ms
Retry Behavior.Retries On 502	✅	5209ms
Retry Behavior.Retries On 504	✅	5212ms
Retry Behavior.Max Retries Respected	✅	15622ms
Deduplication.Generates Unique Uuids	✅	113ms
Deduplication.Preserves Uuid On Retry	✅	5212ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	10417ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	5214ms
Deduplication.No Duplicate Events In Batch	✅	111ms
Deduplication.Different Events Have Different Uuids	✅	107ms
Compression.Sends Gzip When Enabled	✅	107ms
Batch Format.Uses Proper Batch Structure	✅	107ms
Batch Format.Flush With No Events Sends Nothing	✅	4ms
Batch Format.Multiple Events Batched Together	✅	112ms
Error Handling.Does Not Retry On 403	✅	2108ms
Error Handling.Does Not Retry On 413	✅	2109ms
Error Handling.Retries On 408	✅	5212ms

Feature_Flags Tests

⚠️ 16/17 tests passed, 1 failed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	107ms
Request Payload.Flags Request Uses V2 Query Param	✅	107ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	107ms
Request Payload.Flags Request Omits Authorization Header	✅	107ms
Request Payload.Token In Flags Body Matches Init	✅	108ms
Request Payload.Groups Round Trip	✅	107ms
Request Payload.Groups Default To Empty Object	✅	107ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	107ms
Request Payload.Disable Geoip Omitted Defaults To False	❌	107ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	107ms
Request Lifecycle.No Flags Request On Init Alone	✅	3ms
Request Lifecycle.No Flags Request On Normal Capture	✅	106ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	113ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	107ms
Retry Behavior.Retries Flags On 502	✅	210ms
Retry Behavior.Retries Flags On 504	✅	257ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	108ms

Failures

request_payload.disable_geoip_omitted_defaults_to_false

Field 'geoip_disable' not found in /flags request body at path 'geoip_disable'. Available keys: ['distinct_id', 'groups', 'person_properties', 'group_properties', 'flag_keys_to_evaluate', 'token']