Version Packages

packages/core/CHANGELOG.md

@@ -1,5 +1,67 @@
 # @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.
+
+- 431d834: Provider resource declarations: open `ResourceKind` vocabulary with optional
+  `kinds` + `description` on providers and `kind` on references; declaration-gated
+  kind routing (a kind-filtered search skips providers whose declared `kinds`
+  lack the value, with a new `unsupported-kind` skip reason) composed with the
+  existing `sources` id filter; MCP tool schema, per-provider source list, and
+  the `modalities` / `media.kind` enums now derived from registered provider
+  declarations at startup.
+
+  Note: the MCP `modalities` input enum is now deployment-dependent (derived
+  from the registered providers). A request naming a modality no registered
+  provider supports is now rejected at the schema boundary — previously a
+  fully-unsupported request threw at search time, and a mixed request (e.g.
+  image+audio against an image-only deployment) returned the supported subset.
+  Fail-loud at the boundary is intentional.
+
+- aa4b048: Add source-targeted search. `SearchInput.sources?: string[]` restricts a search
+  to specific provider ids (intersected with modality matching); omit it to fan out
+  to every configured source as before. This lets a caller scope a search-engine
+  operator — e.g. `site:xiaohongshu.com` against Brave's index — to one
+  web-discovery source without polluting the other providers' queries.
+
+  Selection stays fail-loud: a `sources` list that matches no configured provider
+  for the requested modalities throws (a typo must not read as "no results"), while
+  an id that resolves to nothing when others still match is reported in
+  `meta.warnings`. Providers excluded by an explicit `sources` filter now report
+  `reason: 'not-selected'` in `meta.providers`, distinct from `'unsupported-modality'`.
+
+  `@refkit/mcp`'s `search_references` tool gains a `sources` parameter (its
+  description enumerates the server's enabled source ids) and turns a
+  source-selection miss into an agent-friendly tool error that lists the valid ids.
+
 ## 0.7.0
 
 ### Minor Changes

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",

packages/mcp/CHANGELOG.md

@@ -1,5 +1,77 @@
 # @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.
+- 17469ad: New keyless provider `@refkit/provider-nailbook` — image references from Nailbook
+  (nailbook.jp), a large Japanese nail-design catalog. Recall is best with Japanese tag
+  words (マグネット, ニュアンス, ちゅるん…). Results are discovery-class: no per-item
+  license metadata, so each carries `license: 'unknown'` + `rehostPolicy: 'thumbnail-only'`
+  and gates to `needs-review` (never auto-allowed) — surface the CDN thumbnail only, never
+  rehost the original.
+
+  Rather than scraping the client-rendered `/design/` list HTML (whose embedded bootstrap
+  carries photo IDs but no image URLs), the provider calls the same JSON endpoint the site's
+  own frontend uses (`POST /api/web/photo/search`), returning full photo objects in one
+  request. Each `search()` makes exactly one request with no multi-page fan-out.
+
+  `@refkit/mcp` boots Nailbook in its zero-config keyless default set.
+
+- 431d834: Provider resource declarations: open `ResourceKind` vocabulary with optional
+  `kinds` + `description` on providers and `kind` on references; declaration-gated
+  kind routing (a kind-filtered search skips providers whose declared `kinds`
+  lack the value, with a new `unsupported-kind` skip reason) composed with the
+  existing `sources` id filter; MCP tool schema, per-provider source list, and
+  the `modalities` / `media.kind` enums now derived from registered provider
+  declarations at startup.
+
+  Note: the MCP `modalities` input enum is now deployment-dependent (derived
+  from the registered providers). A request naming a modality no registered
+  provider supports is now rejected at the schema boundary — previously a
+  fully-unsupported request threw at search time, and a mixed request (e.g.
+  image+audio against an image-only deployment) returned the supported subset.
+  Fail-loud at the boundary is intentional.
+
+- aa4b048: Add source-targeted search. `SearchInput.sources?: string[]` restricts a search
+  to specific provider ids (intersected with modality matching); omit it to fan out
+  to every configured source as before. This lets a caller scope a search-engine
+  operator — e.g. `site:xiaohongshu.com` against Brave's index — to one
+  web-discovery source without polluting the other providers' queries.
+
+  Selection stays fail-loud: a `sources` list that matches no configured provider
+  for the requested modalities throws (a typo must not read as "no results"), while
+  an id that resolves to nothing when others still match is reported in
+  `meta.warnings`. Providers excluded by an explicit `sources` filter now report
+  `reason: 'not-selected'` in `meta.providers`, distinct from `'unsupported-modality'`.
+
+  `@refkit/mcp`'s `search_references` tool gains a `sources` parameter (its
+  description enumerates the server's enabled source ids) and turns a
+  source-selection miss into an agent-friendly tool error that lists the valid ids.
+
+### Patch Changes
+
+- Updated dependencies [b5bbba8]
+- Updated dependencies [17469ad]
+- Updated dependencies [431d834]
+- Updated dependencies [aa4b048]
+  - @refkit/core@0.8.0
+  - @refkit/provider-nailbook@0.1.0
+  - @refkit/provider-wikimedia-commons@0.4.0
+  - @refkit/provider-openverse@0.4.0
+  - @refkit/provider-met@0.3.0
+  - @refkit/provider-artic@0.3.0
+  - @refkit/provider-rijksmuseum@0.3.0
+  - @refkit/provider-gutendex@0.3.0
+  - @refkit/provider-poetrydb@0.3.0
+  - @refkit/provider-internet-archive@0.4.0
+  - @refkit/provider-polyhaven@0.3.0
+
 ## 0.6.1
 
 ### Patch Changes

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",

