docs: improve cache_info() discoverability for observability

[27Bslash6]

Problem

When trying to access cache statistics (hits, misses, L1/L2 breakdown), it's not immediately obvious how to do this. I initially assumed prometheus metrics were exported automatically and searched for metric names like cache_operations_total.

Current State

The .cache_info() method on decorated functions works and follows the functools.lru_cache pattern:

from cachekit import cache

@cache(namespace="my_cache")
def expensive_func(x):
    return x * 2

# After some calls...
info = expensive_func.cache_info()
print(f"Hits: {info.hits}, L1: {info.l1_hits}, L2: {info.l2_hits}, Misses: {info.misses}")

However, this requires manual polling of each decorated function - not practical for production observability.

Suggestions

1. Add automatic prometheus metric export (feature request)

For production use, cachekit should optionally export prometheus metrics:

# Ideal API
from cachekit import cache, enable_prometheus_metrics

enable_prometheus_metrics()  # Registers with prometheus_client.REGISTRY

# Or via env var
# CACHEKIT_PROMETHEUS_ENABLED=true

Metrics to export:

• cachekit_hits_total{namespace, layer} - counter (layer = l1/l2)
• cachekit_misses_total{namespace} - counter
• cachekit_l2_latency_seconds{namespace} - histogram

This would integrate with existing monitoring stacks (Grafana, alerting, etc.) without custom code.

2. Document the cache_info() API

Add a "Monitoring & Observability" section to the README showing:

• How to access stats via .cache_info()
• Available CacheInfo fields (hits, l1_hits, l2_hits, misses, l2_avg_latency_ms)
• Example of building a simple stats endpoint

Context

Discovered while dogfooding cachekit in audiobook-optimizer. The caching itself works perfectly - production observability is the gap.