diff --git a/.agents/context/sdk-instrumentation.md b/.agents/context/sdk-instrumentation.md
index 2e9f168c..83ea2ab4 100644
--- a/.agents/context/sdk-instrumentation.md
+++ b/.agents/context/sdk-instrumentation.md
@@ -12,11 +12,10 @@ Optional extra: `pip install opendecree[otel]`. Constructor flag `otel=True` wir
 
 ### Go SDKs (`decree`)
 
-Docs-only — users pass their own `grpc.ClientConn`, add OTel interceptors themselves:
+Docs-only — users pass their own `grpc.ClientConn`, add OTel via stats handler (preferred over deprecated interceptor API):
 ```go
 conn, _ := grpc.NewClient(target,
-    grpc.WithUnaryInterceptor(otelgrpc.UnaryClientInterceptor()),
-    grpc.WithStreamInterceptor(otelgrpc.StreamClientInterceptor()),
+    grpc.WithStatsHandler(otelgrpc.NewClientHandler()),
 )
 ```
 
diff --git a/docs/sdk.md b/docs/sdk.md
index 8426f89a..130e0f90 100644
--- a/docs/sdk.md
+++ b/docs/sdk.md
@@ -37,3 +37,26 @@ Reusable power tools for config management — importable as Go packages for int
 - **API Reference:** [pkg.go.dev/github.com/opendecree/decree/sdk/tools](https://pkg.go.dev/github.com/opendecree/decree/sdk/tools)
 
 Packages: `diff` (config version diffing), `docgen` (schema → markdown), `validate` (offline YAML validation), `seed` (bootstrap from YAML), `dump` (full tenant backup). Offline tools have zero gRPC/proto dependencies.
+
+## OpenTelemetry instrumentation (Go)
+
+The Go SDKs accept a `grpc.ClientConn` that callers construct themselves. Wire an OTel interceptor at connection time:
+
+```go
+import (
+    "go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"
+    "google.golang.org/grpc"
+    "github.com/opendecree/decree/sdk/configclient"
+)
+
+conn, err := grpc.NewClient(
+    "localhost:9090",
+    grpc.WithStatsHandler(otelgrpc.NewClientHandler()),
+)
+// conn is passed to the SDK client
+client := configclient.New(conn, ...)
+```
+
+`otelgrpc.NewClientHandler()` uses the stats handler API (preferred over deprecated interceptors) and records spans for every RPC. The same pattern applies to `adminclient` and the watcher's underlying connection.
+
+Install: `go get go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc`