diff --git a/docs/guides/go-sdk/index.md b/docs/guides/go-sdk/index.md
index 6ac81e40b..25b93e913 100644
--- a/docs/guides/go-sdk/index.md
+++ b/docs/guides/go-sdk/index.md
@@ -154,19 +154,52 @@ Requesting a model whose provider was compiled out fails at construction time wi
The Google provider's Vertex Model Garden support also imports the Anthropic SDK, so the Anthropic dependency is only fully removed when both docker_agent_no_anthropic and docker_agent_no_google are set.
-## RAG Toolset (cgo-free builds)
+## RAG Toolset (opt-out)
-The RAG toolset (`type: rag`) uses a tree-sitter code parser that requires cgo. When building without cgo — or when you want to drop the cgo dependency entirely — do not import the `pkg/rag` package in your binary.
+The RAG toolset (`type: rag`) is included in `NewDefaultToolsetRegistry()` (from `pkg/teamloader/toolsets`) and `loaderdefaults.Opts()` (from `pkg/teamloader/defaults`, using the conventional import alias `loaderdefaults`).
-By default the RAG toolset is **opt-in**: it is only linked when you blank-import its package:
+The underlying tree-sitter code parser uses cgo, but build-tag guards in `pkg/rag/treesitter` mean importing the package is safe regardless of `CGO_ENABLED`: with `CGO_ENABLED=0` the parser stub compiles in and returns a runtime error on first use rather than failing at compile time.
+
+If you want to exclude the RAG toolset from your binary entirely — surfacing a load-time warning on the agent rather than a deferred runtime error from the `!cgo` stub — remove it from the registry before passing it to `teamloader.Load`:
```go
import (
- _ "github.com/docker/docker-agent/pkg/tools/builtin/rag" // register RAG toolset
+ "github.com/docker/docker-agent/pkg/teamloader"
+ loadertoolsets "github.com/docker/docker-agent/pkg/teamloader/toolsets"
)
+
+// Opt out of the RAG toolset; a config that declares type: rag attaches
+// a load-time warning to the agent instead of failing at document processing.
+creators := loadertoolsets.DefaultToolsetCreators()
+delete(creators, "rag")
+registry := teamloader.NewToolsetRegistry(creators)
```
-Without this import, a config that declares `type: rag` fails with a "toolset type not registered" error at startup. If your application does not use RAG, simply omit the blank import; the rest of docker-agent works without cgo.
+Pass the custom registry via `teamloader.WithToolsetRegistry(registry)` when calling `teamloader.Load`. Note that `teamloader.Load()` does not return an error for unknown toolset types — the failure is recorded as a load-time warning and can be retrieved with `agent.DrainWarnings()`; it is also surfaced via logging and TUI notifications.
+
+## MCP OAuth Token Persistence
+
+By default, MCP OAuth tokens are stored in-memory only and are not persisted across process restarts. The CLI registers a keyring-backed store automatically at startup; when embedding docker-agent as a library you must do this yourself if you want tokens to survive restarts.
+
+Call `keyringstore.Register()` **before** any MCP toolset is initialised to enable the OS keyring-backed token store:
+
+```go
+import "github.com/docker/docker-agent/pkg/tools/mcp/keyringstore"
+
+func main() {
+ // Must be called before teamloader.Load() on configs with remote MCP
+ // toolsets; calling it after the store is created panics.
+ keyringstore.Register()
+ // ... rest of your startup code
+}
+```
+
+
+
Call order matters
+
If keyringstore.Register() is called after the default token store has already been lazily initialised, docker-agent panics. The store is initialised when any remote MCP toolset is constructed — which happens inside teamloader.Load(). Always call keyringstore.Register() before calling teamloader.Load() on a config that includes remote MCP toolsets.
+