refkitjs · MyPrototypeWhat · Jul 16, 2026 · Jul 14, 2026
diff --git a/.changeset/architecture-review-core.md b/.changeset/architecture-review-core.md
diff --git a/.changeset/architecture-review-mcp.md b/.changeset/architecture-review-mcp.md
diff --git a/.changeset/architecture-review-providers.md b/.changeset/architecture-review-providers.md
diff --git a/packages/core/CHANGELOG.md b/packages/core/CHANGELOG.md
@@ -1,5 +1,20 @@
 # @refkit/core
 
+## 0.7.0
+
+### Minor Changes
+
+- 3cce5e3: Architecture-review hardening:
+
+  - **Conservative cross-source rights merge** — when two sources disagree about the license of the same canonical URL, the stricter license wins (incomparable claims collapse to `unknown` → needs-review); conflicts surface in `meta.warnings` and via the new `merge.onRightsConflict` observer. New export: `stricterLicense`, `RightsConflict`.
+  - **Unified pagination cursor** — `SearchInput.cursor` + `meta.nextCursor`: opaque load-more cursor that first drains the current provider page's overfetched pool, then advances the provider-local page internally, deduping against previously returned results (seen-set capped so cursors stay small).
+  - **CJK-aware `tokenize`** — CJK runs tokenize into character bigrams, so `lexicalReranker` scores Chinese/Japanese/Korean queries instead of dropping them.
+  - **Collision-proof cache keys** — per-provider cache keys stay short and fixed-shape (safe for strict KV backends), while the cached value embeds the full normalized-query fingerprint and is verified on read: a key collision degrades to a cache miss, never to another query's results. Existing cache entries are invalidated by the format change (`refkit:v2:`).
+  - New `cacheRaw: false` option strips `raw` provider payloads from cache entries.
+  - New `concurrency` option bounds how many provider searches run at once per search call (default unlimited, matching previous behavior); a queued provider's timeout starts only when it actually runs.
+  - **Deprecations (single-track capability routing)** — `SearchFilters`, `SearchInput.filters`, `NormalizedQuery.filters`, `ReferenceProvider.queryFeatures` (now optional), and `QueryFeature` are deprecated. Routing is driven solely by `capabilities.controls`; legacy `filters` are merged into `controls` and the deprecated `NormalizedQuery.filters` channel is derived from the routed controls, so both channels always agree. Providers that declared filter support only via `queryFeatures` must declare `capabilities.controls` to keep receiving those values.
+  - `runProviderSearch` / `providerCacheKey` / `stableStringify` extracted and exported (`provider-run`), shrinking the search orchestrator.
+
 ## 0.6.1
 
 ### Patch Changes

diff --git a/packages/core/package.json b/packages/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@refkit/core",
-  "version": "0.6.1",
+  "version": "0.7.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,28 @@
 # @refkit/mcp
 
+## 0.6.0
+
+### Minor Changes
+
+- 3cce5e3: - `search_references` gains `rerank: true` (query-aware re-ranking via `lexicalReranker`, CJK-aware) and `cursor` (load-more pagination with cross-page dedup; the continuation token is returned as top-level `nextCursor` on every call, independent of `explain`).
+  - BYOK provider packages are explicitly externalized from the tsup bundle so dynamic imports resolve from node_modules at runtime — `--omit=optional` actually omits them, and provider patch releases reach `@refkit/mcp` users without a republish.
+  - BYOK provider packages moved from `dependencies` to `optionalDependencies` and are now loaded lazily, only when their key is present. Default installs (incl. `npx -y @refkit/mcp`) still get everything; installs with `--omit=optional` skip BYOK sources, and a key whose package is missing logs a stderr warning instead of crashing. `defaultProviders()` is now async.
+
+### Patch Changes
+
+- Updated dependencies [3cce5e3]
+- Updated dependencies [3cce5e3]
+  - @refkit/core@0.7.0
+  - @refkit/provider-openverse@0.3.2
+  - @refkit/provider-internet-archive@0.3.2
+  - @refkit/provider-wikimedia-commons@0.3.2
+  - @refkit/provider-artic@0.2.4
+  - @refkit/provider-met@0.2.4
+  - @refkit/provider-polyhaven@0.2.3
+  - @refkit/provider-gutendex@0.2.4
+  - @refkit/provider-poetrydb@0.2.4
+  - @refkit/provider-rijksmuseum@0.2.3
+
 ## 0.5.1
 
 ### Patch Changes

