[ML-858] docs: align docs with implementation

[kxzk]

TL;DR

Consolidated docs-alignment PR covering every known drift between docs/ (and YARD) and the current implementation. Supersedes #72 and #73.

Why

Three separate Linear issues (ML-858, ML-896, ML-931) each flagged overlapping drift across the same doc files. Shipping one consolidated PR eliminates merge conflicts and keeps the history clean.

Checklist

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

Summary

Cache eviction (docs/CACHING.md, docs/ARCHITECTURE.md, CHANGELOG.md)

• In-memory cache is not LRU. It evicts the entry with the earliest stale_until when max_size is reached (lib/langfuse/prompt_cache.rb:238-244).
• Updated docs and the v0.1.0 CHANGELOG entry to say "bounded expiration-ordered eviction".

ApiClient constructor (docs/ARCHITECTURE.md)

• Corrected the example to use the real keyword-arg signature: public_key:, secret_key:, base_url:, timeout:, logger:, cache: (lib/langfuse/api_client.rb:52-59).

Prompt API surface (docs/API_REFERENCE.md)

• Added Client#create_prompt and Client#update_prompt sections with full signature, params, raises, and examples.
• Corrected get_prompt fallback type to String or Array<Hash> (chat fallback was always supported).
• Corrected example comment from # Latest version to # API default selection (no version/label sent).
• Corrected cache_stale_while_revalidate parameter-table description to "advisory SWR intent flag".
• Corrected cache_stale_ttl parameter-table type to Integer or :indefinite.

SWR activation (docs/CONFIGURATION.md, docs/CACHING.md)

• cache_stale_while_revalidate does not gate SWR. SWR is active when cache_stale_ttl > 0 (lib/langfuse/stale_while_revalidate.rb:102-104, lib/langfuse/config.rb).
• Rewrote the cache_stale_while_revalidate section in CONFIGURATION.md to describe it as an advisory intent flag.
• Updated code-example comments in CACHING.md and CONFIGURATION.md so readers don't think the boolean alone activates SWR.
• Swapped the "disable SWR for tests" example to set cache_stale_ttl = 0 (the actual off switch).

Prompt selection semantics (docs/PROMPTS.md, docs/API_REFERENCE.md, docs/CACHING.md, lib/langfuse/cache_warmer.rb)

• Omitting both version and label sends no selector to the API — the server decides which version to return (lib/langfuse/api_client.rb:738-740). The SDK does not auto-inject "production".
• Corrected PROMPTS.md "Best Practices" to recommend explicit label: "production" in production and frame implicit selection as API-defined.
• Updated cache-warming examples in docs/CACHING.md and the CacheWarmer#warm_all YARD example that previously claimed omitting the label fetched "latest versions".

Fixes Addressed

• [P1] Docs-to-code mismatch for in-memory cache eviction policy.
• [P1] Docs-to-code mismatch for SWR activation semantics.
• [P1] Docs-to-code mismatch for implicit prompt-selection behavior.
• [P2] ApiClient constructor example used an outdated positional signature.
• [P2] API reference omitted create_prompt/update_prompt and under-specified fallback / cache_stale_ttl types.
• [P3] CHANGELOG v0.1.0 entry still said "LRU eviction".
• [P3] Stale YARD example in CacheWarmer#warm_all.

Validation Checklist

• bundle exec rspec — 1198 examples, 0 failures related to this change (2 pre-existing failures caused by LANGFUSE_HOST env var pointing to staging; docs-only changes don't affect them)
• bundle exec rubocop — clean
• Codebase audit for remaining drift (LRU mentions, SWR boolean, "latest version" phrasing, String-only fallback, positional ApiClient.new, missing prompt-mutation methods) — no further instances found

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 2 additional findings.

[Copilot]

Pull request overview

Updates user-facing documentation to match the SDK’s actual cache eviction behavior and the current prompt management API surface, reducing docs-to-code drift for SDK consumers.

Changes:

• Corrects in-memory cache eviction description to reflect expiration-ordered bounded eviction (not LRU).
• Updates ApiClient.new architecture example to the current keyword-argument constructor.
• Extends the API reference to document Client#create_prompt and Client#update_prompt.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
docs/CACHING.md	Updates caching backend descriptions, especially in-memory eviction behavior.
docs/ARCHITECTURE.md	Aligns the ApiClient construction example and cache eviction wording with implementation.
docs/API_REFERENCE.md	Adds missing reference sections for prompt creation and label updates.

---

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