spec: M092_002 — cache-kit vs other Rust caches docs page

[indykish]

Summary

Second v0.9.2 milestone spec. Independent of #3 (M092_001 error codes) — this is docs-only work.

Converts the moka comparison recommendation from plans/comprehensive-code-review.md (§12 #2 and §18) into a goal-contract spec following the updated dotfiles/docs/TEMPLATE.md.

No code yet — spec only. Implementation lands on feat/m092-vs-other-caches after this PR merges.

What ships

A new MDX page at site/content/concepts/vs-other-caches.mdx, reachable at https://cachekit.org/concepts/vs-other-caches. Four sections:

1. Capability matrix — rows = features, columns = cache-kit / moka / cached / redis-rs, cells = ✅/❌/⚠️/N/A. No self-rating stars.
2. When to pick which — 4 decision scenarios (single-instance L1, multi-instance shared, embedded/no-network, edge/serverless). Calls out moka as the right answer for single-instance hot-path reads.
3. Worked example — moka-as-L1 + cache-kit-as-L2 layered. Short Rust snippet.
4. Things cache-kit deliberately doesn't do — TinyLFU eviction, sub-µs in-process reads, lock-free reads via concurrent hashmap, in-process-only optimization. Closes with: "If you need any of the above, use moka; cache-kit is the wrong tool."

Why this shape

The seed table in plans/comprehensive-code-review.md §18 has two problems that this spec demands the implementation fix:

1. Self-rated. Rows like "Documentation ⭐⭐⭐⭐⭐" are vibes. Dropped. The shipping table is objective rows only (type-safe / async-first / has eviction policy).
2. Doesn't surface moka's actual strengths. A reader can't tell when to use moka over cache-kit. The new §4 says it out loud in cache-kit's own docs — so users who'd be better served by moka self-select correctly.

Both issues are pinned as invariants in the spec (greppable: zero ⭐ characters, §4 non-empty).

Out of scope (intentional)

Out-of-scope item	Why
Running new benchmarks vs moka	Needs a separate proposal (workload selection, CI compute). Document plans/proposals/perf-vs-moka.md using PROPOSAL_TEMPLATE.md.
Migration guide moka → cache-kit	Different artifact (worked examples, not comparison). Separate spec when picked up.
The other 10 review recommendations	Circuit breaker, observability, cache warming, etc. Each gets its own spec. v0.9.2 stays scoped to (1) error codes and (2) this comparison page.

Test plan

• Read the spec top-to-bottom. Confirm Invariants section names enforceable checks (no ⭐, §4 non-empty, every perf claim cited).
• Confirm prologue (5 file pointers) lists moka's README — non-negotiable for honest comparison.
• Confirm Failure Modes table includes "moka's strengths get hand-waved" with the §4 mandate as the guard.
• Confirm Out of Scope explicitly carves out the other 10 review recommendations — they're not bundled.
• Once spec lands on main: open feat/m092-vs-other-caches per CHORE(open), write the page, run cd site && npm run build.

🤖 Generated with Claude Code

[indykish]

Consolidated into #2 (docs/nextjs-netlify-migration). Same spec content, single PR.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@2be07bf). Learn more about missing BASE report.
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@           Coverage Diff           @@
##             main       #4   +/-   ##
=======================================
  Coverage        ?   73.03%           
=======================================
  Files           ?       14           
  Lines           ?     2173           
  Branches        ?        0           
=======================================
  Hits            ?     1587           
  Misses          ?      586           
  Partials        ?        0           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.