Author a caching strategy and key-namespace reference in docs/cache.md

[1nonlypiece]

📌 Description

A Redis-backed cache-aside layer exists in src/lib/cache.ts and is used by vault
and analytics reads, but there is no documentation of the caching strategy: which
reads are cached, the key-namespace scheme, TTLs, invalidation triggers, and the
in-memory vs Redis fallback behaviour. Without this, contributors risk introducing
inconsistent or unsafe cache usage.

This issue authors a caching reference doc.

🎯 Requirements and Context

• Document the key-namespace convention (including per-org namespacing) and TTL
  policy per cached resource.
• Document invalidation triggers and the in-memory LRU vs Redis fallback.
• Document cache versioning (CACHE_VERSION) and how to safely change cached
  shapes.
• Provide a checklist for adding a new cached read safely.

🛠️ Suggested Execution

1. Fork the repo and create a branch

git checkout -b docs/cache-strategy

2. Implement changes

• Author docs/cache.md reflecting src/lib/cache.ts.
• Add src/tests/docs.cache.test.ts asserting documented env keys and
  CACHE_VERSION references exist in the code.

3. Test and commit

• Run: npm test -- src/tests/docs.cache.test.ts
• Cover edge cases: documented env keys exist, namespaces match code, fallback
  behaviour described.

Example commit message

docs: caching strategy, key namespaces, and invalidation reference

✅ Guidelines

• Minimum 95% test coverage on any assertion code added.
• Doc must match src/lib/cache.ts behaviour.
• Timeframe: 96 hours.

🏷️ Labels

type-documentation · type-performance · area-backend · MAYBE REWARDED · GRANTFOX OSS · OFFICIAL CAMPAIGN

💬 Community & Support

• Join the contributor Discord to coordinate, ask questions, and get unblocked fast: https://discord.gg/xvNAvMJf
• Please introduce yourself in the channel before you start so we can avoid duplicate work, pair you with a reviewer, and get your PR merged quickly.
• Maintainers actively triage this channel and aim for fast, clear, respectful reviews — reach out any time you're blocked.

[code-0-stella]

@code-0-stella has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hello, I have reviewed the issue and understand what needs to be done.

I would appreciate being assigned to it.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @code-0-stella to this issue.

[drips-wave]

Congratulations, @code-0-stella! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @code-0-stella: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