docs: improve documentation readability and formatting

docs/ARCHITECTURE.md

@@ -535,21 +535,9 @@ User Code
 - **In-memory**: Monitor-based locking (minimal contention)
 - **Rails.cache**: Redis atomic operations (high concurrency)
 
-## Future Enhancements
+## See Also
 
-See [docs/future-enhancements/](future-enhancements/) for detailed designs:
-
-- **Stale-While-Revalidate**: Background cache refresh for even lower latency
-- **Cost Tracking**: Automatic LLM cost calculation
-- **Automatic LLM Client Wrappers**: Zero-boilerplate tracing for OpenAI, Anthropic
-
-## Additional Resources
-
-- [Main README](../README.md) - Getting started guide
-- [Caching Guide](CACHING.md) - Detailed caching documentation
-- [Tracing Guide](TRACING.md) - LLM observability guide
-- [Rails Integration](RAILS.md) - Rails-specific patterns
-
-## Questions?
-
-Open an issue on [GitHub](https://github.com/langfuse/langfuse-ruby/issues) if you have architecture questions.
+- [Caching Guide](CACHING.md) - Cache backends, SWR, and stampede protection
+- [Tracing Guide](TRACING.md) - LLM observability and nested spans
+- [Rails Integration](RAILS.md) - Rails-specific patterns and testing
+- [API Reference](API_REFERENCE.md) - Complete method reference

docs/CACHING.md

@@ -668,14 +668,9 @@ end
 2. Verify Redis is accessible
 3. Check `cache_lock_timeout` is sufficient
 
-## Additional Resources
+## See Also
 
-- [Main README](../README.md) - SDK overview
 - [Configuration Reference](CONFIGURATION.md) - All config options including SWR
-- [Rails Integration Guide](RAILS.md) - Rails-specific patterns
-- [Tracing Guide](TRACING.md) - LLM observability
-- [Architecture Guide](ARCHITECTURE.md) - Design decisions
-
-## Questions?
-
-Open an issue on [GitHub](https://github.com/langfuse/langfuse-ruby/issues) if you have questions or need help with caching.
+- [Rails Integration](RAILS.md) - Rails-specific cache patterns
+- [Architecture Guide](ARCHITECTURE.md) - Cache design decisions
+- [Error Handling](ERROR_HANDLING.md) - Cache miss fallback behavior

docs/GETTING_STARTED.md

@@ -302,14 +302,14 @@ end
 
 See [ERROR_HANDLING.md](ERROR_HANDLING.md) for complete error reference.
 
-## Next Steps
-
-- **[PROMPTS.md](PROMPTS.md)** - Chat prompts, versioning, Mustache templating
-- **[TRACING.md](TRACING.md)** - Nested observations, RAG patterns, OpenTelemetry
-- **[SCORING.md](SCORING.md)** - Add quality scores to traces
-- **[DATASETS.md](DATASETS.md)** - Create and manage evaluation datasets
-- **[EXPERIMENTS.md](EXPERIMENTS.md)** - Run systematic evaluations with the experiment runner
-- **[CACHING.md](CACHING.md)** - Optimize performance with caching
-- **[RAILS.md](RAILS.md)** - Rails-specific patterns and testing
-- **[CONFIGURATION.md](CONFIGURATION.md)** - All configuration options
-- **[API_REFERENCE.md](API_REFERENCE.md)** - Complete method reference
+## See Also
+
+- [Prompts Guide](PROMPTS.md) - Chat prompts, versioning, Mustache templating
+- [Tracing Guide](TRACING.md) - Nested observations, RAG patterns, OpenTelemetry
+- [Scoring Guide](SCORING.md) - Add quality scores to traces
+- [Datasets Guide](DATASETS.md) - Create and manage evaluation datasets
+- [Experiments Guide](EXPERIMENTS.md) - Run evaluations against datasets
+- [Caching Guide](CACHING.md) - In-memory and Rails.cache backends, SWR
+- [Configuration Reference](CONFIGURATION.md) - All configuration options
+- [Rails Integration](RAILS.md) - Rails-specific patterns and testing
+- [API Reference](API_REFERENCE.md) - Complete method reference

docs/MIGRATION.md

@@ -717,9 +717,10 @@ prompt.compile("name" => "Alice")
 3. Use fallbacks for critical paths
 4. Check network latency to Langfuse API
 
-## Additional Resources
+## See Also
 
-- [Main README](../README.md) - SDK overview
-- [Rails Integration Guide](RAILS.md) - Rails-specific patterns
-- [Tracing Guide](TRACING.md) - LLM observability
-- [Langfuse Documentation](https://langfuse.com/docs) - Official docs
+- [Getting Started](GETTING_STARTED.md) - Installation and first trace
+- [Rails Integration](RAILS.md) - Rails-specific patterns
+- [Prompts Guide](PROMPTS.md) - Versioning and Mustache templating
+- [Caching Guide](CACHING.md) - Cache backends and SWR
+- [Langfuse Documentation](https://langfuse.com/docs) - Official Langfuse docs

docs/RAILS.md

@@ -626,9 +626,10 @@ If experiencing high memory usage:
 1. **Reduce cache_max_size**: Default is 1000, reduce if needed
 2. **Enable cache cleanup**: Implement periodic cache cleanup in background job
 
-## Additional Resources
+## See Also
 
-- [Main README](../README.md) - SDK overview and basic usage
-- [Tracing Guide](TRACING.md) - Deep dive on LLM tracing
+- [Getting Started](GETTING_STARTED.md) - Installation and first trace
+- [Configuration Reference](CONFIGURATION.md) - All config options
+- [Tracing Guide](TRACING.md) - Nested spans and OpenTelemetry
 - [Migration Guide](MIGRATION.md) - Migrating from hardcoded prompts
 - [Langfuse Documentation](https://langfuse.com/docs) - Official Langfuse docs

docs/README.md

@@ -0,0 +1,37 @@
+# Langfuse Ruby SDK — Documentation
+
+## Foundations
+
+Core concepts you need before using any feature.
+
+- **[Getting Started](GETTING_STARTED.md)** — Install the gem, configure credentials, send your first trace
+- **[Configuration](CONFIGURATION.md)** — All `Langfuse.configure` options: keys, timeouts, cache backends, SWR
+
+## Core Features
+
+The three primitives of the SDK.
+
+- **[Prompts](PROMPTS.md)** — Fetch, compile, and version-manage text and chat prompts
+- **[Tracing](TRACING.md)** — Nested spans, RAG patterns, OpenTelemetry integration
+- **[Scoring](SCORING.md)** — Attach quality scores to traces and observations
+
+## Evaluation
+
+Systematic testing of LLM behavior.
+
+- **[Datasets](DATASETS.md)** — Create and manage evaluation datasets
+- **[Experiments](EXPERIMENTS.md)** — Run evaluations against datasets with the experiment runner
+
+## Production
+
+Patterns for real-world deployments.
+
+- **[Caching](CACHING.md)** — In-memory and Rails.cache backends, SWR, stampede protection
+- **[Error Handling](ERROR_HANDLING.md)** — Exception types, retry behavior, fallback strategies
+- **[Rails Integration](RAILS.md)** — Initializers, controller tracing, testing helpers
+- **[Migration Guide](MIGRATION.md)** — Move from hardcoded prompts to Langfuse-managed prompts
+
+## Reference
+
+- **[API Reference](API_REFERENCE.md)** — Complete method reference for every public class
+- **[Architecture](ARCHITECTURE.md)** — Internal design: layers, threading, cache architecture

docs/TRACING.md

@@ -668,8 +668,12 @@ This allows traces to flow seamlessly across:
 - Go services
 - Any service that implements W3C Trace Context
 
-## Resources
+## See Also
 
+- [Scoring Guide](SCORING.md) - Add quality scores to traces
+- [Prompts Guide](PROMPTS.md) - Managed prompts with tracing integration
+- [Rails Integration](RAILS.md) - Controller-level tracing patterns
+- [API Reference](API_REFERENCE.md) - Complete method reference
 - [Langfuse Documentation](https://langfuse.com/docs)
 - [OpenTelemetry Ruby Documentation](https://opentelemetry.io/docs/instrumentation/ruby/)
 - [W3C Trace Context Specification](https://www.w3.org/TR/trace-context/)