feat: production-ready polish

[devin-ai-integration]

Summary

Production-readiness improvements in a single PR. No API changes to Cache[K,V] itself.

New features:

• providers/local/ -- hash-based embedding provider for testing without API keys. Deterministic FNV hashing, L2-normalised. New options.WithLocalProvider option.
• examples/basic/ -- runnable example using the local provider.
• Makefile -- make test, make test-race, make bench, make lint, make check.

Architecture cleanup:

• Deleted errors/ package. Sentinel errors moved to owning packages: ErrClosed/ErrZeroKey/ErrInvalidN in root, ErrNilBackend/ErrNilProvider/ErrNilComparator in options/.
• Fixed CONTRIBUTING.md reference to types.CacheBackend (now types.Backend).

Test coverage:

• backends/inmemory/backend_test.go -- CRUD, eviction, overwrite, flush, interface compliance for LRU/LFU/FIFO.
• backends/inmemory/bench_test.go -- Set/Get/Keys benchmarks for all three backends.
• cache_bench_test.go -- Set/Get/Lookup/TopMatches benchmarks at the cache level.
• providers/local/local_test.go -- determinism, dimensions, normalisation, batch.

Documentation:

• Rewrote root README.md -- concise, no emojis, accurate API reference (sync-only).
• Added README.md (human docs) and AGENTS.md (agent instructions) to every module: types, options, backends, backends/inmemory, backends/remote, providers, providers/openai, providers/local, similarity, chunker, tokenizer.
• Updated root CLAUDE.md and AGENTS.md -- fixed import paths (botirk38), documented current architecture and error conventions.

Review & Testing Checklist for Human

• Verify the errors/ package deletion doesn't break any downstream code you have outside this repo that imported github.com/botirk38/semanticcache/errors
• Run go run ./examples/basic/ to confirm the example works
• Spot-check a few module READMEs and AGENTS.md files for accuracy
• Run make check (builds, tests with race detector, vet, fmt)

Notes

• The local provider vectors are NOT semantically meaningful -- they're for testing the plumbing only.
• The errors/ package removal is a breaking change for anyone who imported it directly. Since this is pre-1.0 and you confirmed no backward compat is needed, this is intentional.
• Net change: +1538 / -616 lines across 39 files.

Link to Devin session: https://app.devin.ai/sessions/1ffef0a58ad440e9aa7f1b64e537a98f
Requested by: @botirk38

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring