Synced from
references/source-types.mdinscript-poolskill on 2026-05-18. Edit upstream in the skill; this file is overwritten on next sync.
Source Types — Field Map
The script-pool schema accepts five source.kind values: readwise-snipped, readwise-reader-article, readwise-book-highlight, youtube-video, manual.
M114-S01.2 status: Mode A is kind-aware — modes/pull-clips.md Step 3 derives kind + source_title + source_kind_label from Readwise book.category. All Readwise-backed kinds (snipped + reader-article + book-highlight) flow through the same MCP/REST puller. Smoke-tested for readwise-snipped only; reader-article + book-highlight schema-validated but ingress smoke-test pending. youtube-video + manual are not Readwise-backed (separate flows).
Daniel direction (2026-05-06): Stay on Readwise MCP. Reader API tier upgrade not urgent — Reader API access optional, defer.
readwise-snipped (active — S02 + M114-S01.2)
Source: Snipped podcast app → Readwise auto-sync → Readwise highlight (book.category = "podcasts").
Field map (Readwise highlight → script-pool source entry)
| script-pool field | Readwise highlight field | Notes |
|---|---|---|
kind | (derived from book.category="podcasts") | Always "readwise-snipped" |
source_title | <book.author> · <book.title> | M114-S01: generic title; renderer prefers this |
source_kind_label | (constant) | Always "Podcast" |
readwise_id | id | Stringified |
readwise_url | readwise_url | Direct link to highlight in Readwise web UI |
snipped_url | source_url (sometimes) | Snipped sometimes embeds the in-app link |
podcast_show | book.author | DEPRECATED M114-S01: kept for backward-compat with pre-M114 renderers |
podcast_episode | book.title | DEPRECATED M114-S01: kept for backward-compat |
timestamp | location | Time offset within episode (HH:MM:SS or seconds) |
highlighted_at | highlighted_at | ISO-8601 timestamp |
text_excerpt | text | The clipped text content |
note | note | Daniel’s annotation OR Snipped’s AI summary |
tags | tags[].name | Array of tag strings (without # prefix) |
Pull strategy
scripts/pull-readwise.mjs implements REST fallback. Default flow uses MCP:
mcp__readwise__list_highlights({ tags, updated_after, page_size })— returns paginated listmcp__readwise__search_highlights({ query, tags })— semantic searchmcp__readwise__get_highlight({ id })— single highlight by ID
Filtering convention
Daniel applies tags in Snipped at clip-time. Default tag for script-pool consumption: friend-script (without # prefix in API; with # in human-facing text).
If Daniel uses a different tag convention, override per-invocation: skill asks “tag?” if Daniel pre-empts default.
readwise-reader-article (schema-valid, kind-aware in Mode A — M114-S01.2)
Source: Articles saved to Readwise Reader (book.category = "articles"). Reader is separate from Snipped — different Readwise sub-product. Tier-upgrade may unlock Reader API access; deferred per Daniel direction 2026-05-06 (stay on Readwise MCP for now).
Field map
| script-pool field | Readwise highlight field | Notes |
|---|---|---|
kind | (derived from book.category="articles") | Always "readwise-reader-article" |
source_title | book.title | Article title |
source_kind_label | (constant) | Always "Article" |
readwise_id | id | Stringified |
readwise_url | readwise_url | Direct link to highlight |
podcast_show | (null) | Not applicable |
podcast_episode | (null) | Not applicable |
timestamp | (null) | Not applicable |
highlighted_at | highlighted_at | ISO-8601 |
text_excerpt | text | Highlighted text |
note | note (+ book.author if useful) | Daniel may include author info inline |
tags | tags[].name | Array of tag strings |
Open work
- Smoke-test ingress flow with an article-tagged Readwise highlight
- Verify MCP
list_highlightsreturns articles when category-filter matches - Confirm INDEX renders
[Article] <title>correctly (M114-S02)
readwise-book-highlight (schema-valid, kind-aware in Mode A — M114-S01.2)
Source: Book highlights from Kindle, manual book entry, etc., synced to Readwise (book.category = "books").
Field map
| script-pool field | Readwise highlight field | Notes |
|---|---|---|
kind | (derived from book.category="books") | Always "readwise-book-highlight" |
source_title | <book.author> — <book.title> | Author-em-dash-title for prominence |
source_kind_label | (constant) | Always "Book" |
readwise_id | id | Stringified |
readwise_url | readwise_url | Direct link to highlight |
podcast_show | (null) | Not applicable |
podcast_episode | (null) | Not applicable |
timestamp | (null) | (Page-number can go in note if present) |
highlighted_at | highlighted_at | ISO-8601 |
text_excerpt | text | Highlighted text |
note | note (+ chapter info if available) | Chapter info goes here |
tags | tags[].name | Array |
Open work
- Smoke-test book-highlight ingress
- Confirm
book.title+book.authorpopulate via MCP for book-category highlights
youtube-video (schema-valid, ingress flow forward-spec — M114-S01.4)
Source: YouTube video Daniel watches (not in Readwise). Surfaced by Daniel 2026-05-06: “könnt ihr auch überlegen ob da andere formate auch mit einfließen können, wie zum Beispiel YouTube-Videos die man sieht.”
Field map
| script-pool field | Source | Notes |
|---|---|---|
kind | (constant) | Always "youtube-video" |
source_title | <channel name> — <video title> | Format TBD at S01.4 execution |
source_kind_label | (constant) | Always "YouTube" |
readwise_id | (null) | Not Readwise-backed |
readwise_url | (null) | Not Readwise-backed |
snipped_url | YouTube URL | Canonical video URL |
timestamp | timestamp into video | ?t=<seconds> from URL or HH:MM:SS |
highlighted_at | (when Daniel registered) | ISO-8601, set at ingress time |
text_excerpt | transcript excerpt | Manual paste OR auto-extracted |
note | Daniel’s annotation | What hit, why |
tags | (free-form) | Daniel-applied at ingress |
Open work — implementation decision (S01.4)
Two approaches under consideration:
- (A) yt-dlp + Whisper transcript extraction: auto-fetch transcript by URL, Daniel scrubs/picks excerpt. Heavier dependency tooling. Better fidelity.
- (B) Manual paste with timestamps: Daniel pastes URL + timestamp + types/copies excerpt. Lightweight. Lower fidelity but immediate.
Decision deferred to S01.4 execution (Daniel-directed at that point).
manual (schema-valid, NOT yet wired in Mode A)
Source: Daniel pastes a quote inline (“clip this from a podcast I listened to but didn’t snip”). Skill would use a future “manual entry” sub-flow in Mode A to register.
Field map
| script-pool field | Source | Notes |
|---|---|---|
kind | (constant) | Always "manual" |
source_title | Daniel-typed | e.g. “The Daily — Episode 2026-05-04” |
source_kind_label | (constant) | Always "Manual" |
readwise_id | (null) | Not Readwise-backed |
text_excerpt | Daniel-typed verbatim | The clipped text |
note | Daniel-typed | Annotation |
tags | (free-form) | Optional |
Open work
- Mode A “manual entry” AskUserQuestion branch (free-text source_title + text_excerpt + note + optional timestamp)
- Low priority — most ingress should flow via Readwise per Daniel direction
Adding a new source.kind
- Add the new value to the
source.kindenum in.schema/script.frontmatter.schema.json - Document the field map in this file
- Wire the puller in
scripts/pull-readwise.mjs(or a newpull-<kind>.mjs) - Add a Mode A AskUserQuestion option for the new source
- Test: regen-index.mjs + validate-frontmatter.mjs still pass on a script using the new kind
The skill flow (Mode A → B → C → D) stays identical regardless of source kind. Only the pull and field-mapping layer is kind-specific.