From d623b32fc4a7fba68305853232a9bc26ef719a2a Mon Sep 17 00:00:00 2001
From: Snider <snider@host.uk.com>
Date: Fri, 13 Mar 2026 13:38:01 +0000
Subject: [PATCH] docs: add CLAUDE.md project instructions

Co-Authored-By: Virgil <virgil@lethean.io>
---
 CLAUDE.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..0695937
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,53 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`go-cache` is a storage-agnostic, JSON-based caching library for Go. Module path: `forge.lthn.ai/core/go-cache`. The entire package is two files: `cache.go` and `cache_test.go`.
+
+## Commands
+
+```bash
+# Run all tests
+go test ./...
+
+# Run a single test
+go test -run TestCache ./...
+
+# QA pipeline (fmt + vet + lint + test) — requires `core` CLI
+core go qa
+core go qa full    # adds race detector, vuln scan, security audit
+
+# Individual checks
+core go fmt
+core go vet
+core go lint
+
+# Coverage
+core go cov
+core go cov --open
+```
+
+## Key Architecture Details
+
+- All I/O is delegated to the `io.Medium` interface from `forge.lthn.ai/core/go-io` — the cache never reads/writes files directly. This makes it backend-swappable (local FS, SQLite, S3, in-memory mock).
+- `Cache.Path()` enforces path-traversal protection on every public method — keys like `../../etc/passwd` are rejected before any I/O occurs.
+- Expired entries are not eagerly deleted; they remain on disk until overwritten or explicitly removed.
+- The struct has no mutex. Concurrent reads are safe, but concurrent writes to the same key need external synchronization.
+
+## Testing Conventions
+
+- Use `io.NewMockMedium()` for all tests — no real filesystem access.
+- Use `testing.T` directly, not testify.
+- Use short TTLs (milliseconds) for expiry tests.
+
+## Commit Conventions
+
+Conventional commits: `feat(cache):`, `fix(cache):`, `refactor:`, etc. The release config (`.core/release.yaml`) includes `feat`, `fix`, `perf`, `refactor` in changelogs.
+
+## Environment
+
+- Go 1.26+
+- Private modules: `GOPRIVATE=forge.lthn.ai/*`
+- Licence: EUPL-1.2