refkitjs · github-actions · Jul 18, 2026
diff --git a/.changeset/cursor-v2-binary-encoding.md b/.changeset/cursor-v2-binary-encoding.md
diff --git a/.changeset/mcp-max-cursor-seen-env.md b/.changeset/mcp-max-cursor-seen-env.md
diff --git a/packages/core/CHANGELOG.md b/packages/core/CHANGELOG.md
@@ -1,5 +1,36 @@
 # @refkit/core
 
+## 0.8.0
+
+### Minor Changes
+
+- b5bbba8: Shrink the load-more cursor to roughly half its size: `meta.nextCursor` is now
+  a binary-packed base64url string (magic + version + page + raw fnv1a uint32
+  seen-keys) instead of v1's JSON array of base36 hash strings — a full 500-entry
+  cursor drops from ~5k to ~2.7k chars. Cursors ride inside LLM tool outputs
+  downstream (and get replayed through conversation history), so every char
+  counts; ~2.7k also clears consumers that clamp tool-output strings at 4k.
+
+  The cursor stays opaque and self-contained: pass back `meta.nextCursor`, get
+  the next deduped batch, no caller-side bookkeeping, no client instance state.
+  Anything else — including a v1 JSON cursor from a previous release — still
+  fails loudly with "invalid cursor" rather than quietly restarting from page 1
+  (cursors are short-lived load-more state, not durable ids; there is no v1
+  migration).
+
+  New `createRefkit({ maxCursorSeen })` caps how many already-returned keys the
+  cursor remembers (default unchanged at 500, most recent kept, ~5.4 chars each)
+  for callers who want an even tighter cursor and can accept re-showing
+  long-evicted results sooner. `Infinity` disables the cap; the effective floor
+  is the batch just returned, so a too-small cap can never make load-more repeat
+  the batch it just handed back.
+
+  Hardening over v1, both restoring guarantees the removed zod schema provided:
+  an out-of-uint32-range `controls.page` (negative, fractional, `NaN`, ≥ 2^32)
+  encodes as a poison cursor that fails loudly on the next call instead of
+  silently wrapping to a different page, and non-canonical base64url (tampered
+  trailing bits) is rejected rather than silently aliased to a valid cursor.
+
 ## 0.7.0
 
 ### Minor Changes

diff --git a/packages/core/package.json b/packages/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@refkit/core",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "refkit core — neutral reference-retrieval brain: Reference/RightsRecord contract, license normalization, strict-deny use-gate, RRF merge/dedup, ReferenceProvider interfaces. Zero-network, zero-provider, only zod.",
   "type": "module",
   "license": "Apache-2.0",

diff --git a/packages/mcp/CHANGELOG.md b/packages/mcp/CHANGELOG.md
@@ -1,5 +1,29 @@
 # @refkit/mcp
 
