From 8300c189b89827fdcc9446d643d76de427c926bc Mon Sep 17 00:00:00 2001
From: MyPrototypeWhat <daoquqiexing@gmail.com>
Date: Mon, 6 Jul 2026 16:51:17 +0800
Subject: [PATCH 1/6] feat(core): programmable evaluatePermissions; evaluateUse
 intents become presets

---
 .changeset/evaluate-permissions.md            |  5 ++
 .../core/src/__tests__/evaluate-use.test.ts   | 31 +++++++-
 packages/core/src/evaluate-use.ts             | 73 +++++++++++++------
 packages/core/src/index.ts                    |  4 +-
 4 files changed, 89 insertions(+), 24 deletions(-)
 create mode 100644 .changeset/evaluate-permissions.md

diff --git a/.changeset/evaluate-permissions.md b/.changeset/evaluate-permissions.md
new file mode 100644
index 0000000..8acb6b4
--- /dev/null
+++ b/.changeset/evaluate-permissions.md
@@ -0,0 +1,5 @@
+---
+"@refkit/core": minor
+---
+
+Export evaluatePermissions/PermissionKey/EvaluateOptions — programmable strict-deny gate; evaluateUse intents are now presets over it (behavior unchanged).
diff --git a/packages/core/src/__tests__/evaluate-use.test.ts b/packages/core/src/__tests__/evaluate-use.test.ts
index 4da6995..62a828f 100644
--- a/packages/core/src/__tests__/evaluate-use.test.ts
+++ b/packages/core/src/__tests__/evaluate-use.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { evaluateUse, NOT_LEGAL_ADVICE } from '../evaluate-use'
+import { evaluatePermissions, evaluateUse, NOT_LEGAL_ADVICE } from '../evaluate-use'
 import type { RightsRecord } from '../rights'
 import { LICENSE_FACTS } from '../license'
 import type { LicenseId } from '../license'
@@ -102,3 +102,32 @@ describe('evaluateUse — strict-deny', () => {
     expect(evaluateUse(rec('CC-BY-ND'), 'redistribution').decision).toBe('allowed-with-attribution')
   })
 })
