From 8812743562164c883aec6b8a201e76e46cd22e7b Mon Sep 17 00:00:00 2001 From: Tristan Farmer <159447266+001TMF@users.noreply.github.com> Date: Sun, 14 Jun 2026 01:59:03 +0100 Subject: [PATCH] docs(readme): document the local state dir and PINAKES_STATE_ROOT override The standalone-decoupling audit (Work Stream A1) flagged that the default local snapshot-store path (/pinakes) and the PINAKES_STATE_ROOT override were only in code comments + the ebola case study, with no pointer in the main README for a user to find/back-up/clear local state. Add a short "Local state" section. Docs only. No engine/idl/schema change. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/README.md b/README.md index f1b00ce..98687df 100644 --- a/README.md +++ b/README.md @@ -109,6 +109,22 @@ Get a free key from your [NCBI account](https://www.ncbi.nlm.nih.gov/account/) --- +## Local state + +Pinakes stores its content-addressed snapshots and reproducibility manifests under your OS cache +directory by default — `~/Library/Caches/pinakes` on macOS, `$XDG_CACHE_HOME/pinakes` (else +`~/.cache/pinakes`) on Linux. It is created on first use; back it up or clear it like any cache. +Relocate it with `PINAKES_STATE_ROOT`: + +```sh +export PINAKES_STATE_ROOT=/path/to/pinakes-state # where the local snapshot store lives +``` + +Everything stays local: a pinned query and its `pinakes verify` re-run read this directory with +**no network access**. + +--- + ## Why Pinakes Three guarantees, none of which a raw API call or a typical MCP wrapper gives you: