Editorial Curation & Starter Picks
Relevant source files
The following files were used as context for generating this wiki page:
The Editorial Curation system in Kocteau is designed to solve the "cold-start" problem for new users or sparse feeds. While the primary experience is driven by human-led music reviews and lightweight recommendation algorithms, Starter Picks serve as curated track prompts that bridge the gap until a user's "For You" feed has sufficient activity. These picks are not fake reviews but curated suggestions ranked against a user's initial taste onboarding signals.
Sources: README.md:214-222, AGENTS.md:27-35
System Architecture
The curation workflow moves from discovery to a temporary queue, and finally into the "Starter Catalog." Curators use the Starter Studio to manage this pipeline, utilizing Deezer search and automated candidate suggestions.
The diagram shows the lifecycle of a starter pick, from its initial discovery as a candidate to its conversion into a real review that influences the recommendation engine.
Sources: apps/web/components/starter-studio-client.tsx:280-360, README.md:224-228
Starter Studio Client
The StarterStudioClient is the primary administrative interface for curators (typically users with the curator role). It provides a unified dashboard for searching the global music catalog, managing a queue of potential candidates, and editing the metadata for active starter picks.
Key Functional Components
- Candidate Finder: Uses modes like
related-seedanddeep-cutto suggest tracks based on a seed artist or scene. - Signal Library: A management interface for
preference_tags. Curators must assign "signals" to tracks to ensure they map correctly to user tastes. - Inspector Rail: A contextual sidebar for editing prompts, editorial notes, and "Featured" status for a selected track.
Sources: apps/web/components/starter-studio-client.tsx:142-260, AGENTS.md:143-155
Curation Metadata
Starter picks require specific editorial data to be effective:
| Field | Type | Description |
|---|---|---|
prompt | String | A short question or hook (e.g., "What should people pay attention to here?"). |
editorial_note | String | Internal or public justification for the pick's inclusion. |
is_featured | Boolean | If true, prioritizes the pick in the feed and rail. |
tag_ids | UUID[] | Associated signals used for ranking against user preferences. |
Sources: apps/web/components/starter-studio-client.tsx:49-65, apps/web/app/api/starter/candidate-queue/route.ts:50-75
Candidate Queue Management
Before a track is officially added to the Starter Catalog, it often resides in the editorial_candidates table. This allows curators to perform "slower listening" and verification before committing a track to the public catalog.
Curators can approve a candidate, which automatically triggers its creation in the starter_tracks table.
Sources: apps/web/app/api/starter/candidate-queue/route.ts:89-130, apps/web/components/starter-studio-client.tsx:428-460
Distribution Channels
Starter picks are surfaced in two primary locations within the web application:
1. The Editorial Rail
Located in the right-hand column on desktop, the WhoToFollowRail component displays a rotated selection of starter picks. To prevent staleness, the system uses a rotation logic based on the current path.
- Rotation Logic:
rotateStarterTracksuses a hash of the context key (URL) to select a stable but varied subset of tracks for the user. - Trigger: Clicking a pick opens a
NewReviewDialogpre-filled with the track's metadata.
Sources: apps/web/components/who-to-follow-rail.tsx:64-90, apps/web/components/who-to-follow-rail.tsx:230-260
2. Feed Layers (Starter Shelf & Layer)
In the primary feed (/), starter picks appear when the personalized recommendation results are sparse (less than 4 reviews).
FeedStarterLayer: A full-width module shown when the feed is empty.FeedStarterShelf: A horizontal carousel shown between reviews to provide continuous discovery.
Sources: apps/web/components/feed-review-list.tsx:165-185, apps/web/components/feed-review-list.tsx:440-460
Monitoring & Health
The system tracks "Recommendation Health" to ensure the editorial efforts are converting into user engagement. Curators monitor metrics such as:
- Starter Conversion: The rate at which starter impressions lead to published reviews.
- Tag Coverage: Ensuring that all
preference_kinds(mood, era, genre, etc.) have sufficient tracks assigned to them. - Fallback Rate: How often the "For You" feed fails and reverts to editorial defaults.
Sources: apps/web/components/recommendation-health-summary.tsx:90-130, README.md:232-245
Conclusion
The Editorial Curation system is a critical component of Kocteau's hybrid discovery model. By combining manual curation via the Starter Studio with algorithmic distribution, the platform maintains an "editorial feel" even when user-generated data is unavailable. The transition of starter picks into real reviews ensures that curated human taste directly feeds back into the automated recommendation graph.
Sources: README.md:289-293, AGENTS.md:16-24