packages/provider-artic/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @refkit/provider-artic
 
+## 0.3.0
+
+### Minor Changes
+
+- 431d834: Provider resource declarations: open `ResourceKind` vocabulary with optional
+  `kinds` + `description` on providers and `kind` on references; declaration-gated
+  kind routing (a kind-filtered search skips providers whose declared `kinds`
+  lack the value, with a new `unsupported-kind` skip reason) composed with the
+  existing `sources` id filter; MCP tool schema, per-provider source list, and
+  the `modalities` / `media.kind` enums now derived from registered provider
+  declarations at startup.
+
+  Note: the MCP `modalities` input enum is now deployment-dependent (derived
+  from the registered providers). A request naming a modality no registered
+  provider supports is now rejected at the schema boundary — previously a
+  fully-unsupported request threw at search time, and a mixed request (e.g.
+  image+audio against an image-only deployment) returned the supported subset.
+  Fail-loud at the boundary is intentional.
+
+### Patch Changes
+
+- Updated dependencies [b5bbba8]
+- Updated dependencies [431d834]
+- Updated dependencies [aa4b048]
+  - @refkit/core@0.8.0
+
 ## 0.2.4
 
 ### Patch Changes

packages/provider-artic/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@refkit/provider-artic",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Art Institute of Chicago provider satellite for refkit.",
   "type": "module",
   "license": "Apache-2.0",

packages/provider-brave/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @refkit/provider-brave
 
+## 0.3.0
+
+### Minor Changes
+
+- 431d834: Provider resource declarations: open `ResourceKind` vocabulary with optional
+  `kinds` + `description` on providers and `kind` on references; declaration-gated
+  kind routing (a kind-filtered search skips providers whose declared `kinds`
+  lack the value, with a new `unsupported-kind` skip reason) composed with the
+  existing `sources` id filter; MCP tool schema, per-provider source list, and
+  the `modalities` / `media.kind` enums now derived from registered provider
+  declarations at startup.
+
+  Note: the MCP `modalities` input enum is now deployment-dependent (derived
+  from the registered providers). A request naming a modality no registered
+  provider supports is now rejected at the schema boundary — previously a
+  fully-unsupported request threw at search time, and a mixed request (e.g.
+  image+audio against an image-only deployment) returned the supported subset.
+  Fail-loud at the boundary is intentional.
+
+### Patch Changes
+
+- Updated dependencies [b5bbba8]
+- Updated dependencies [431d834]
+- Updated dependencies [aa4b048]
+  - @refkit/core@0.8.0
+
 ## 0.2.4
 
 ### Patch Changes

packages/provider-brave/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@refkit/provider-brave",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "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",

packages/provider-europeana/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @refkit/provider-europeana
 
+## 0.4.0
+
+### Minor Changes
+
+- 431d834: Provider resource declarations: open `ResourceKind` vocabulary with optional
+  `kinds` + `description` on providers and `kind` on references; declaration-gated
+  kind routing (a kind-filtered search skips providers whose declared `kinds`
+  lack the value, with a new `unsupported-kind` skip reason) composed with the
+  existing `sources` id filter; MCP tool schema, per-provider source list, and
+  the `modalities` / `media.kind` enums now derived from registered provider
+  declarations at startup.
+
+  Note: the MCP `modalities` input enum is now deployment-dependent (derived
+  from the registered providers). A request naming a modality no registered
+  provider supports is now rejected at the schema boundary — previously a
+  fully-unsupported request threw at search time, and a mixed request (e.g.
+  image+audio against an image-only deployment) returned the supported subset.
+  Fail-loud at the boundary is intentional.
+
+### Patch Changes
+
+- Updated dependencies [b5bbba8]
+- Updated dependencies [431d834]
+- Updated dependencies [aa4b048]
+  - @refkit/core@0.8.0
+
 ## 0.3.2
 
 ### Patch Changes