- CLAUDE.md: Project guide with structure, build commands, and priorities
- ai-native-services.md: End-to-end tutorial building an MCP-enabled task service
- mcp-security.md: Production security guide (auth, scopes, rate limiting, audit)
- tool-descriptions.md: Best practices for writing Go comments that help agents
- agent-patterns.md: Six integration patterns from single-agent to event-driven
- Updated docs index with new "AI & Agents" section linking all four guides

These were the highest priority gaps identified in the roadmap analysis:
the framework has solid features that were under-documented.

https://claude.ai/code/session_01GkduEhcrqcG45rdfYh8dAc

Integrate OpenTelemetry spans into the MCP gateway for both HTTP and
stdio transports. Each tool call now creates a server span with rich
attributes (tool name, account ID, auth outcome, transport type).
Trace context is propagated to downstream RPC calls via metadata,
enabling end-to-end distributed tracing through Jaeger, Grafana, etc.

New files:
- gateway/mcp/otel.go: Span creation, attribute constants, metadata carrier
- gateway/mcp/otel_test.go: 8 tests covering span creation, auth denied/allowed,
  rate limiting, trace propagation, noop provider, and missing token

Changes:
- Options.TraceProvider: Optional trace.TracerProvider field
- handleCallTool (HTTP): Creates OTel spans with auth/rate-limit attributes
- handleToolsCall (stdio): Same instrumentation for stdio transport
- go.mod: Added go.opentelemetry.io/otel/sdk v1.35.0 (test dependency)

The existing MCP trace ID (UUID) is preserved for backward compatibility
and recorded as a span attribute alongside the W3C trace context.

https://claude.ai/code/session_01GkduEhcrqcG45rdfYh8dAc