chore: document why we replace llm provider sdks

Author: SasSwart

go.mod

@@ -18,6 +18,7 @@ require (
 	go.uber.org/goleak v1.3.0
 	go.uber.org/mock v0.6.0
 	golang.org/x/exp v0.0.0-20250819193227-8b4c13bb791b
+	golang.org/x/sync v0.16.0
 	golang.org/x/tools v0.36.0
 )
 
@@ -36,8 +37,6 @@ require (
 	go.opentelemetry.io/otel/trace v1.38.0
 )
 
-require golang.org/x/sync v0.16.0
-
 require (
 	github.com/aws/aws-sdk-go-v2 v1.30.3 // indirect
 	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.6.3 // indirect
@@ -90,6 +89,9 @@ require (
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )
 
+// Replace sdks with our own optimized forks until relevant upstream PRs are merged.
+// https://github.com/anthropics/anthropic-sdk-go/pull/262
 replace github.com/anthropics/anthropic-sdk-go v1.13.0 => github.com/dannykopping/anthropic-sdk-go v0.0.0-20251230111224-88a4315810bd
 
+// https://github.com/openai/openai-go/pull/602
 replace github.com/openai/openai-go/v3 => github.com/SasSwart/openai-go/v3 v3.0.0-20260202093810-72af3b857f95