diff --git a/packages/mcp/package.json b/packages/mcp/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@refkit/mcp",
-  "version": "0.5.1",
+  "version": "0.6.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,13 @@
 # @refkit/provider-artic
 
+## 0.2.4
+
+### Patch Changes
+
+- 3cce5e3: Declare and honor the `page` search control (`capabilities.controls: ['page']`), wiring `controls.page` to each source's native pagination — native `page` params where they exist, offset translation for offset-based APIs (Wikimedia `gsroffset`, Smithsonian/Europeana `start`, Jamendo/ambientCG `offset`), and a window over the full result list for Met/Poly Haven. Enables core's unified load-more cursor across these sources. (Brave, PoetryDB, and Rijksmuseum expose no usable offset pagination and keep `page` undeclared.)
+- Updated dependencies [3cce5e3]
+  - @refkit/core@0.7.0
+
 ## 0.2.3
 
 ### 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.3",
+  "version": "0.2.4",
   "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.4
+
+### Patch Changes
+
+- Updated dependencies [3cce5e3]
+  - @refkit/core@0.7.0
+
 ## 0.2.3
 
 ### 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.3",
+  "version": "0.2.4",
   "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,13 @@
 # @refkit/provider-europeana
 
+## 0.3.2
+
+### Patch Changes
+
+- 3cce5e3: Declare and honor the `page` search control (`capabilities.controls: ['page']`), wiring `controls.page` to each source's native pagination — native `page` params where they exist, offset translation for offset-based APIs (Wikimedia `gsroffset`, Smithsonian/Europeana `start`, Jamendo/ambientCG `offset`), and a window over the full result list for Met/Poly Haven. Enables core's unified load-more cursor across these sources. (Brave, PoetryDB, and Rijksmuseum expose no usable offset pagination and keep `page` undeclared.)
+- Updated dependencies [3cce5e3]
+  - @refkit/core@0.7.0
+
 ## 0.3.1
 
 ### 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.1",
+  "version": "0.3.2",
   "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,13 @@
 # @refkit/provider-flickr
 
+## 0.3.2
+
+### Patch Changes
+
+- 3cce5e3: Declare and honor the `page` search control (`capabilities.controls: ['page']`), wiring `controls.page` to each source's native pagination — native `page` params where they exist, offset translation for offset-based APIs (Wikimedia `gsroffset`, Smithsonian/Europeana `start`, Jamendo/ambientCG `offset`), and a window over the full result list for Met/Poly Haven. Enables core's unified load-more cursor across these sources. (Brave, PoetryDB, and Rijksmuseum expose no usable offset pagination and keep `page` undeclared.)
+- Updated dependencies [3cce5e3]
+  - @refkit/core@0.7.0
+
 ## 0.3.1
 
 ### 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.1",
+  "version": "0.3.2",
   "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,13 @@
 # @refkit/provider-freesound
 
+## 0.3.2
+
+### Patch Changes
+
+- 3cce5e3: Declare and honor the `page` search control (`capabilities.controls: ['page']`), wiring `controls.page` to each source's native pagination — native `page` params where they exist, offset translation for offset-based APIs (Wikimedia `gsroffset`, Smithsonian/Europeana `start`, Jamendo/ambientCG `offset`), and a window over the full result list for Met/Poly Haven. Enables core's unified load-more cursor across these sources. (Brave, PoetryDB, and Rijksmuseum expose no usable offset pagination and keep `page` undeclared.)
+- Updated dependencies [3cce5e3]
+  - @refkit/core@0.7.0
+
 ## 0.3.1
 
 ### 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.1",
+  "version": "0.3.2",
   "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.4
+
+### Patch Changes
+
+- Updated dependencies [3cce5e3]
+  - @refkit/core@0.7.0
+
 ## 0.2.3
 
 ### 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.3",
+  "version": "0.2.4",
   "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,13 @@
 # @refkit/provider-internet-archive
 
