docs: align docs with implementation

[kxzk]

Supersedes #58 after branch rename to conventional format.

TL;DR

Align docs with actual SDK behavior for tracing export modes, SWR activation semantics, and config coverage.

Why

docs/ contained high-confidence mismatches against implementation that can cause incorrect production configuration and observability assumptions.

Checklist

• Has label
• Has linked issue
• Tests added for new behavior
• Docs updated (if user-facing)

Summary

• Corrected tracing_async docs to match OpenTelemetry behavior.
• Corrected SWR docs to require explicit positive cache_stale_ttl.
• Documented batch_size / flush_interval impact on trace export.
• Added missing environment and release config docs and env defaults.

Fixes addressed

• P1 docs-to-code gaps in docs/CONFIGURATION.md, docs/CACHING.md, docs/API_REFERENCE.md
• P2 missing documentation for environment/release config defaults

Validation checklist

• Langfuse CLI schema check via npx langfuse-cli api __schema
• bundle exec rspec (blocked: missing bundler 2.4.7)
• bundle exec rubocop (blocked: missing bundler 2.4.7)

Linear: ML-646

[greptile-apps]

Greptile Summary

This PR corrects critical documentation gaps that could lead to production misconfigurations. The changes align documentation with actual SDK implementation behavior.

Key fixes:

• SWR activation semantics: Clarified that cache_stale_while_revalidate = true alone is insufficient; cache_stale_ttl must be explicitly set to a positive value (verified against stale_while_revalidate.rb:102 which checks stale_ttl.positive?)
• Tracing async behavior: Corrected description from "not implemented" to accurately reflect OpenTelemetry BatchSpanProcessor usage in both async and sync modes (verified against otel_setup.rb:35-53)
• Batch configuration scope: Documented that batch_size and flush_interval affect both score batching AND OpenTelemetry trace export scheduling (verified in otel_setup.rb:40-41)
• Environment defaults: Added missing documentation for environment and release config options with their environment variable defaults (verified in config.rb:151-152)

All documentation changes are accurate to implementation and address the P1 docs-to-code gaps mentioned in the PR description.

Confidence Score: 5/5

• This documentation-only PR is safe to merge with no risk
• Documentation changes are accurate to implementation code, fix critical mismatches that could cause production misconfigurations, and include no code changes
• No files require special attention

Important Files Changed

Filename	Overview
docs/API_REFERENCE.md	Corrected SWR activation semantics, documented environment/release configs, clarified batch_size and flush_interval apply to both scores and trace exports
docs/CACHING.md	Fixed critical misconception that SWR auto-sets stale_ttl; documented requirement for explicit positive cache_stale_ttl value
docs/CONFIGURATION.md	Aligned tracing_async docs with OpenTelemetry BatchSpanProcessor implementation, clarified SWR activation, added environment/release config docs

_{Last reviewed commit: 44280ca}

[Copilot]

Pull request overview

This PR aligns documentation with the actual SDK implementation, correcting critical mismatches in tracing export modes, SWR (stale-while-revalidate) activation semantics, and configuration coverage that could lead to incorrect production configuration.

Changes:

• Corrected SWR documentation to clearly state that cache_stale_ttl must be a positive value for SWR to activate, not just the boolean flag
• Updated tracing_async documentation to accurately reflect that it controls OpenTelemetry BatchSpanProcessor scheduling, not a placeholder feature
• Documented that batch_size and flush_interval control both scoring API and OpenTelemetry trace export batching
• Added missing documentation for environment and release configuration options with their environment variable defaults

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
docs/CONFIGURATION.md	Updated SWR activation requirements, tracing_async behavior, batch/flush parameter usage, and added environment/release config documentation
docs/CACHING.md	Clarified SWR activation requirement and added cache_stale_ttl to configuration examples
docs/API_REFERENCE.md	Updated configuration table with corrected descriptions for SWR, batching parameters, tracing_async status, and added environment/release entries

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.