+
+describe('evaluatePermissions — programmable strict-deny gate', () => {
+  it('custom permission set: derivatives-only on CC-BY-ND → denied, naming CC-BY-ND', () => {
+    const v = evaluatePermissions(rec('CC-BY-ND'), ['derivatives'])
+    expect(v.decision).toBe('denied')
+    expect(v.reasons.join(' ')).toContain('CC-BY-ND')
+  })
+
+  it('empty required set on CC-BY with enforceAttribution (default true) → allowed-with-attribution', () => {
+    const v = evaluatePermissions(rec('CC-BY'), [])
+    expect(v.decision).toBe('allowed-with-attribution')
+  })
+
+  it('unknown license → needs-review regardless of required permissions', () => {
+    const v = evaluatePermissions(rec('unknown'), ['commercialUse', 'derivatives', 'redistribution'])
+    expect(v.decision).toBe('needs-review')
+    expect(v.confidence).toBe('low')
+  })
+
+  it('preset parity: evaluatePermissions(rec, [commercialUse], undefined, {denyEditorialOnly:true}) equals evaluateUse(rec, commercial-product)', () => {
+    const licenses: LicenseId[] = ['CC0-1.0', 'CC-BY', 'CC-BY-NC', 'CC-BY-ND', 'proprietary', 'unknown']
+    for (const license of licenses) {
+      const viaPermissions = evaluatePermissions(rec(license), ['commercialUse'], undefined, { denyEditorialOnly: true })
+      const viaUse = evaluateUse(rec(license), 'commercial-product')
+      expect(viaPermissions.decision).toBe(viaUse.decision)
+      expect(viaPermissions.reasons).toEqual(viaUse.reasons)
+    }
+  })
+})
diff --git a/packages/core/src/evaluate-use.ts b/packages/core/src/evaluate-use.ts
index 5a99180..ad62c44 100644
--- a/packages/core/src/evaluate-use.ts
+++ b/packages/core/src/evaluate-use.ts
@@ -14,37 +14,43 @@ export interface Verdict {
 export const NOT_LEGAL_ADVICE =
   'Heuristic based on source-declared license/ToS facts; not legal advice.'
 
-// Which permission(s) an intent requires to be granted (true).
-// strict-deny: a required permission that is false → denied; 'unknown' → needs-review.
-function requiredPermissions(intent: Intent): Array<keyof ReturnType<typeof factsFor>> {
-  switch (intent) {
-    case 'commercial-product': return ['commercialUse']
-    case 'ai-generation-input': return ['commercialUse', 'derivatives']
-    case 'redistribution': return ['redistribution']
-    case 'internal-moodboard': return [] // lenient; gated only by the unknown/proprietary checks below
-  }
+/** The tri-state permission axes of LicenseFacts. */
+export type PermissionKey = 'commercialUse' | 'derivatives' | 'redistribution'
+
+export interface EvaluateOptions {
+  /** Treat editorial-only sources as denied (commercial-flavored uses). Default false. */
+  denyEditorialOnly?: boolean
+  /** Enforce attributionRequired as allowed-with-attribution. Default true; presets
+   *  disable it for internal-moodboard (note-only). */
+  enforceAttribution?: boolean
 }
 
-export function evaluateUse(
+/** Low-level, programmable strict-deny gate: unknown license → needs-review;
+ *  jurisdiction mismatch → needs-review; each required permission false → denied,
+ *  'unknown' → needs-review; else allowed(-with-attribution). evaluateUse's four
+ *  intents are presets over this. */
+export function evaluatePermissions(
   r: RightsRecord,
-  intent: Intent,
+  required: readonly PermissionKey[],
   ctx?: { userJurisdiction?: string },
+  opts?: EvaluateOptions,
 ): Verdict {
+  const denyEditorialOnly = opts?.denyEditorialOnly ?? false
+  const enforceAttribution = opts?.enforceAttribution ?? true
+
   const facts = factsFor(r.license)
   const reasons: string[] = []
   const confidence: 'high' | 'low' = r.license === 'unknown' ? 'low' : 'high'
   const base = { reasons, confidence, disclaimer: NOT_LEGAL_ADVICE }
 
-  const commercialIntent = intent === 'commercial-product' || intent === 'ai-generation-input'
-
-  // Unknown license: never allowed — needs-review regardless of intent.
+  // Unknown license: never allowed — needs-review regardless of required permissions.
   if (r.license === 'unknown') {
     reasons.push('license could not be determined (strict-deny)')
     return { decision: 'needs-review', ...base }
   }
 
-  // editorial-only blocks commercial/AI use outright.
-  if (r.editorialOnly && commercialIntent) {
+  // editorial-only blocks commercial-flavored uses outright, when requested.
+  if (r.editorialOnly && denyEditorialOnly) {
     reasons.push('source marked editorial-only')
     return { decision: 'denied', ...base }
   }
@@ -57,7 +63,7 @@ export function evaluateUse(
   }
 
   // Evaluate the required permissions with strict-deny semantics.
-  for (const perm of requiredPermissions(intent)) {
+  for (const perm of required) {
     const value = facts[perm] as Tri
     if (value === false) {
       reasons.push(`${perm} not granted by ${r.license}`)
@@ -69,14 +75,39 @@ export function evaluateUse(
     }
   }
 
-  reasons.push(`permitted for ${intent} under ${r.license}`)
-  // internal-moodboard is lenient: attribution not enforced for internal-only use.
-  if (facts.attributionRequired && intent === 'internal-moodboard') {
+  reasons.push(`permitted for ${required.join('+') || 'use'} under ${r.license}`)
+  // Lenient callers (e.g. internal-moodboard) surface a note instead of enforcing.
+  if (facts.attributionRequired && !enforceAttribution) {
     reasons.push('attribution required by license but not enforced for internal-moodboard use')
   }
   const decision: Decision =
-    facts.attributionRequired && intent !== 'internal-moodboard'
+    facts.attributionRequired && enforceAttribution
       ? 'allowed-with-attribution'
       : 'allowed'
   return { decision, ...base }
 }
+
+// Which permission(s) an intent requires to be granted (true), plus the
+// evaluatePermissions options that reproduce evaluateUse's historical behavior.
+function presetFor(intent: Intent): { required: PermissionKey[]; opts: EvaluateOptions } {
+  switch (intent) {
+    case 'commercial-product':
+      return { required: ['commercialUse'], opts: { denyEditorialOnly: true, enforceAttribution: true } }
+    case 'ai-generation-input':
+      return { required: ['commercialUse', 'derivatives'], opts: { denyEditorialOnly: true, enforceAttribution: true } }
+    case 'redistribution':
+      return { required: ['redistribution'], opts: { denyEditorialOnly: false, enforceAttribution: true } }
+    case 'internal-moodboard':
+      // lenient; gated only by the unknown/jurisdiction checks in evaluatePermissions
+      return { required: [], opts: { denyEditorialOnly: false, enforceAttribution: false } }
+  }
+}
+
+export function evaluateUse(
+  r: RightsRecord,
+  intent: Intent,
+  ctx?: { userJurisdiction?: string },
+): Verdict {
+  const { required, opts } = presetFor(intent)
+  return evaluatePermissions(r, required, ctx, opts)
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 7bf122f..c4e9de3 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -20,8 +20,8 @@ export { hammingDistance, dedupeReferences } from './dedup'
 export type { DedupeOptions } from './dedup'
 export { mergeReferences } from './merge'
 export type { MergeOptions } from './merge'
-export { evaluateUse, NOT_LEGAL_ADVICE } from './evaluate-use'
-export type { Intent, Decision, Verdict } from './evaluate-use'
+export { evaluateUse, evaluatePermissions, NOT_LEGAL_ADVICE } from './evaluate-use'
+export type { Intent, Decision, Verdict, PermissionKey, EvaluateOptions } from './evaluate-use'
 export { defineProvider } from './provider'
 export type {
   ReferenceProvider,

From fdfafcf75decb1081c5e963c87824ed3dea40414 Mon Sep 17 00:00:00 2001
From: MyPrototypeWhat <daoquqiexing@gmail.com>
Date: Mon, 6 Jul 2026 16:56:33 +0800
Subject: [PATCH 2/6] fix(core): preserve evaluateUse's historical
 success-reason wording via preset label

---
 packages/core/src/__tests__/evaluate-use.test.ts | 13 +++++++++++--
 packages/core/src/evaluate-use.ts                | 15 ++++++++++-----
 2 files changed, 21 insertions(+), 7 deletions(-)

diff --git a/packages/core/src/__tests__/evaluate-use.test.ts b/packages/core/src/__tests__/evaluate-use.test.ts
index 62a828f..d85291a 100644
--- a/packages/core/src/__tests__/evaluate-use.test.ts
+++ b/packages/core/src/__tests__/evaluate-use.test.ts
@@ -121,13 +121,22 @@ describe('evaluatePermissions — programmable strict-deny gate', () => {
     expect(v.confidence).toBe('low')
   })
 
-  it('preset parity: evaluatePermissions(rec, [commercialUse], undefined, {denyEditorialOnly:true}) equals evaluateUse(rec, commercial-product)', () => {
+  it('preset parity: evaluatePermissions(rec, [commercialUse], undefined, {denyEditorialOnly:true, label}) equals evaluateUse(rec, commercial-product)', () => {
     const licenses: LicenseId[] = ['CC0-1.0', 'CC-BY', 'CC-BY-NC', 'CC-BY-ND', 'proprietary', 'unknown']
     for (const license of licenses) {
-      const viaPermissions = evaluatePermissions(rec(license), ['commercialUse'], undefined, { denyEditorialOnly: true })
+      const viaPermissions = evaluatePermissions(rec(license), ['commercialUse'], undefined, { denyEditorialOnly: true, label: 'commercial-product' })
       const viaUse = evaluateUse(rec(license), 'commercial-product')
       expect(viaPermissions.decision).toBe(viaUse.decision)
       expect(viaPermissions.reasons).toEqual(viaUse.reasons)
     }
   })
+
+  it('evaluateUse success reasons name the intent (historical wording)', () => {
+    expect(evaluateUse(rec('CC0-1.0'), 'commercial-product').reasons).toContain('permitted for commercial-product under CC0-1.0')
+    expect(evaluateUse(rec('CC0-1.0'), 'internal-moodboard').reasons).toContain('permitted for internal-moodboard under CC0-1.0')
+  })
+
+  it('standalone evaluatePermissions defaults the label to the permission set', () => {
+    expect(evaluatePermissions(rec('CC0-1.0'), ['commercialUse']).reasons).toContain('permitted for commercialUse under CC0-1.0')
+  })
 })
diff --git a/packages/core/src/evaluate-use.ts b/packages/core/src/evaluate-use.ts
index ad62c44..88dca7c 100644
--- a/packages/core/src/evaluate-use.ts
+++ b/packages/core/src/evaluate-use.ts
@@ -23,6 +23,10 @@ export interface EvaluateOptions {
   /** Enforce attributionRequired as allowed-with-attribution. Default true; presets
    *  disable it for internal-moodboard (note-only). */
   enforceAttribution?: boolean
+  /** Label used in the success-path reason ("permitted for <label> under <license>").
+   *  Defaults to the joined required-permission names (or 'use' if empty). Presets
+   *  pass the original intent name to preserve evaluateUse's historical wording. */
+  label?: string
 }
 
 /** Low-level, programmable strict-deny gate: unknown license → needs-review;
@@ -37,6 +41,7 @@ export function evaluatePermissions(
 ): Verdict {
   const denyEditorialOnly = opts?.denyEditorialOnly ?? false
   const enforceAttribution = opts?.enforceAttribution ?? true
+  const label = opts?.label ?? (required.join('+') || 'use')
 
   const facts = factsFor(r.license)
   const reasons: string[] = []
@@ -75,7 +80,7 @@ export function evaluatePermissions(
     }
   }
 
-  reasons.push(`permitted for ${required.join('+') || 'use'} under ${r.license}`)
+  reasons.push(`permitted for ${label} under ${r.license}`)
   // Lenient callers (e.g. internal-moodboard) surface a note instead of enforcing.
   if (facts.attributionRequired && !enforceAttribution) {
     reasons.push('attribution required by license but not enforced for internal-moodboard use')
@@ -92,14 +97,14 @@ export function evaluatePermissions(
 function presetFor(intent: Intent): { required: PermissionKey[]; opts: EvaluateOptions } {
   switch (intent) {
     case 'commercial-product':
-      return { required: ['commercialUse'], opts: { denyEditorialOnly: true, enforceAttribution: true } }
+      return { required: ['commercialUse'], opts: { denyEditorialOnly: true, enforceAttribution: true, label: intent } }
     case 'ai-generation-input':
-      return { required: ['commercialUse', 'derivatives'], opts: { denyEditorialOnly: true, enforceAttribution: true } }
+      return { required: ['commercialUse', 'derivatives'], opts: { denyEditorialOnly: true, enforceAttribution: true, label: intent } }
     case 'redistribution':
-      return { required: ['redistribution'], opts: { denyEditorialOnly: false, enforceAttribution: true } }
+      return { required: ['redistribution'], opts: { denyEditorialOnly: false, enforceAttribution: true, label: intent } }
     case 'internal-moodboard':
       // lenient; gated only by the unknown/jurisdiction checks in evaluatePermissions
-      return { required: [], opts: { denyEditorialOnly: false, enforceAttribution: false } }
+      return { required: [], opts: { denyEditorialOnly: false, enforceAttribution: false, label: intent } }
   }
 }
 

From 6a9b7e9c6d21dbc294eeb808391b0352ada2403b Mon Sep 17 00:00:00 2001
From: MyPrototypeWhat <daoquqiexing@gmail.com>
Date: Mon, 6 Jul 2026 17:02:54 +0800
Subject: [PATCH 3/6] feat(mcp): stateless evaluate_use + build_attribution
 tools; REFKIT_* env aliases

---
 .changeset/mcp-verdict-tools.md        | 14 ++++
 README.md                              |  2 +-
 packages/mcp/README.md                 | 21 +++++-
 packages/mcp/src/__tests__/mcp.test.ts | 95 ++++++++++++++++++++++++++
 packages/mcp/src/cli.ts                | 33 ++++++---
 packages/mcp/src/index.ts              | 86 ++++++++++++++++++++++-
 6 files changed, 237 insertions(+), 14 deletions(-)
 create mode 100644 .changeset/mcp-verdict-tools.md

diff --git a/.changeset/mcp-verdict-tools.md b/.changeset/mcp-verdict-tools.md
new file mode 100644
index 0000000..af75c5c
--- /dev/null
+++ b/.changeset/mcp-verdict-tools.md
@@ -0,0 +1,14 @@
+---
+"@refkit/mcp": minor
+---
+
+New stateless `evaluate_use` and `build_attribution` MCP tools — evaluate a
+license against an intended use, or build an attribution credit line, without a
+search round-trip. Zero-config `defaultProviders` now reads unified
+`REFKIT_<PROVIDER>_KEY` env names first (`REFKIT_UNSPLASH_KEY`,
+`REFKIT_PEXELS_KEY`, `REFKIT_PIXABAY_KEY`, `REFKIT_FLICKR_KEY`,
+`REFKIT_SMITHSONIAN_KEY`, `REFKIT_BRAVE_KEY`, `REFKIT_FREESOUND_KEY`,
+`REFKIT_JAMENDO_CLIENT_ID`, `REFKIT_EUROPEANA_KEY`), falling back to the legacy
+names (`UNSPLASH_KEY`, `PEXELS_KEY`, `PIXABAY_KEY`, `FLICKR_KEY`, `SI_KEY`,
+`BRAVE_TOKEN`, `FREESOUND_TOKEN`, `JAMENDO_CLIENT_ID`, `EUROPEANA_KEY`), which
+are still honored.
diff --git a/README.md b/README.md
index 0ed7443..0a817ed 100644
--- a/README.md
+++ b/README.md
@@ -229,7 +229,7 @@ Agents can use refkit in two ways:
 npx -y @refkit/mcp
 ```
 
-It boots with the keyless sources (Met, Art Institute, Wikimedia, Openverse, Project Gutenberg, PoetryDB, Rijksmuseum, Poly Haven, ambientCG, Internet Archive) and auto-adds any BYOK source whose key is in the environment (`UNSPLASH_KEY`, `PEXELS_KEY`, `BRAVE_TOKEN`, …). Pass `intent` to annotate each result with a use-verdict (may I use this, is attribution required); `gateFor` to return only allowed results. Or wire your own providers/keys via `serveStdio(createRefkit({ … }))` — see [`@refkit/mcp`](https://www.npmjs.com/package/@refkit/mcp).
+It boots with the keyless sources (Met, Art Institute, Wikimedia, Openverse, Project Gutenberg, PoetryDB, Rijksmuseum, Poly Haven, ambientCG, Internet Archive) and auto-adds any BYOK source whose key is in the environment (`REFKIT_UNSPLASH_KEY`, `REFKIT_PEXELS_KEY`, `REFKIT_BRAVE_KEY`, … — legacy names like `UNSPLASH_KEY`, `PEXELS_KEY`, `BRAVE_TOKEN` still work as fallbacks). Pass `intent` to annotate each result with a use-verdict (may I use this, is attribution required); `gateFor` to return only allowed results. Beyond search, `evaluate_use` and `build_attribution` expose the same license-verdict and attribution logic as standalone stateless tools, for when an agent already has a license id and just needs a verdict or a credit line. Or wire your own providers/keys via `serveStdio(createRefkit({ … }))` — see [`@refkit/mcp`](https://www.npmjs.com/package/@refkit/mcp).
 
 ## Not legal advice
 
diff --git a/packages/mcp/README.md b/packages/mcp/README.md
index 43aab0f..bd968e5 100644
--- a/packages/mcp/README.md
+++ b/packages/mcp/README.md
@@ -1,6 +1,6 @@
 # @refkit/mcp
 
-An MCP server that exposes refkit's **license-normalized reference search** as an agent tool (`search_references`).
+An MCP server that exposes refkit's **license-normalized reference search** (`search_references`) plus two stateless verdict tools (`evaluate_use`, `build_attribution`) as agent tools.
 
 ## Zero-config (`npx`)
 
@@ -10,9 +10,12 @@ Point any MCP client at:
 npx -y @refkit/mcp
 ```
 
-It boots with the keyless sources (Met, Art Institute of Chicago, Wikimedia Commons, Openverse + audio, Project Gutenberg, PoetryDB) and auto-adds any BYOK source whose key is in the environment:
+It boots with the keyless sources (Met, Art Institute of Chicago, Wikimedia Commons, Openverse + audio, Project Gutenberg, PoetryDB) and auto-adds any BYOK source whose key is in the environment. Each key is read as a unified `REFKIT_<PROVIDER>_KEY` name first, falling back to the provider's legacy name (both are honored indefinitely):
 
 ```bash
+REFKIT_UNSPLASH_KEY=… REFKIT_PEXELS_KEY=… REFKIT_PIXABAY_KEY=… REFKIT_FLICKR_KEY=… REFKIT_SMITHSONIAN_KEY=… REFKIT_BRAVE_KEY=… npx -y @refkit/mcp
+
+# legacy names still work:
 UNSPLASH_KEY=… PEXELS_KEY=… PIXABAY_KEY=… FLICKR_KEY=… SI_KEY=… BRAVE_TOKEN=… npx -y @refkit/mcp
 ```
 
@@ -66,6 +69,20 @@ Output: `{ references: [{ id, title?, modality, provider, canonicalUrl, license,
 
 > Results are references with a license id + source link — **not rights clearance, not legal advice**. `unknown` / `needs-review` results require the caller to verify the source's terms.
 
+## The `evaluate_use` tool
+
+Stateless: no search round-trip, no session cache — the caller supplies the rights fields directly.
+
+Input: `{ license, licenseVersion?, author?, title?, canonicalUrl, intent, editorialOnly?, jurisdiction?, userJurisdiction? }`.
+
+Output: `{ decision, reasons, confidence, disclaimer, attribution? }`. `attribution.text`/`.html` are included when `decision` is `allowed-with-attribution` (built from the same input fields via `buildAttribution`).
+
+> Same conservative heuristic as `search_references`' use-gate — **not legal advice**. Every verdict carries a `disclaimer` and a `confidence`.
+
+## The `build_attribution` tool
+
+Input: `{ license, licenseVersion?, author?, title?, canonicalUrl }` → output `{ required, text?, html? }`. `required` is `false` (and `text`/`html` omitted) for licenses that need no attribution (e.g. `CC0-1.0`, `PD`).
+
 ## Discovery (web) source
 
 refkit's clean providers give license-normalized results. For open-web **breadth** (e.g. "cyberpunk alley"), add the Brave discovery provider — its results carry `license: 'unknown'`, so refkit's use-gate returns `needs-review` for every one (never auto-allowed):
diff --git a/packages/mcp/src/__tests__/mcp.test.ts b/packages/mcp/src/__tests__/mcp.test.ts
index 3875c00..e57b10b 100644
--- a/packages/mcp/src/__tests__/mcp.test.ts
+++ b/packages/mcp/src/__tests__/mcp.test.ts
@@ -224,6 +224,88 @@ describe('@refkit/mcp', () => {
   })
 })
 
+describe('evaluate_use tool', () => {
+  it('lists the evaluate_use and build_attribution tools', async () => {
+    const client = await connectedClient()
+    const { tools } = await client.listTools()
+    expect(tools.map(t => t.name)).toContain('evaluate_use')
+    expect(tools.map(t => t.name)).toContain('build_attribution')
+    await client.close()
+  })
+
+  it('CC-BY under commercial-product → allowed-with-attribution, with attribution.text containing the author', async () => {
+    const client = await connectedClient()
+    const res = await client.callTool({
+      name: 'evaluate_use',
+      arguments: {
+        license: 'CC-BY',
+        author: 'Alice',
+        title: 'attribution pic',
+        canonicalUrl: 'https://ov/bbb',
+        intent: 'commercial-product',
+      },
+    })
+    const structured = res.structuredContent as {
+      decision: string
+      reasons: string[]
+      confidence: string
+      disclaimer: string
+      attribution?: { text?: string }
+    }
+    expect(structured.decision).toBe('allowed-with-attribution')
+    expect(structured.attribution?.text).toContain('Alice')
+    await client.close()
+  })
+
+  it('unknown license → needs-review', async () => {
+    const client = await connectedClient()
+    const res = await client.callTool({
+      name: 'evaluate_use',
+      arguments: {
+        license: 'unknown',
+        canonicalUrl: 'https://example.com/x',
+        intent: 'commercial-product',
+      },
+    })
+    const structured = res.structuredContent as { decision: string }
+    expect(structured.decision).toBe('needs-review')
+    await client.close()
+  })
+})
+
+describe('build_attribution tool', () => {
+  it('CC0 → required false', async () => {
+    const client = await connectedClient()
+    const res = await client.callTool({
+      name: 'build_attribution',
+      arguments: {
+        license: 'CC0-1.0',
+        canonicalUrl: 'https://example.com/cc0',
+      },
+    })
+    const structured = res.structuredContent as { required: boolean; text?: string }
+    expect(structured.required).toBe(false)
+    await client.close()
+  })
+
+  it('CC-BY-NC with version → text contains "CC-BY-NC 2.0"', async () => {
+    const client = await connectedClient()
+    const res = await client.callTool({
+      name: 'build_attribution',
+      arguments: {
+        license: 'CC-BY-NC',
+        licenseVersion: '2.0',
+        author: 'Carol',
+        canonicalUrl: 'https://example.com/nc',
+      },
+    })
+    const structured = res.structuredContent as { required: boolean; text?: string }
+    expect(structured.required).toBe(true)
+    expect(structured.text).toContain('CC-BY-NC 2.0')
+    await client.close()
+  })
+})
+
 describe('defaultProviders (zero-config CLI wiring)', () => {
   it('includes every keyless provider by default', () => {
     const ids = defaultProviders({}).map(p => p.id)
@@ -237,6 +319,10 @@ describe('defaultProviders (zero-config CLI wiring)', () => {
     expect(defaultProviders({ UNSPLASH_KEY: 'k' }).map(p => p.id)).toContain('unsplash')
   })
 
+  it('adds a BYOK provider when only the unified REFKIT_ env key is present', () => {
+    expect(defaultProviders({ REFKIT_UNSPLASH_KEY: 'k' }).map(p => p.id)).toContain('unsplash')
+  })
+
   it('adds freesound only when FREESOUND_TOKEN is present', () => {
     expect(defaultProviders({}).map(p => p.id)).not.toContain('freesound')
     expect(defaultProviders({ FREESOUND_TOKEN: 'k' }).map(p => p.id)).toContain('freesound')
@@ -251,4 +337,13 @@ describe('defaultProviders (zero-config CLI wiring)', () => {
     expect(defaultProviders({}).map(p => p.id)).not.toContain('europeana')
     expect(defaultProviders({ EUROPEANA_KEY: 'k' }).map(p => p.id)).toContain('europeana')
   })
+
+  it('adds europeana when only the unified REFKIT_EUROPEANA_KEY is present', () => {
+    expect(defaultProviders({ REFKIT_EUROPEANA_KEY: 'k' }).map(p => p.id)).toContain('europeana')
+  })
+
+  it('adds smithsonian via the legacy SI_KEY name (no unified alias renames the id)', () => {
+    expect(defaultProviders({}).map(p => p.id)).not.toContain('smithsonian')
+    expect(defaultProviders({ SI_KEY: 'k' }).map(p => p.id)).toContain('smithsonian')
+  })
 })
diff --git a/packages/mcp/src/cli.ts b/packages/mcp/src/cli.ts
index 8b1fb92..4fa5ba0 100644
--- a/packages/mcp/src/cli.ts
+++ b/packages/mcp/src/cli.ts
@@ -25,21 +25,34 @@ import { internetArchive } from '@refkit/provider-internet-archive'
 import { serveStdio } from './index'
 
 /** Providers a zero-config server boots with: all keyless sources, plus any BYOK
- *  source whose key is present in `env`. Exported so the wiring is unit-testable. */
+ *  source whose key is present in `env`. Exported so the wiring is unit-testable.
+ *
+ *  Env var convention: each BYOK key is read as `REFKIT_<PROVIDER>_KEY` first (the
+ *  unified name), falling back to the provider's legacy env var name — both are
+ *  honored indefinitely, the unified name is just preferred going forward. */
 export function defaultProviders(env: NodeJS.ProcessEnv = process.env): ReferenceProvider[] {
   const providers: ReferenceProvider[] = [
     openverse(), openverseAudio(), wikimediaCommons(), met(), artic(), gutendex(), poetrydb(),
     rijksmuseum(), polyhaven(), ambientcg(), internetArchive(),
   ]
-  if (env.UNSPLASH_KEY) providers.push(unsplash({ accessKey: env.UNSPLASH_KEY }))
-  if (env.PEXELS_KEY) providers.push(pexels({ apiKey: env.PEXELS_KEY }), pexelsVideo({ apiKey: env.PEXELS_KEY }))
-  if (env.PIXABAY_KEY) providers.push(pixabay({ key: env.PIXABAY_KEY }), pixabayVideo({ key: env.PIXABAY_KEY }))
-  if (env.FLICKR_KEY) providers.push(flickr({ apiKey: env.FLICKR_KEY }))
-  if (env.SI_KEY) providers.push(smithsonian({ apiKey: env.SI_KEY }))
-  if (env.BRAVE_TOKEN) providers.push(brave({ token: env.BRAVE_TOKEN }))
-  if (env.FREESOUND_TOKEN) providers.push(freesound({ apiKey: env.FREESOUND_TOKEN }))
-  if (env.JAMENDO_CLIENT_ID) providers.push(jamendo({ clientId: env.JAMENDO_CLIENT_ID }))
-  if (env.EUROPEANA_KEY) providers.push(europeana({ apiKey: env.EUROPEANA_KEY }))
+  const unsplashKey = env.REFKIT_UNSPLASH_KEY ?? env.UNSPLASH_KEY
+  const pexelsKey = env.REFKIT_PEXELS_KEY ?? env.PEXELS_KEY
+  const pixabayKey = env.REFKIT_PIXABAY_KEY ?? env.PIXABAY_KEY
+  const flickrKey = env.REFKIT_FLICKR_KEY ?? env.FLICKR_KEY
+  const smithsonianKey = env.REFKIT_SMITHSONIAN_KEY ?? env.SI_KEY
+  const braveKey = env.REFKIT_BRAVE_KEY ?? env.BRAVE_TOKEN
+  const freesoundKey = env.REFKIT_FREESOUND_KEY ?? env.FREESOUND_TOKEN
+  const jamendoClientId = env.REFKIT_JAMENDO_CLIENT_ID ?? env.JAMENDO_CLIENT_ID
+  const europeanaKey = env.REFKIT_EUROPEANA_KEY ?? env.EUROPEANA_KEY
+  if (unsplashKey) providers.push(unsplash({ accessKey: unsplashKey }))
+  if (pexelsKey) providers.push(pexels({ apiKey: pexelsKey }), pexelsVideo({ apiKey: pexelsKey }))
+  if (pixabayKey) providers.push(pixabay({ key: pixabayKey }), pixabayVideo({ key: pixabayKey }))
+  if (flickrKey) providers.push(flickr({ apiKey: flickrKey }))
+  if (smithsonianKey) providers.push(smithsonian({ apiKey: smithsonianKey }))
+  if (braveKey) providers.push(brave({ token: braveKey }))
+  if (freesoundKey) providers.push(freesound({ apiKey: freesoundKey }))
+  if (jamendoClientId) providers.push(jamendo({ clientId: jamendoClientId }))
+  if (europeanaKey) providers.push(europeana({ apiKey: europeanaKey }))
   return providers
 }
 
diff --git a/packages/mcp/src/index.ts b/packages/mcp/src/index.ts
index 170b322..053e6ea 100644
--- a/packages/mcp/src/index.ts
+++ b/packages/mcp/src/index.ts
@@ -2,7 +2,8 @@ import { readFileSync } from 'node:fs'
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod'
-import type { RefkitClient, Reference, Verdict, Attribution, SearchFilters, SearchControls, SearchControlKey, ProviderOptionsById, SearchMeta } from '@refkit/core'
+import { LICENSE_IDS, evaluateUse, buildAttribution } from '@refkit/core'
+import type { RefkitClient, Reference, Verdict, Attribution, SearchFilters, SearchControls, SearchControlKey, ProviderOptionsById, SearchMeta, RightsRecord } from '@refkit/core'
 
 const MODALITIES = ['image', 'video', 'audio', 'text'] as const
 const INTENTS = ['internal-moodboard', 'commercial-product', 'ai-generation-input', 'redistribution'] as const
@@ -202,6 +203,89 @@ export function createRefkitMcpServer(refkit: RefkitClient): McpServer {
     },
   )
 
+  const attributionOutputSchema = { required: z.boolean(), text: z.string().optional(), html: z.string().optional() }
+
+  server.registerTool(
+    'evaluate_use',
+    {
+      title: 'Evaluate a license for an intended use',
+      description:
+        'Stateless license/use-gate check: given a license id + intended use, returns a conservative-heuristic verdict ' +
+        '(allowed / allowed-with-attribution / denied / needs-review) with reasons and confidence. ' +
+        'Not legal advice — a strict-deny heuristic over source-declared license facts.',
+      inputSchema: {
+        license: z.enum(LICENSE_IDS).describe('the reference\'s license id'),
+        licenseVersion: z.string().optional().describe('precise CC version, e.g. "4.0" — attribution only'),
+        author: z.string().optional(),
+        title: z.string().optional(),
+        canonicalUrl: z.string().describe('canonical source link, for attribution and audit'),
+        intent: z.enum(INTENTS).describe('the intended use to evaluate this license against'),
+        editorialOnly: z.boolean().optional().describe('source marked editorial-only'),
+        jurisdiction: z.string().optional().describe('source-declared jurisdiction of the PD/copyright status'),
+        userJurisdiction: z.string().optional().describe('caller\'s jurisdiction; mismatched jurisdictions default to needs-review'),
+      },
+      outputSchema: {
+        decision: z.enum(['allowed', 'allowed-with-attribution', 'denied', 'needs-review']),
+        reasons: z.array(z.string()),
+        confidence: z.enum(['high', 'low']),
+        disclaimer: z.string(),
+        attribution: z.object(attributionOutputSchema).optional(),
+      },
+    },
+    async ({ license, licenseVersion, author, title, canonicalUrl, intent, editorialOnly, jurisdiction, userJurisdiction }) => {
+      const rights: RightsRecord = {
+        license,
+        licenseVersion,
+        author,
+        rehostPolicy: 'cache-allowed',
+        jurisdiction,
+        editorialOnly,
+        raw: { sourceTerms: '', sourceUrl: canonicalUrl },
+      }
+      const verdict: Verdict = evaluateUse(rights, intent, { userJurisdiction })
+      const attribution =
+        verdict.decision === 'allowed-with-attribution'
+          ? buildAttribution({ license, licenseVersion, author, title, canonicalUrl })
+          : undefined
+      const summary = `${verdict.decision}: ${verdict.reasons.join('; ') || 'license facts allow this use'}`
+      return {
+        content: [{ type: 'text', text: summary }],
+        structuredContent: {
+          decision: verdict.decision,
+          reasons: verdict.reasons,
+          confidence: verdict.confidence,
+          disclaimer: verdict.disclaimer,
+          ...(attribution ? { attribution } : {}),
+        },
+      }
+    },
+  )
+
+  server.registerTool(
+    'build_attribution',
+    {
+      title: 'Build an attribution credit line',
+      description:
+        'Mechanically derive an attribution credit line (plain text + HTML) from a license id + author + title + ' +
+        'canonicalUrl. `required` is false when the license needs no attribution (e.g. CC0, PD).',
+      inputSchema: {
+        license: z.enum(LICENSE_IDS),
+        licenseVersion: z.string().optional().describe('precise CC version, e.g. "4.0" — appended to the license name'),
+        author: z.string().optional(),
+        title: z.string().optional(),
+        canonicalUrl: z.string(),
+      },
+      outputSchema: attributionOutputSchema,
+    },
+    async ({ license, licenseVersion, author, title, canonicalUrl }) => {
+      const attribution: Attribution = buildAttribution({ license, licenseVersion, author, title, canonicalUrl })
+      return {
+        content: [{ type: 'text', text: attribution.required ? (attribution.text ?? '') : 'No attribution required for this license.' }],
+        structuredContent: { required: attribution.required, text: attribution.text, html: attribution.html },
+      }
+    },
+  )
+
   return server
 }
 

From 4ee262bad80a7d8df410bc0c205aeb683ec95e1d Mon Sep 17 00:00:00 2001
From: MyPrototypeWhat <daoquqiexing@gmail.com>
Date: Mon, 6 Jul 2026 17:06:20 +0800
Subject: [PATCH 4/6] docs: pagination semantics + semantic-rerank cookbook

No changeset: documentation only.
---
 README.md                        |  8 +++
 docs/examples/semantic-rerank.md | 96 ++++++++++++++++++++++++++++++++
 packages/core/src/provider.ts    |  3 +
 3 files changed, 107 insertions(+)
 create mode 100644 docs/examples/semantic-rerank.md

diff --git a/README.md b/README.md
index 0a817ed..2cc8932 100644
--- a/README.md
+++ b/README.md
@@ -108,6 +108,14 @@ console.log(meta.providers)
 console.log(meta.warnings)
 ```
 
+`controls.page` is a **provider-local** cursor: each provider paginates its own result stream independently, and refkit does not track a unified offset across sources. Because pages are fused with Reciprocal Rank Fusion per request, page N+1 is not guaranteed to be disjoint from page N — results can overlap or shift relative to the previous page. For a "load more" UI, dedupe across pages by `canonicalUrl` rather than assuming stable, non-overlapping windows:
+
+```ts
+const seen = new Set(prev.map((r) => r.canonicalUrl))
+const nextPage = await refkit.search({ query, modalities: ['image'], controls: { page: 2 } })
+const newOnly = nextPage.filter((r) => !seen.has(r.canonicalUrl))
+```
+
 ## Ranking & rerank
 
 By default, results are fused across sources with **Reciprocal Rank Fusion** — cross-source-orderable, but not query-aware. For sharper relevance, pass a **reranker**:
diff --git a/docs/examples/semantic-rerank.md b/docs/examples/semantic-rerank.md
new file mode 100644
index 0000000..40855cd
--- /dev/null
+++ b/docs/examples/semantic-rerank.md
@@ -0,0 +1,96 @@
+# Cookbook: BYO-embedding semantic reranker
+
+refkit ships no embedding model — [`lexicalReranker`](../../README.md#ranking--rerank) (term-coverage +
+resolution + license weighting) remains the zero-dep default. This recipe wires a
+`Reranker` to a host-provided embeddings endpoint for query-aware semantic ranking.
+
+Imports come only from `@refkit/core`; the embeddings call is the one intentional
+seam to your own backend.
+
+```ts
+import type { Reranker, RerankInput, Reference } from '@refkit/core'
+
+/** Host-provided endpoint: POST { input: string[] } -> { embeddings: number[][] },
+ *  one embedding per input string, same order. Swap in your own provider. */
+async function fetchEmbeddings(
+  texts: string[],
+  signal?: AbortSignal,
+): Promise<number[][]> {
+  const res = await fetch('https://your-embeddings-host.example/v1/embed', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ input: texts }),
+    signal,
+  })
+  if (!res.ok) throw new Error(`embeddings request failed: ${res.status}`)
+  const { embeddings } = (await res.json()) as { embeddings: number[][] }
+  return embeddings
+}
+
+function dot(a: number[], b: number[]): number {
+  let sum = 0
+  for (let i = 0; i < a.length; i++) sum += a[i] * b[i]
+  return sum
+}
+
+function norm(a: number[]): number {
+  return Math.sqrt(dot(a, a))
+}
+
+/** Cosine similarity in [-1, 1]; 0 when either vector is zero-length. */
+function cosineSimilarity(a: number[], b: number[]): number {
+  const denom = norm(a) * norm(b)
+  return denom === 0 ? 0 : dot(a, b) / denom
+}
+
+function refText(ref: Reference): string {
+  return `${ref.title ?? ''} ${ref.text?.excerpt ?? ''}`.trim()
+}
+
+/** Semantic reranker: embeds the query and each ref's title+excerpt, scores by
+ *  cosine similarity, sorts descending, and rewrites `relevance` to a normalized
+ *  0..1 score. Preserves every `referenceSchema` invariant — refs are copied,
+ *  never mutated, and none are dropped or fabricated. */
+export function semanticReranker(): Reranker {
+  return async ({ query, refs, signal }: RerankInput): Promise<Reference[]> => {
+    if (refs.length === 0) return []
+
+    const [queryVec, ...refVecs] = await fetchEmbeddings(
+      [query, ...refs.map(refText)],
+      signal,
+    )
+
+    const scored = refs.map((ref, i) => ({
+      ref,
+      score: cosineSimilarity(queryVec, refVecs[i]),
+    }))
+    scored.sort((a, b) => b.score - a.score)
+
+    // Cosine similarity is [-1, 1]; normalize to referenceSchema's required 0..1.
+    return scored.map(({ ref, score }) => ({
+      ...ref, // copy — never mutate the input ref in place
+      relevance: (score + 1) / 2,
+    }))
+  }
+}
+```
+
+Usage:
+
+```ts
+import { createRefkit } from '@refkit/core'
+import { semanticReranker } from './semantic-reranker'
+
+const refkit = createRefkit({ providers: [/* ... */] })
+
+const refs = await refkit.search({
+  query: 'cyberpunk alley at night',
+  modalities: ['image'],
+  rerank: semanticReranker(),
+})
+```
+
+**Invariants a custom `Reranker` must preserve** (see `Reranker` in `packages/core/src/rerank.ts`):
+copy each `Reference` rather than mutating it in place, keep `relevance` within `0..1`,
+and return a reorder/subset of the input — no dropped required fields, no duplicated or
+fabricated refs.
diff --git a/packages/core/src/provider.ts b/packages/core/src/provider.ts
index 123e05d..2be5721 100644
--- a/packages/core/src/provider.ts
+++ b/packages/core/src/provider.ts
@@ -45,6 +45,9 @@ export interface SearchControls {
   media?: SearchMediaControls
   creator?: SearchCreatorControls
   text?: SearchTextControls
+  /** Provider-local page cursor: each provider paginates its own result stream;
+   *  after RRF merging, page N+1 may overlap or shift relative to page N. For
+   *  UI "load more", dedupe across pages by canonicalUrl (see README). */
   page?: number
 }
 

From cd20997c01b4f30f69c0c5c1f38bd2c84e1218b2 Mon Sep 17 00:00:00 2001
From: MyPrototypeWhat <daoquqiexing@gmail.com>
Date: Mon, 6 Jul 2026 17:11:19 +0800
Subject: [PATCH 5/6] docs: Wave 4 capability-extensions plan

---
 .../plans/2026-07-03-capability-extensions.md | 68 +++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-07-03-capability-extensions.md

diff --git a/docs/superpowers/plans/2026-07-03-capability-extensions.md b/docs/superpowers/plans/2026-07-03-capability-extensions.md
new file mode 100644
index 0000000..85f982c
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-03-capability-extensions.md
@@ -0,0 +1,68 @@
+# Wave 4 — Capability Extensions Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: superpowers:subagent-driven-development or executing-plans, task-by-task.
+
+**Goal:** (4a) export a programmable low-level `evaluatePermissions` with `evaluateUse` refactored into behavior-identical presets; (4b) document pagination semantics; (4c) stateless `evaluate_use` + `build_attribution` MCP tools and unified `REFKIT_<PROVIDER>_KEY` env names with legacy fallbacks; (4d) a runnable semantic-rerank cookbook. Branch: `m13t/wave4-capability-extensions` (off main).
+
+**Hard constraint for 4a:** ALL existing evaluate-use tests pass UNCHANGED — the refactor is proven behavior-identical by the existing suite (reason strings included).
+
+---
+
+### Task W4.1: core — `evaluatePermissions` (4a)
+
+**Files:** modify `packages/core/src/evaluate-use.ts`, `packages/core/src/index.ts`; test `packages/core/src/__tests__/evaluate-use.test.ts` (ADD only).
+
+Design (implementer adapts internals so existing tests stay green verbatim):
+
+```ts
+/** The tri-state permission axes of LicenseFacts. */
+export type PermissionKey = 'commercialUse' | 'derivatives' | 'redistribution'
+
+export interface EvaluateOptions {
+  /** Treat editorial-only sources as denied (commercial-flavored uses). Default false. */
+  denyEditorialOnly?: boolean
+  /** Enforce attributionRequired as allowed-with-attribution. Default true; presets
+   *  disable it for internal-moodboard (note-only). */
+  enforceAttribution?: boolean
+}
+
+/** Low-level, programmable strict-deny gate: unknown license → needs-review;
+ *  jurisdiction mismatch → needs-review; each required permission false → denied,
+ *  'unknown' → needs-review; else allowed(-with-attribution). evaluateUse's four
+ *  intents are presets over this. */
+export function evaluatePermissions(
+  r: RightsRecord,
+  required: readonly PermissionKey[],
+  ctx?: { userJurisdiction?: string },
+  opts?: EvaluateOptions,
+): Verdict
+```
+
+`evaluateUse` becomes: map intent → (required, opts) preset and delegate; keep the moodboard "attribution required by license but not enforced" reason note and every existing reason string byte-identical (existing tests are the oracle). Export `evaluatePermissions`, `PermissionKey`, `EvaluateOptions` from core index. New tests (ADD): custom permission set `['derivatives']` on CC-BY-ND → denied naming CC-BY-ND; empty required on CC-BY with enforceAttribution true → allowed-with-attribution; unknown license → needs-review regardless of required; parity spot-check `evaluatePermissions(rec, ['commercialUse'], undefined, {denyEditorialOnly:true})` equals `evaluateUse(rec,'commercial-product')` for a few licenses. Changeset: `.changeset/evaluate-permissions.md` — `"@refkit/core": minor` — "Export evaluatePermissions/PermissionKey/EvaluateOptions — programmable strict-deny gate; evaluateUse intents are now presets over it (behavior unchanged)." Verify: full repo green (304/22). Commit `feat(core): programmable evaluatePermissions; evaluateUse intents become presets`.
+
+### Task W4.2: MCP — stateless verdict tools + env unification (4c)
+
+**Files:** modify `packages/mcp/src/index.ts`, `packages/mcp/src/cli.ts`, `packages/mcp/src/__tests__/mcp.test.ts`, `packages/mcp/README.md` (if it documents env vars — check), changeset.
+
+1. Register two tools in `createRefkitMcpServer` (stateless — inputs carry the rights fields; no session cache):
+   - `evaluate_use`: input { license: z.enum(LICENSE_IDS from core), licenseVersion?, author?, title?, canonicalUrl: string, intent: z.enum(INTENTS), editorialOnly?: boolean, jurisdiction?: string, userJurisdiction?: string }. Build a RightsRecord (rehostPolicy 'cache-allowed', raw { sourceTerms: '', sourceUrl: canonicalUrl } — verdict doesn't read them), call core `evaluateUse(rights, intent, { userJurisdiction })`; output { decision, reasons, confidence, disclaimer, attribution? (text when verdict allows-with-attribution — via buildAttribution) }. Description: mirrors search_references' "not legal advice" framing.
+   - `build_attribution`: input { license, licenseVersion?, author?, title?, canonicalUrl } → core buildAttribution output { required, text?, html? }.
+2. cli.ts `defaultProviders`: unified names first with legacy fallback — `REFKIT_UNSPLASH_KEY ?? UNSPLASH_KEY`, `REFKIT_PEXELS_KEY ?? PEXELS_KEY`, `REFKIT_PIXABAY_KEY ?? PIXABAY_KEY`, `REFKIT_FLICKR_KEY ?? FLICKR_KEY`, `REFKIT_SMITHSONIAN_KEY ?? SI_KEY`, `REFKIT_BRAVE_KEY ?? BRAVE_TOKEN`, `REFKIT_FREESOUND_KEY ?? FREESOUND_TOKEN`, `REFKIT_JAMENDO_CLIENT_ID ?? JAMENDO_CLIENT_ID`, `REFKIT_EUROPEANA_KEY ?? EUROPEANA_KEY`. Comment documents the convention; `defaultProviders` is already unit-tested — extend its tests to cover a REFKIT_-name and a legacy-name both working.
+3. Tests: tool-level tests for both new tools (CC-BY → allowed-with-attribution + credit line; unknown → needs-review; CC0 → attribution not required). Follow mcp.test.ts's existing server-invocation pattern.
+4. Changeset `"@refkit/mcp": minor`: new tools + env aliases (legacy names still honored).
+5. Root README MCP section: mention the two new tools in one sentence; keep the env example working.
+
+Verify: full repo green. Commit `feat(mcp): stateless evaluate_use + build_attribution tools; REFKIT_* env aliases`.
+
+### Task W4.3: docs — pagination semantics + rerank cookbook (4b, 4d)
+
+**Files:** modify `packages/core/src/provider.ts` (SearchControls.page JSDoc), root `README.md` (Search controls section), create `docs/examples/semantic-rerank.md`.
+
+1. `SearchControls.page` JSDoc: `/** Provider-local page cursor: each provider paginates its own result stream; after RRF merging, page N+1 may overlap or shift relative to page N. For UI "load more", dedupe across pages by canonicalUrl (see README). */` README Search controls section: 3-sentence paragraph stating the same + a dedupe recipe snippet (`const seen = new Set(prev.map(r => r.canonicalUrl))` filter).
+2. `docs/examples/semantic-rerank.md`: runnable BYO-embedding `Reranker` — fetch embeddings from a host-provided endpoint for `[query, ...refs.map(title+excerpt)]`, cosine similarity, sort desc, rewrite relevance to normalized score, note on preserving referenceSchema invariants (0..1, no mutation — copy refs), and a one-line pointer that lexicalReranker remains the zero-dep default. TypeScript, imports from '@refkit/core' only, ~60 lines, self-contained.
+
+No changeset (docs only). Verify repo green. Commit `docs: pagination semantics + semantic-rerank cookbook`.
+
+---
+
+**Wave finish (coordinator):** final whole-wave review → push → PR to main. Changesets: core minor + mcp minor land in Tasks 1–2.

From 6318c6f2196fd73c2103d96c35b1724f7091c042 Mon Sep 17 00:00:00 2001
From: MyPrototypeWhat <daoquqiexing@gmail.com>
Date: Mon, 6 Jul 2026 18:38:05 +0800
Subject: [PATCH 6/6] =?UTF-8?q?fix:=20review=20findings=20=E2=80=94=20norm?=
 =?UTF-8?q?alized=20dedup=20recipe,=20cookbook=20guards,=20CC-only=20licen?=
 =?UTF-8?q?seVersion,=20shared=20INTENTS,=20label-aware=20note,=20MCP=20pa?=
 =?UTF-8?q?th=20tests?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                                     |  8 ++-
 docs/examples/semantic-rerank.md              | 10 ++--
 .../core/src/__tests__/evaluate-use.test.ts   |  5 ++
 packages/core/src/evaluate-use.ts             |  5 +-
 packages/core/src/index.ts                    |  2 +-
 packages/mcp/src/__tests__/mcp.test.ts        | 50 +++++++++++++++++++
 packages/mcp/src/index.ts                     | 11 ++--
 7 files changed, 77 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 2cc8932..66af5a8 100644
--- a/README.md
+++ b/README.md
@@ -111,11 +111,15 @@ console.log(meta.warnings)
 `controls.page` is a **provider-local** cursor: each provider paginates its own result stream independently, and refkit does not track a unified offset across sources. Because pages are fused with Reciprocal Rank Fusion per request, page N+1 is not guaranteed to be disjoint from page N — results can overlap or shift relative to the previous page. For a "load more" UI, dedupe across pages by `canonicalUrl` rather than assuming stable, non-overlapping windows:
 
 ```ts
-const seen = new Set(prev.map((r) => r.canonicalUrl))
+import { canonicalizeUrl } from '@refkit/core'
+
+const seen = new Set(prev.map((r) => canonicalizeUrl(r.canonicalUrl)))
 const nextPage = await refkit.search({ query, modalities: ['image'], controls: { page: 2 } })
-const newOnly = nextPage.filter((r) => !seen.has(r.canonicalUrl))
+const newOnly = nextPage.filter((r) => !seen.has(canonicalizeUrl(r.canonicalUrl)))
 ```
 
+(core's own merge/dedup normalizes URLs the same way, so this recipe stays consistent with what refkit dedupes internally.)
+
 ## Ranking & rerank
 
 By default, results are fused across sources with **Reciprocal Rank Fusion** — cross-source-orderable, but not query-aware. For sharper relevance, pass a **reranker**:
diff --git a/docs/examples/semantic-rerank.md b/docs/examples/semantic-rerank.md
index 40855cd..503f0a3 100644
--- a/docs/examples/semantic-rerank.md
+++ b/docs/examples/semantic-rerank.md
@@ -55,10 +55,12 @@ export function semanticReranker(): Reranker {
   return async ({ query, refs, signal }: RerankInput): Promise<Reference[]> => {
     if (refs.length === 0) return []
 
-    const [queryVec, ...refVecs] = await fetchEmbeddings(
-      [query, ...refs.map(refText)],
-      signal,
-    )
+    const vectors = await fetchEmbeddings([query, ...refs.map(refText)], signal)
+    const expected = 1 + refs.length
+    if (vectors.length !== expected) {
+      throw new Error(`embeddings count mismatch: got ${vectors.length}, expected ${expected}`)
+    }
+    const [queryVec, ...refVecs] = vectors
 
     const scored = refs.map((ref, i) => ({
       ref,
diff --git a/packages/core/src/__tests__/evaluate-use.test.ts b/packages/core/src/__tests__/evaluate-use.test.ts
index d85291a..4cd855c 100644
--- a/packages/core/src/__tests__/evaluate-use.test.ts
+++ b/packages/core/src/__tests__/evaluate-use.test.ts
@@ -139,4 +139,9 @@ describe('evaluatePermissions — programmable strict-deny gate', () => {
   it('standalone evaluatePermissions defaults the label to the permission set', () => {
     expect(evaluatePermissions(rec('CC0-1.0'), ['commercialUse']).reasons).toContain('permitted for commercialUse under CC0-1.0')
   })
+
+  it('lenient-attribution note interpolates the custom label', () => {
+    const v = evaluatePermissions(rec('CC-BY'), [], undefined, { enforceAttribution: false, label: 'archival-review' })
+    expect(v.reasons.some(r => r.includes('not enforced for archival-review use'))).toBe(true)
+  })
 })
diff --git a/packages/core/src/evaluate-use.ts b/packages/core/src/evaluate-use.ts
index 88dca7c..c9e7b99 100644
--- a/packages/core/src/evaluate-use.ts
+++ b/packages/core/src/evaluate-use.ts
@@ -1,7 +1,8 @@
 import { factsFor, type Tri } from './license'
 import type { RightsRecord } from './rights'
 
-export type Intent = 'internal-moodboard' | 'commercial-product' | 'ai-generation-input' | 'redistribution'
+export const INTENTS = ['internal-moodboard', 'commercial-product', 'ai-generation-input', 'redistribution'] as const
+export type Intent = (typeof INTENTS)[number]
 export type Decision = 'allowed' | 'allowed-with-attribution' | 'denied' | 'needs-review'
 
 export interface Verdict {
@@ -83,7 +84,7 @@ export function evaluatePermissions(
   reasons.push(`permitted for ${label} under ${r.license}`)
   // Lenient callers (e.g. internal-moodboard) surface a note instead of enforcing.
   if (facts.attributionRequired && !enforceAttribution) {
-    reasons.push('attribution required by license but not enforced for internal-moodboard use')
+    reasons.push(`attribution required by license but not enforced for ${label} use`)
   }
   const decision: Decision =
     facts.attributionRequired && enforceAttribution
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index c4e9de3..7600c0c 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -20,7 +20,7 @@ export { hammingDistance, dedupeReferences } from './dedup'
 export type { DedupeOptions } from './dedup'
 export { mergeReferences } from './merge'
 export type { MergeOptions } from './merge'
-export { evaluateUse, evaluatePermissions, NOT_LEGAL_ADVICE } from './evaluate-use'
+export { evaluateUse, evaluatePermissions, NOT_LEGAL_ADVICE, INTENTS } from './evaluate-use'
 export type { Intent, Decision, Verdict, PermissionKey, EvaluateOptions } from './evaluate-use'
 export { defineProvider } from './provider'
 export type {
diff --git a/packages/mcp/src/__tests__/mcp.test.ts b/packages/mcp/src/__tests__/mcp.test.ts
index e57b10b..99f6f9f 100644
--- a/packages/mcp/src/__tests__/mcp.test.ts
+++ b/packages/mcp/src/__tests__/mcp.test.ts
@@ -271,6 +271,39 @@ describe('evaluate_use tool', () => {
     expect(structured.decision).toBe('needs-review')
     await client.close()
   })
+
+  it('CC0 editorialOnly + commercial-product intent → denied', async () => {
+    const client = await connectedClient()
+    const res = await client.callTool({
+      name: 'evaluate_use',
+      arguments: {
+        license: 'CC0-1.0',
+        editorialOnly: true,
+        canonicalUrl: 'https://example.com/editorial',
+        intent: 'commercial-product',
+      },
+    })
+    const structured = res.structuredContent as { decision: string }
+    expect(structured.decision).toBe('denied')
+    await client.close()
+  })
+
+  it('PD with mismatched jurisdiction + commercial-product intent → needs-review', async () => {
+    const client = await connectedClient()
+    const res = await client.callTool({
+      name: 'evaluate_use',
+      arguments: {
+        license: 'PD',
+        jurisdiction: 'US',
+        userJurisdiction: 'DE',
+        canonicalUrl: 'https://example.com/pd',
+        intent: 'commercial-product',
+      },
+    })
+    const structured = res.structuredContent as { decision: string }
+    expect(structured.decision).toBe('needs-review')
+    await client.close()
+  })
 })
 
 describe('build_attribution tool', () => {
@@ -304,6 +337,23 @@ describe('build_attribution tool', () => {
     expect(structured.text).toContain('CC-BY-NC 2.0')
     await client.close()
   })
+
+  it('non-CC license id: licenseVersion is dropped silently (bare license label, no text emitted)', async () => {
+    const client = await connectedClient()
+    const res = await client.callTool({
+      name: 'build_attribution',
+      arguments: {
+        license: 'unsplash',
+        licenseVersion: '4.0',
+        canonicalUrl: 'https://example.com/unsplash',
+      },
+    })
+    const structured = res.structuredContent as { required: boolean; text?: string }
+    // unsplash requires no attribution at all, so text is absent — but critically,
+    // the version must never have been threaded through un-gated (it isn't a CC family).
+    expect(structured.text ?? '').not.toContain('4.0')
+    await client.close()
+  })
 })
 
 describe('defaultProviders (zero-config CLI wiring)', () => {
diff --git a/packages/mcp/src/index.ts b/packages/mcp/src/index.ts
index 053e6ea..9115052 100644
--- a/packages/mcp/src/index.ts
+++ b/packages/mcp/src/index.ts
@@ -2,11 +2,10 @@ import { readFileSync } from 'node:fs'
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod'
-import { LICENSE_IDS, evaluateUse, buildAttribution } from '@refkit/core'
+import { LICENSE_IDS, INTENTS, evaluateUse, buildAttribution, ccVersionFor } from '@refkit/core'
 import type { RefkitClient, Reference, Verdict, Attribution, SearchFilters, SearchControls, SearchControlKey, ProviderOptionsById, SearchMeta, RightsRecord } from '@refkit/core'
 
 const MODALITIES = ['image', 'video', 'audio', 'text'] as const
-const INTENTS = ['internal-moodboard', 'commercial-product', 'ai-generation-input', 'redistribution'] as const
 const ORIENTATIONS = ['landscape', 'portrait', 'square'] as const
 const SEARCH_CONTROL_KEYS = [
   'orientation',
@@ -233,9 +232,10 @@ export function createRefkitMcpServer(refkit: RefkitClient): McpServer {
       },
     },
     async ({ license, licenseVersion, author, title, canonicalUrl, intent, editorialOnly, jurisdiction, userJurisdiction }) => {
+      const version = ccVersionFor(license, licenseVersion)
       const rights: RightsRecord = {
         license,
-        licenseVersion,
+        licenseVersion: version,
         author,
         rehostPolicy: 'cache-allowed',
         jurisdiction,
@@ -245,7 +245,7 @@ export function createRefkitMcpServer(refkit: RefkitClient): McpServer {
       const verdict: Verdict = evaluateUse(rights, intent, { userJurisdiction })
       const attribution =
         verdict.decision === 'allowed-with-attribution'
-          ? buildAttribution({ license, licenseVersion, author, title, canonicalUrl })
+          ? buildAttribution({ license, licenseVersion: version, author, title, canonicalUrl })
           : undefined
       const summary = `${verdict.decision}: ${verdict.reasons.join('; ') || 'license facts allow this use'}`
       return {
@@ -278,7 +278,8 @@ export function createRefkitMcpServer(refkit: RefkitClient): McpServer {
       outputSchema: attributionOutputSchema,
     },
     async ({ license, licenseVersion, author, title, canonicalUrl }) => {
-      const attribution: Attribution = buildAttribution({ license, licenseVersion, author, title, canonicalUrl })
+      const version = ccVersionFor(license, licenseVersion)
+      const attribution: Attribution = buildAttribution({ license, licenseVersion: version, author, title, canonicalUrl })
       return {
         content: [{ type: 'text', text: attribution.required ? (attribution.text ?? '') : 'No attribution required for this license.' }],
         structuredContent: { required: attribution.required, text: attribution.text, html: attribution.html },