Sources
A source is a thing that fills your Library — a configured link between Trove and an upstream system. Each source points at something specific (e.g., “My Tech RSS” pointing at a particular feed URL, or “HN Top Stories” pulling your Hacker News saves), and a source can have several feeds — the individual publications, accounts, or shows it follows.
Source Types
Section titled “Source Types”| Type | Description |
|---|---|
hacker-news | Hacker News saved stories and top posts |
rss | RSS and Atom feeds |
arxiv | arXiv paper feeds |
manual | Content saved via trove_save or the API |
| Your own | Any type you define via the API |
How Sources Sync
Section titled “How Sources Sync”Trove does not fetch from upstream systems itself. A sync client — the Trove Mac app, or your own code built against the Sync API — fetches content and pushes it into Trove. The cloud’s job is to store, index, and search what it receives.
This means scheduling, retries, and credential handling all live in the sync client, not in Trove. A source record is the cloud’s view of what you follow: its type, status, config (preferences only — no credentials), and the documents that have been pushed so far.
Lifecycle
Section titled “Lifecycle”| Status | Meaning |
|---|---|
SETUP | Created but not yet fully configured |
ACTIVE | Running normally. The sync client pushes new content as it syncs. |
PAUSED | Marked paused. The sync client should stop syncing it until resumed. |
ERROR | The last sync reported a failure. Check errorMessage for details. The sync client retries on its next run. |
Sync Runs
Section titled “Sync Runs”The sync client records a SyncRun after each sync (via the createSyncRun mutation), giving you a queryable history. Each record tracks:
- Status.
RUNNING,SUCCESS,ERROR, orCANCELLED - Documents synced. How many new documents were indexed
- Duration. How long the sync took
- Cursor. Position marker for incremental sync, so the next run picks up where this one left off
View sync history via the syncRuns field on any source.
Manual Saves Source
Section titled “Manual Saves Source”The first time you use trove_save (from Claude) or the saveDocument mutation (GraphQL), Trove automatically creates a “Manual Saves” source with type manual and status ACTIVE. All manually saved content goes here.
Source Config
Section titled “Source Config”Each source has a JSON config object with source-specific preferences (feed URLs, section lists, filter parameters). Config holds preferences only — credentials never live in the cloud; the sync client keeps them locally (e.g., in the macOS Keychain).
Managing Sources
Section titled “Managing Sources”| Mutation | Purpose |
|---|---|
createSource | Create a new source with type, name, and config |
updateSource | Change name, description, or config |
pauseSource | Mark a source paused (status changes to PAUSED) |
resumeSource | Resume a paused source (status changes to ACTIVE) |
deleteSource | Remove a source and all its documents |