# AGENTS.md — SuperCache

Notes for AI coding agents working **with** or **on** this library.

This repository ships agent skills that teach the library's correct usage
from consuming applications. Read the one matching your task before writing
SuperCache code:

| Task | Read |
|------|------|
| Start/cache CRUD in a consumer app | [`skills/super-cache/SKILL.md`](skills/super-cache/SKILL.md) |
| KeyValue / Queue / Stack / Struct | [`skills/super-cache-collections/SKILL.md`](skills/super-cache-collections/SKILL.md) |
| Multi-node cluster setup & debugging | [`skills/super-cache-distributed/SKILL.md`](skills/super-cache-distributed/SKILL.md) |

## The one rule agents break most often

A record's identity is its element at `key_pos` (**index 0 by default**).
With defaults, `put!({:user, 1, a})` then `put!({:user, 2, b})` leaves ONE
record — both are keyed by `:user`. Use a composite key as element 0
(`{{:user, 1}, data}`) or configure `key_pos:` to point at a unique field.

Other non-obvious behaviours:

- All `get*` functions return a **list of tuples**, never nil/a bare record.
- `Queue.get_all/1` and `Stack.get_all/1` **drain** their structure.
- `delete_all/0` is global and destructive.
- There is no TTL; expiry is application-managed.
- Distributed mode requires identical structural opts on every node;
  mismatches raise at join time.

## Working on this repo (not a consumer app)

- Unit tests: `mix test` (cluster excluded). Cluster tests: `mix test.cluster`
  (spawns real peer nodes; requires distribution).
- Coverage: `mix test --cover`; per-module uncovered lines:
  `elixir -S mix run tools/coverage/uncovered.exs` (run after `--cover`).
- Full docs: `guides/Usage.md`, `guides/Distributed.md`, `guides/Developer.md`.