/know — capture sources into the vault

Capture each source as either a bookmark record (60-bookmarks/) or a pass-1 source record (50-resources/sources/<medium>/). Capture is cheap and shallow by default; /deepen escalates later. Never classify by topic at capture.

Contract (binding)

1. Never store verbatim source text as the working note. The record is compressed, in your own words. Verbatim material (transcripts, PDFs, HTML) goes only in an evidence package.
2. Captures are immutable once written. Later synthesis links back; it does not edit the capture. /deepen may fill empty sections and update processing/updated, but never rewrites existing prose.
3. topics: stays empty at capture. Classification is deferred until material accumulates (three meaningful sources per theme).
4. Not everything deserves a note. Link-only material becomes a bookmark. Junk gets declined with one line of reasoning.
5. This is retrieval, not understanding. After a batch, invite (don't force) the user to add one sentence per capture on why it matters — that sentence goes in the record body under ## Why I saved this.

Procedure

0. Arguments

• With arguments: process each URL/path sequentially.
• Without: say you're in batch-intake mode, await a list, then process sequentially.
• Handle bare domains (pi.dev → https://pi.dev), GitHub repos, docs sites, local PDFs.

1. Fetch and triage each item

Fetch the page — prefer defuddle parse <url> --md over WebFetch when the defuddle CLI is installed (otherwise use WebFetch or your harness's fetch tool) for standard web pages (articles, docs, blog posts): it strips navigation and clutter, and -p title / -p description / -p domain feed the frontmatter. Use WebFetch for raw .md URLs; for repos also read the README. Then decide:

• Bookmark — reference/tool/homepage you'd revisit but not extract claims from. → 60-bookmarks/<slug>.md
• Source record — substantive material with claims worth extracting later (talk, paper, essay, repo with ideas, docs explaining a design). → 50-resources/sources/<medium>/<slug>.md where <medium> ∈ videos | podcasts | articles | papers | books | audio | other (repos and docs sites → other unless clearly an article).
• Decline — no durable value. Report it in the summary with the reason; write nothing.

If the same URL already exists as a bookmark or source record (search 60-bookmarks/ and 50-resources/sources/ for the URL), report "already captured" and skip.

2. Write the record

Filenames: lowercase kebab-case slug of the content (idea/title-scented, not domain-scented). Create missing sources/<medium>/ directories as needed. If 00-meta/templates/Source Record.md exists, follow it; otherwise use the inline schemas below (they are the same schema — it lands with the selective-vault-migration branch).

Bookmark record:

---
type: resource
status: active
created: YYYY-MM-DD        # today
updated: YYYY-MM-DD
captured: YYYY-MM-DD
url: https://...
tags: [lowercase, hyphenated, plural]
title: <original title>
---

Body: 2–4 sentences in your own words — what it is, who made it, why someone would come back to it.

Pass-1 source record:

---
type: resource
status: active
created: YYYY-MM-DD
updated: YYYY-MM-DD
tags: [<medium tag>, processed-sources]
captured: YYYY-MM-DD
source_type: video | podcast | audio | article | paper | book | other
processing: captured
url: https://...
authors:
  - "[[Person Name]]"     # only when clearly identifiable; omit otherwise
---

Body sections (pass-1 fills only these; leave the rest for /deepen):

# <Source Title>

## Executive takeaway
<3–6 sentences, own words: what this is, who made it, the central claim, why it might matter.>

## Claims and evidence
- <central claim, one sentence, own words> ^claim-<2-5-word-kebab-slug-of-the-idea>

## Retained evidence
<link to evidence package, or "URL only — no local evidence retained.">

Claim block IDs name the idea, not the source (^claim-verbatim-overlap-hurts-recall, not ^claim-smith-2026). Unique within the file; never rename once written.

3. Evidence packages (only when warranted)

If bulky verification material exists and is worth keeping (transcript, PDF, key article text), save it under 50-resources/evidence/<source-slug>/ — for articles, retain defuddle's clean markdown output rather than raw HTML and link it from ## Retained evidence plus an evidence: "50-resources/evidence/<source-slug>/" frontmatter field. A public URL alone is sufficient for most captures — do not archive by default. Every evidence package must be owned by exactly one source record; never create an orphan.

3a. Video sources always get an evidence package (transcript + key frames)

Never transcribe by watching or paraphrase from memory of the page — use subtitles, and work in the scratchpad, not the vault.

If yt-dlp or ffmpeg is not installed, do not improvise a substitute. Write the source record from the page metadata alone, set evidence: to nothing, add a ## Retained evidence line saying "none — yt-dlp/ffmpeg unavailable at capture", and tell the owner which tool to install before /deepen can read the video.

1. Metadata: yt-dlp --skip-download --print "%(title)s | %(uploader)s | %(upload_date)s | %(duration_string)s" <url> — feeds the record's frontmatter and takeaway.
2. Transcript: yt-dlp --skip-download --write-subs --write-auto-subs --sub-langs "en.*" --sub-format vtt -o "<scratchpad>/<slug>" <url>. Prefer manual subs over auto-captions when both exist. Convert the VTT to timestamped lines (m:ss text, rolling-caption duplicates removed) and write 50-resources/evidence/<slug>/transcript.md, matching the existing transcript idiom: frontmatter (type: resource, tags research-evidence + transcripts, source: owner wikilink), the original URL, a caveat line when captions are automatic, then ## Timestamped transcript.
3. Key frames — when the transcript suggests visual content (a conference talk, slides, diagrams, demos): download video to the scratchpad at slide-legible resolution (yt-dlp -f "bv*[height<=1440]/bv*" -o "<scratchpad>/<slug>.mp4" <url>). If that selector 403s or otherwise fails and yt-dlp silently falls back to a low-res combined format (e.g. format 18, 360p), do not extract from it — run yt-dlp -F <url> to list formats, retry with an explicit higher-resolution itag (prefer 1080p if available; e.g. -f 299 or -f 399), and confirm before extracting. Then extract scene-change candidates (ffmpeg select='gt(scene,0.30)' with -vsync vfr, mapping each frame back to its timestamp), view the frames, and keep only the ≤15 that carry information — slides, architecture diagrams, benchmark tables, demo states. Discard talking heads and near-duplicates. Save keepers with ffmpeg -ss <t> -i <video> -frames:v 1 -q:v 2 <out>.png as 50-resources/evidence/<slug>/frames/<mm-ss>-<short-hint>.png, and verify resolution before writing to the vault (file <file> or ffprobe -v error -show_entries stream=width,height <file> — text/code slides should land at the source's native resolution, not a downscaled fallback; re-extract if pixelated). List keepers with one-line descriptions in the transcript's or record's ## Retained evidence. Delete the video file afterward — evidence retains frames and transcript, never the video (re-fetch it if /deepen needs more frames).
4. A face-to-camera video with no visual content gets a transcript only; say so.
5. Pass-1 stays pass-1: the takeaway comes from skimming the transcript, and claims tied to a slide cite the frame and timestamp.

4. Questions register (if present)

If 00-meta/questions.md exists, scan open questions; when a capture plausibly answers one, add answers: [Q<n>] to its frontmatter and say so in the summary. Do not close the question yourself.

5. Log and report

• Append one row for the whole batch to the 00-meta/log.md table: | YYYY-MM-DD | ingest | /know batch: <n> sources, <m> bookmarks (<short theme hint>) |. Do not update 00-meta/index.md (captures are never hubs).
• Report a summary table: item → disposition (bookmark / source record / declined / duplicate) → path → one-line takeaway.
• Report accumulation pressure: count records in 50-resources/sources/ with processing: captured and note any informal theme with ≥3 sources as "ready for classification" (suggest /classify; do not cluster here).
• If capture volume is far outrunning deepening (many captured, few processed), say so plainly: the vault is accumulating a library, not understanding.

Legacy awareness

The vault has three content generations; read all, imitate only the newest:

1. Pre-pipeline notes (most of 40-areas/, 50-resources/concepts|books|papers/) — untyped links, no claims blocks. Never retrofit them.
2. Research-graph records (60-bookmarks/ imports with extra fields like source:/read:; source records per the body contract) — this is the schema you write.
3. Post-amendment notes — claims block IDs and typed relations (extends, contradicts, special-case-of, supersedes, supports as field:: [[target]] inline fields), which you use where sections call for them.

Old bookmark imports may have fields you don't write (source, read, promoted_to); leave them alone.