# CueFinder — agent + machine discovery note

CueFinder is Cumulative Web Inc's AI sync-discovery engine: natural-language
search over the That Boy Hi Hat catalog (24 tracks, alternative rap /
Post-Trap Futurism). Tagline: "Search like a supervisor thinks."
Positioning: the AI sync-discovery engine for the CWI catalog — and the
machine-readable front door that supervisor tools and agent builders can ingest.

## Machine-readable catalog
- Full descriptor set: https://cumulativewebinc.github.io/cwi-cuefinder/sync-catalog.json
- Versioned, pinned: https://cumulativewebinc.github.io/cwi-cuefinder/v1/sync-catalog.json
  (changelog at .../v1/CHANGELOG.md — v2 will never silently break v1 consumers)
- Agent card: https://cumulativewebinc.github.io/cwi-cuefinder/.well-known/agent-card.json
- Schema: cwi.sync-catalog/1.0, namespaced by catalog_id "cwi.tbhh.sync-catalog"
  (multi-artist future without a rewrite). Vocabularies are controlled and shared
  by the search engine and the catalog (moods, energy words, scenes, use cases,
  instrumentation).

## Embed
Blogs, supervisor sites, and agent pages can host CueFinder search:
<iframe src="https://cumulativewebinc.github.io/cwi-cuefinder/embed.html"
  width="100%" height="520" style="border:0" title="CueFinder search"></iframe>
Optional preset: embed.html?q=dark+futuristic

## Sync brief packs (v1.1.0)
Five machine-readable brief packs, one per brief type, for supervisors and agents:
sports hype, trailer tension, fashion film, horror/thriller, sneaker commercial.
- Bundle: https://cumulativewebinc.github.io/cwi-cuefinder/v1/brief-packs
  (also .../v1/brief-packs.json)
- Single packs: .../v1/brief-packs-sports-hype.json, .../v1/brief-packs-trailer-tension.json,
  .../v1/brief-packs-fashion-film.json, .../v1/brief-packs-horror-thriller.json,
  .../v1/brief-packs-sneaker-commercial.json
- Agent index: https://cumulativewebinc.github.io/cwi-cuefinder/v1/index.json
Each pack carries >=2 best-fit tracks with full sonic descriptors (BPM est., moods,
energy, scenes, use cases, lyrical themes, sounds-like reference, credits, rights),
carried through verbatim from v1/sync-catalog.json. Rights: no one-stop or pre-cleared
claims; clearance direct via hp@cumulativeweb.com.

## Provenance labels (binding)
- verified: titles, artist, Spotify track URLs (all 24), explicit flags from
  Spotify metadata ("unknown" where absent — never defaulted), producer/studio
  credits, rights positioning, Frederick MD origin.
- editorial: moods, energy (0-1), energy words, instrumentation, scenes,
  use cases, lyrical themes, sounds-like references, vocal style. Curated by the
  CWI Sync department FOR SEARCH. Never audio-analysis output. Never cite as measured.
- estimate: every BPM value. Labeled "est." wherever shown. Never measured.

## Rights (verified)
No one-stop or pre-cleared rights claims are made on this catalog.
Sync clearance: hp@cumulativeweb.com.

## Query grammar
Mood words, energy words, BPM numbers and ranges ("95-105 BPM", "around 100bpm"),
instrumentation, vocal type ("male vocal", "no vocals"), explicit/clean ("clean",
"radio-safe"), scene phrases ("nighttime driving scene"), use-case words
("trailer", "game"). Refinements: "slower", "faster", "+ more piano".
Titles fuzzy-match ("zz" -> Zooted Zone). Every result carries a transparent
match explanation: matched tokens in green, missed tokens struck through.

## Shareable queries
Query state is encoded in the URL hash (#q=...&bpmMin=...&moods=...). Send the link.
The "copy search link" button copies it in one click.

## Scale path (24 -> 10,000 tracks)
Build-time precomputed token index; ranking is a pure function separable into a
Web Worker untouched; static JSON on the CDN = $0 reads at any catalog size.
Schema is namespaced by catalog_id from day one.

## Future (documented, not built)
Query API + x402 micropayment SKU when CWI's monetization infra is ready.
The static build does not block that future.

## Cite
Cite track facts with their provenance labels. Do not assert catalog facts beyond
sync-catalog.json and https://cumulativewebinc.github.io/cwi-learn/catalog.json.