docs: add semantic cache latency warning, comparison table row, and routing harness ledger docs

[Pratham-Mishra04]

Summary

This PR documents the latency trade-offs of semantic caching, introduces a local routing harness ledger convention for e2e test journaling, and adds the corresponding gitignore entry to keep those ledger files out of version control.

Changes

• Added a <Warning> block to the semantic caching docs explaining the latency overhead for direct lookups, semantic lookups, and cache writes — including the nuance that a semantic cache hit still costs an embedding round-trip, and a semantic miss pays that cost on top of the full LLM call.
• Added a row to the direct vs. semantic comparison table covering added latency per mode.
• Added a Routing Harness Ledger section to the e2e API README describing the daily journaling convention (routing/ledger-YYYY-MM-DD.md), its structure, and the rule against rewriting past days.
• Added tests/e2e/api/routing/ledger-* to .gitignore so local run journals are never committed.

Type of change

• Bug fix
• Feature
• Refactor
• Documentation
• Chore/CI

Affected areas

• Core (Go)
• Transports (HTTP)
• Providers/Integrations
• Plugins
• UI (React)
• Docs

How to test

Verify the docs render correctly and that the gitignore pattern excludes ledger files as expected:

# Confirm ledger files are ignored
touch tests/e2e/api/routing/ledger-2025-01-01.md
git status  # should not appear as an untracked file

Review the updated semantic caching docs to confirm the warning block and table row render as intended.

Breaking changes

• No

Related issues

N/A

Security considerations

None. No code changes; no secrets, auth, or PII involved.

Checklist

• I read docs/contributing/README.md and followed the guidelines
• I added/updated tests where appropriate
• I updated documentation where needed
• I verified builds succeed (Go and UI)
• I verified the CI pipeline passes locally if applicable

Summary by CodeRabbit

• Documentation

  • Added a Latency overhead warning to semantic caching docs describing added costs for cache reads and asynchronous writes
  • Clarified direct vs. semantic caching comparison with an explicit “Added latency” row
  • Added routing harness ledger guidance describing daily, append-only ledger entries for test runs

• Chores

  • Updated ignore rules to exclude local test artifacts and routing ledger journal files

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[Pratham-Mishra04]

• refactor: simplify load balancing skip logic to use parsed provider field directly #4279
• docs: add semantic cache latency warning, comparison table row, and routing harness ledger docs #4255 👈 (View in Graphite)
• tests: add e2e fallback routing scenarios and setup clear-providers step #4254
• tests: add weightless VK allow-list and case-insensitive alias fallback e2e scenarios #4253
• tests: cover blacklist/multi-key/keyless/details/base catalog cases. #4252
• tests: add e2e scenarios for reverse-alias gate #4251
• tests: add e2e model-catalog wiring tests for openai, anthropic, and gemini #4250
• tests: add e2e routing wiring test harness #4249
• dev

This stack of pull requests is managed by Graphite. Learn more about stacking.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: e9309fa1-8975-4831-a2b6-79eb4b9f6461

📥 Commits

Reviewing files that changed from the base of the PR and between 5218731 and 66ed6f1.

📒 Files selected for processing (3)

• .gitignore
• docs/features/semantic-caching.mdx
• tests/e2e/api/README.md

---

📝 Walkthrough

Walkthrough

Adds .gitignore entries for local test artifacts, documents the routing harness ledger format and append-only rule, and adds a "Latency overhead" warning plus an "Added latency" row to the direct vs semantic comparison table in semantic-caching docs.

Changes

Test Infrastructure and Caching Documentation

Layer / File(s)	Summary
Test artifact ignores and ledger documentation .gitignore, tests/e2e/api/README.md	Ignored tests/cmd/seedvks/seedvks and tests/e2e/api/routing/ledger-*; README documents per-day routing ledger files, their contents (open divergences snapshot, scenario tables/markers, run results, notes) and append-only update guidance.
Caching latency performance documentation docs/features/semantic-caching.mdx	Added a "Latency overhead" warning describing direct vs semantic lookup costs (embedding + similarity search on semantic lookups) and clarified cache writes are asynchronous; updated "Direct vs. semantic mode" table with an "Added latency" row.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Suggested reviewers

• akshaydeo
• danpiths

Poem

A rabbit tapped the ledger neat and light,
Ignored the crumbs that cluttered up the night,
I hummed of embeddings, lookups, tiny cost,
Notes appended—never old days lost,
Hooray for tidy docs and artifacts in flight. 🐇✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes all three main changes: semantic cache latency warning, comparison table row, and routing harness ledger documentation.
Description check	✅ Passed	The description is comprehensive and well-structured, covering summary, changes, type of change, affected areas, testing instructions, breaking changes, and security considerations.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 06-10-docs_semantic_cache_doc_updates

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[greptile-apps]

Confidence Score: 5/5

Safe to merge — no code changes, only documentation updates and a gitignore entry.

All three changes are documentation or chore. The latency descriptions in the semantic caching warning were cross-checked against the actual plugin implementation and are accurate. The gitignore pattern and README ledger section are self-consistent.

No files require special attention.

Important Files Changed

Filename	Overview
.gitignore	Adds newline fix and tests/e2e/api/routing/ledger-* ignore pattern for local run journals
docs/features/semantic-caching.mdx	Adds a latency-overhead Warning block and a new table row; technical claims are consistent with the async goroutine write pattern in the plugin code
tests/e2e/api/README.md	Documents the routing harness ledger convention and file naming; consistent with the new gitignore entry

_{Reviews (3): Last reviewed commit: "docs: semantic cache doc updates" | Re-trigger Greptile}

[Pratham-Mishra04]

Merge activity

• Jun 11, 7:18 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jun 11, 7:36 AM UTC: Graphite rebased this pull request as part of a merge.
• Jun 11, 7:37 AM UTC: @Pratham-Mishra04 merged this pull request with Graphite.