+## 0.7.0
+
+### Minor Changes
+
+- b5bbba8: `REFKIT_MAX_CURSOR_SEEN` env var for the zero-config CLI: caps how many
+  already-returned keys the load-more cursor remembers (core's `maxCursorSeen`),
+  for hosts that clamp tool-output strings — the default 500-key cursor is ~2.7k
+  chars; `REFKIT_MAX_CURSOR_SEEN=200` brings it near ~1.1k. Invalid values warn
+  on stderr and fall back to the core default.
+
+### Patch Changes
+
+- Updated dependencies [b5bbba8]
+  - @refkit/core@0.8.0
+  - @refkit/provider-artic@0.2.5
+  - @refkit/provider-gutendex@0.2.6
+  - @refkit/provider-internet-archive@0.3.3
+  - @refkit/provider-met@0.2.5
+  - @refkit/provider-openverse@0.3.3
+  - @refkit/provider-poetrydb@0.2.5
+  - @refkit/provider-polyhaven@0.2.4
+  - @refkit/provider-rijksmuseum@0.2.4
+  - @refkit/provider-wikimedia-commons@0.3.3
+
 ## 0.6.1
 
 ### Patch Changes

diff --git a/packages/mcp/package.json b/packages/mcp/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@refkit/mcp",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "MCP server for refkit — exposes license-normalized reference search as an agent tool.",
   "type": "module",
   "license": "Apache-2.0",

diff --git a/packages/provider-artic/CHANGELOG.md b/packages/provider-artic/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @refkit/provider-artic
 
+## 0.2.5
+
+### Patch Changes
+
+- Updated dependencies [b5bbba8]
+  - @refkit/core@0.8.0
+
 ## 0.2.4
 
 ### Patch Changes

diff --git a/packages/provider-artic/package.json b/packages/provider-artic/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@refkit/provider-artic",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Art Institute of Chicago provider satellite for refkit.",
   "type": "module",
   "license": "Apache-2.0",

diff --git a/packages/provider-brave/CHANGELOG.md b/packages/provider-brave/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @refkit/provider-brave
 
+## 0.2.5
+
+### Patch Changes
+
+- Updated dependencies [b5bbba8]
+  - @refkit/core@0.8.0
+
 ## 0.2.4
 
 ### Patch Changes

diff --git a/packages/provider-brave/package.json b/packages/provider-brave/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@refkit/provider-brave",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Brave Search web-discovery provider satellite for refkit — open-web image breadth, license:unknown (use-gated to needs-review).",
   "type": "module",
   "license": "Apache-2.0",

diff --git a/packages/provider-europeana/CHANGELOG.md b/packages/provider-europeana/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @refkit/provider-europeana
 
+## 0.3.3
+
+### Patch Changes
+
+- Updated dependencies [b5bbba8]
+  - @refkit/core@0.8.0
+
 ## 0.3.2
 
 ### Patch Changes

diff --git a/packages/provider-europeana/package.json b/packages/provider-europeana/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@refkit/provider-europeana",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Europeana provider satellite for refkit.",
   "type": "module",
   "license": "Apache-2.0",

diff --git a/packages/provider-flickr/CHANGELOG.md b/packages/provider-flickr/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @refkit/provider-flickr
 
+## 0.3.3
+
+### Patch Changes
+
+- Updated dependencies [b5bbba8]
+  - @refkit/core@0.8.0
+
 ## 0.3.2
 
 ### Patch Changes

diff --git a/packages/provider-flickr/package.json b/packages/provider-flickr/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@refkit/provider-flickr",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Flickr provider satellite for refkit.",
   "type": "module",
   "license": "Apache-2.0",

diff --git a/packages/provider-freesound/CHANGELOG.md b/packages/provider-freesound/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @refkit/provider-freesound
 
+## 0.3.3
+
+### Patch Changes
+
+- Updated dependencies [b5bbba8]
+  - @refkit/core@0.8.0
+
 ## 0.3.2
 
 ### Patch Changes

diff --git a/packages/provider-freesound/package.json b/packages/provider-freesound/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@refkit/provider-freesound",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Freesound provider satellite for refkit.",
   "type": "module",
   "license": "Apache-2.0",

diff --git a/packages/provider-gutendex/CHANGELOG.md b/packages/provider-gutendex/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @refkit/provider-gutendex
 
+## 0.2.6
+
+### Patch Changes
+
+- Updated dependencies [b5bbba8]
+  - @refkit/core@0.8.0
+
 ## 0.2.5
 
 ### Patch Changes

diff --git a/packages/provider-gutendex/package.json b/packages/provider-gutendex/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@refkit/provider-gutendex",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Gutendex (Project Gutenberg) provider satellite for refkit — public-domain book references, per-item copyright→license.",
   "type": "module",
   "license": "Apache-2.0",

diff --git a/packages/provider-internet-archive/CHANGELOG.md b/packages/provider-internet-archive/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @refkit/provider-internet-archive
 
+## 0.3.3
+
+### Patch Changes
+
+- Updated dependencies [b5bbba8]
+  - @refkit/core@0.8.0
+
 ## 0.3.2
 
 ### Patch Changes

diff --git a/packages/provider-internet-archive/package.json b/packages/provider-internet-archive/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@refkit/provider-internet-archive",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Internet Archive provider satellite for refkit.",
   "type": "module",
   "license": "Apache-2.0",

diff --git a/packages/provider-jamendo/CHANGELOG.md b/packages/provider-jamendo/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @refkit/provider-jamendo
 
+## 0.3.3
+
+### Patch Changes
+
+- Updated dependencies [b5bbba8]
+  - @refkit/core@0.8.0
+
 ## 0.3.2
 
 ### Patch Changes

diff --git a/packages/provider-jamendo/package.json b/packages/provider-jamendo/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@refkit/provider-jamendo",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Jamendo provider satellite for refkit.",
   "type": "module",
   "license": "Apache-2.0",

diff --git a/packages/provider-met/CHANGELOG.md b/packages/provider-met/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @refkit/provider-met
 
+## 0.2.5
+
+### Patch Changes
+
+- Updated dependencies [b5bbba8]
+  - @refkit/core@0.8.0
+
 ## 0.2.4
 
 ### Patch Changes

diff --git a/packages/provider-met/package.json b/packages/provider-met/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@refkit/provider-met",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "The Metropolitan Museum of Art provider satellite for refkit.",
   "type": "module",
   "license": "Apache-2.0",

diff --git a/packages/provider-openverse/CHANGELOG.md b/packages/provider-openverse/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @refkit/provider-openverse
 
+## 0.3.3
+
+### Patch Changes
+
+- Updated dependencies [b5bbba8]
+  - @refkit/core@0.8.0
+
 ## 0.3.2
 
 ### Patch Changes

diff --git a/packages/provider-openverse/package.json b/packages/provider-openverse/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@refkit/provider-openverse",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Openverse provider satellite for refkit — CC/PD licensed image search, license-normalized.",
   "type": "module",
   "license": "Apache-2.0",

diff --git a/packages/provider-pexels/CHANGELOG.md b/packages/provider-pexels/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @refkit/provider-pexels
 
+## 0.2.5
+
+### Patch Changes
+
+- Updated dependencies [b5bbba8]
+  - @refkit/core@0.8.0
+
 ## 0.2.4
 
 ### Patch Changes

diff --git a/packages/provider-pexels/package.json b/packages/provider-pexels/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@refkit/provider-pexels",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Pexels provider satellite for refkit — image search, hotlink-required.",
   "type": "module",
   "license": "Apache-2.0",

diff --git a/packages/provider-pixabay/CHANGELOG.md b/packages/provider-pixabay/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @refkit/provider-pixabay
 
+## 0.2.5
+
+### Patch Changes
+
+- Updated dependencies [b5bbba8]
+  - @refkit/core@0.8.0
+
 ## 0.2.4
 
 ### Patch Changes

diff --git a/packages/provider-pixabay/package.json b/packages/provider-pixabay/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@refkit/provider-pixabay",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Pixabay provider satellite for refkit — image search, cache-allowed.",
   "type": "module",
   "license": "Apache-2.0",

diff --git a/packages/provider-poetrydb/CHANGELOG.md b/packages/provider-poetrydb/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @refkit/provider-poetrydb
 
+## 0.2.5
+
+### Patch Changes
+
+- Updated dependencies [b5bbba8]
+  - @refkit/core@0.8.0
+
 ## 0.2.4
 
 ### Patch Changes

diff --git a/packages/provider-poetrydb/package.json b/packages/provider-poetrydb/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@refkit/provider-poetrydb",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "PoetryDB provider satellite for refkit — classic public-domain poems.",
   "type": "module",
   "license": "Apache-2.0",