+## 0.3.2
+
+### Patch Changes
+
+- 3cce5e3: Declare and honor the `page` search control (`capabilities.controls: ['page']`), wiring `controls.page` to each source's native pagination — native `page` params where they exist, offset translation for offset-based APIs (Wikimedia `gsroffset`, Smithsonian/Europeana `start`, Jamendo/ambientCG `offset`), and a window over the full result list for Met/Poly Haven. Enables core's unified load-more cursor across these sources. (Brave, PoetryDB, and Rijksmuseum expose no usable offset pagination and keep `page` undeclared.)
+- Updated dependencies [3cce5e3]
+  - @refkit/core@0.7.0
+
 ## 0.3.1
 
 ### 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.1",
+  "version": "0.3.2",
   "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,13 @@
 # @refkit/provider-jamendo
 
+## 0.3.2
+
+### Patch Changes
+
+- 3cce5e3: Declare and honor the `page` search control (`capabilities.controls: ['page']`), wiring `controls.page` to each source's native pagination — native `page` params where they exist, offset translation for offset-based APIs (Wikimedia `gsroffset`, Smithsonian/Europeana `start`, Jamendo/ambientCG `offset`), and a window over the full result list for Met/Poly Haven. Enables core's unified load-more cursor across these sources. (Brave, PoetryDB, and Rijksmuseum expose no usable offset pagination and keep `page` undeclared.)
+- Updated dependencies [3cce5e3]
+  - @refkit/core@0.7.0
+
 ## 0.3.1
 
 ### 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.1",
+  "version": "0.3.2",
   "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,13 @@
 # @refkit/provider-met
 
+## 0.2.4
+
+### Patch Changes
+
+- 3cce5e3: Declare and honor the `page` search control (`capabilities.controls: ['page']`), wiring `controls.page` to each source's native pagination — native `page` params where they exist, offset translation for offset-based APIs (Wikimedia `gsroffset`, Smithsonian/Europeana `start`, Jamendo/ambientCG `offset`), and a window over the full result list for Met/Poly Haven. Enables core's unified load-more cursor across these sources. (Brave, PoetryDB, and Rijksmuseum expose no usable offset pagination and keep `page` undeclared.)
+- Updated dependencies [3cce5e3]
+  - @refkit/core@0.7.0
+
 ## 0.2.3
 
 ### 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.3",
+  "version": "0.2.4",
   "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,13 @@
 # @refkit/provider-openverse
 
+## 0.3.2
+
+### Patch Changes
+
+- 3cce5e3: Declare and honor the `page` search control (`capabilities.controls: ['page']`), wiring `controls.page` to each source's native pagination — native `page` params where they exist, offset translation for offset-based APIs (Wikimedia `gsroffset`, Smithsonian/Europeana `start`, Jamendo/ambientCG `offset`), and a window over the full result list for Met/Poly Haven. Enables core's unified load-more cursor across these sources. (Brave, PoetryDB, and Rijksmuseum expose no usable offset pagination and keep `page` undeclared.)
+- Updated dependencies [3cce5e3]
+  - @refkit/core@0.7.0
+
 ## 0.3.1
 
 ### 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.1",
+  "version": "0.3.2",
   "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.4
+
+### Patch Changes
+
+- Updated dependencies [3cce5e3]
+  - @refkit/core@0.7.0
+
 ## 0.2.3
 
 ### 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.3",
+  "version": "0.2.4",
   "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,13 @@
 # @refkit/provider-pixabay
 
+## 0.2.4
+
+### Patch Changes
+
+- 3cce5e3: Declare and honor the `page` search control (`capabilities.controls: ['page']`), wiring `controls.page` to each source's native pagination — native `page` params where they exist, offset translation for offset-based APIs (Wikimedia `gsroffset`, Smithsonian/Europeana `start`, Jamendo/ambientCG `offset`), and a window over the full result list for Met/Poly Haven. Enables core's unified load-more cursor across these sources. (Brave, PoetryDB, and Rijksmuseum expose no usable offset pagination and keep `page` undeclared.)
+- Updated dependencies [3cce5e3]
+  - @refkit/core@0.7.0
+
 ## 0.2.3
 
 ### 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.3",
+  "version": "0.2.4",
   "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.4
+
+### Patch Changes
+
+- Updated dependencies [3cce5e3]
+  - @refkit/core@0.7.0
+
 ## 0.2.3
 
 ### 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.3",
+  "version": "0.2.4",
   "description": "PoetryDB provider satellite for refkit — classic public-domain poems.",
   "type": "module",
   "license": "Apache-2.0",