YouTube Cairns Blueprint.

How this fits in the OS.

What you'll build.

By the end of this build you have a local vault with three folders: cairns/L1/, card-catalog/L2/, and raw/transcripts/. You pick a public YouTube channel. The pipeline pulls a few captions, drafts a dense card per video, links the cards to ten durable waypoints, and embeds all three layers into Supabase so your agent can answer questions and cite the exact source.

The reference vault behind the public Build Lab lessons holds 56,621 transcripts across 48 channels at $0 external API cost, ingested over years using this same shape. You will not match that on a Sunday. That is fine. The Sunday goal is the shape working end to end on a small slice you actually care about. Scale is just more channels and more nights.

What changes for you.

The pipeline itself is straightforward Python. The bigger thing is the shift in how you treat YouTube as a knowledge source. Three internal shifts you'll feel:

• You stop bookmarking videos you'll never rewatch. The captions go into a vault you can query. "What did that channel say about Cairns retrieval?" becomes a real question with a sourced answer, not a search through your watch history.
• You stop dumping raw transcripts into chat windows. The agent reads waypoints first, picks a card, opens the raw transcript only to verify. Your context window stays small. Your answers stay grounded.
• You start thinking of overnight as compute time. Once the shape works, the next move is a cron job. Channels you follow get checked nightly. New videos land, get transcribed, get embedded, get summarized, get linked. By morning, the vault is current. You wake up to a brief, not a backlog.

Before you start.

This build assumes a few things are already in place. If any of these are unfamiliar, work through the prereq cards first.

• You understand the Cairns three-tier shape. If L1, L2 Chain of Density Card Catalog Layer, L3 doesn't ring a bell yet, read The Cairns Three Tiers first. The blueprint assumes you know the contract.
• Python 3.10 or newer. Standard library only. The pipeline scripts have zero dependencies beyond yt-dlp.
• yt-dlp installed locally. brew install yt-dlp on macOS, pip install yt-dlp works on Windows. The pipeline calls it as a subprocess, so all it needs is a yt-dlp command on your PATH. If Homebrew starts compiling rust or deno from source (it does that on a macOS version it no longer ships pre-built packages for), stop it and run pipx install yt-dlp instead. You do not need Xcode.
• A Supabase project with the vector extension available. Free tier is fine for a Sunday build. You will run one SQL migration to create namespaced tables.
• An OpenAI API key for embeddings, stored in your password manager. The blueprint defaults to text-embedding-3-small. You can swap in a local model later, but the starter uses OpenAI so you can finish in one session.
• Optional, only if you want graph traversal. Neo4j Desktop, Aura, or a local Neo4j server. The Sunday build does not require it.
• Public content only. Public YouTube channels, or channels you have rights to process. Do not point this at private uploads or content with usage restrictions.

The build.

Five phases. The starter prompt at the top of the page walks Claude through all of them with confirmation gates between each one. What follows is each phase in order, with what to paste into Claude Code and how to know it worked.

When it works.

Success looks specific. If all of these are true, the blueprint is doing its job:

• L3 transcripts are immutable. You can re-run build.py and the same video does not get rewritten. The raw layer is a one-way ratchet.
• L2 Chain of Density Card Catalog Layer cards each cite one L3 source. Every card has a path back to the transcript that generated it. No card invents content the transcript doesn't contain.
• L1 waypoints stay small. Ten Cairns. New videos can propose an L1 update through the card's promotion note, but L1 doesn't silently rewrite itself.
• Queries cite cards and sources. The answer to "what did this channel say about X" comes back with the L2 Chain of Density Card Catalog Layer card name and the L3 video URL. No citations means the retrieval cascade fell down somewhere, not that the answer is bad.
• Adding a channel is cheap. Edit channels.yaml, re-run the three pipeline commands, the new content lands in the same three layers. No new code.

If you get stuck.

Common failure modes, ranked by how often they bite people:

• Tried to ingest 40 channels on the first pass. Most common. Start with one channel, three videos. Confirm the shape. Then scale.
• Edited an L3 transcript to "clean it up." Don't. The raw layer exists so the agent can cite evidence and you can audit the answer. Record corrections in L2 Chain of Density Card Catalog Layer or create a reviewed derivative.
• Skipped the L2 Chain of Density Card Catalog Layer review. Treated the deterministic enricher's output as final. The starter cards are drafts. Read them. Fix the obvious misses. The prompt improves from seeing the first few outputs.
• Pasted a real Supabase service key into the chat. Rotate the key immediately, then redo the env step with Infisical or 1Password and the placeholder pattern. If Claude offers to enter the real key for you, say no. Real values go into your password manager and into pipeline/.env directly.
• Query returns generic answers without citations. The cascade didn't reach L2 Chain of Density Card Catalog Layer or L3. Check that ingest-rag.py wrote rows to all three tables (sources, chunks, cairns). If any count is zero, embedding failed for that layer.
• Channel has weird caption coverage. Some channels have great auto-captions, some have nothing. If the channel you care about has poor captions, this blueprint is the wrong starting tool. You'd want a transcription pipeline (MacWhisper or Parakeet) feeding into build.py instead.

Still stuck? Post the channel slug, the phase you're on, and the actual error, in the workshop Slack. Someone in the cohort hit the same thing.

Where to go next.

You shipped the first vault. The pattern compounds from here. The natural next moves on the shelf: