kd-engine 1.0.0__py3-none-any.whl

ytk/renderers/markdown_renderer.py

@@ -0,0 +1,540 @@
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+
+def source_processing_notice(bundle: Any) -> str:
+    """Keep acquisition provenance distinct from human review and visual coverage."""
+    source = getattr(bundle, "transcript_source", "unknown")
+    notice = {
+        "manual": "Extracted from manual captions",
+        "auto": "Extracted from auto-generated captions; not human reviewed",
+        "asr": "Extracted from ASR speech-to-text; not human reviewed",
+        "yt_dlp": "Transcript acquired via yt-dlp; caption type not independently verified",
+        "minimax": "Cloud-model video interpretation; not human reviewed",
+    }.get(source, "Transcript source unknown")
+    scope = ("Visual coverage not independently verified (画面覆盖范围未独立验证)"
+             if source == "minimax" else "Visuals not analysed (未分析画面); slides and demonstrations may be missing")
+    return notice + ". " + scope + "."
+
+
+class MarkdownRenderer:
+    """Render an ExtractionBundle into a clean, human-readable Markdown note."""
+
+    # ── Garbage-detection patterns ──────────────────────────────────
+    _TRUNCATION_ENDINGS = re.compile(
+        r"(?:In|The|Once|Now we are|or|and|the|a|in|But|So|That|This|It|We|They"
+        r"|You|He|She|What|How|Why|When|Where|Who|Is|Are|Was|Were|Do|Does|Did"
+        r"|Can|Could|Will|Would|Should|May|Might|Must|Shall|Has|Have|Had"
+        r"|Not|No|Yes|But|Just|Only|Also|Even|Still|Already|Yet|Now|Then"
+        r"|Here|There|Well|OK|Okay|Right|Sure|Good|Great|Fine|Nice"
+        r"|Like|Just|Really|Very|Much|More|Most|Less|Least|Too|Also)\.$"
+    )
+    _NATURAL_LANGUAGE_FRAGMENT = re.compile(
+        r"^[A-Z][a-z].*\b(?:can|will|is|are|was|were|it|we|you|they|the|this|that)\b"
+    )
+    _YAML_SPECIAL_RE = re.compile(r"[:#&*!|>%@`]")
+
+    # ── Public API ─────────────────────────────────────────────────
+
+    def render(self, bundle: Any, output_path: Path, **kwargs: Any) -> None:
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        video_url = bundle.metadata.get(
+            "canonical_url",
+            f"https://www.youtube.com/watch?v={bundle.video_id}",
+        )
+        title = str(bundle.metadata.get("title", bundle.video_id))
+
+        src = bundle.transcript_source
+        clean_atoms = [a for a in bundle.knowledge_atoms if not self._is_garbage(a, source=src)]
+
+        lines: list[str] = []
+
+        # ── Header ─────────────────────────────────────────────
+        lines.append(f"# {title}")
+        lines.append("")
+        lines.append(f"> 📺 [Watch on YouTube]({video_url})")
+        caption_note = source_processing_notice(bundle)
+        lines.append(f"> 🕐 {caption_note}")
+        lines.append("")
+        lines.append("---")
+        lines.append("")
+
+        # ── Summary (legacy section — tests assert exact format) ──
+        lines.append("## Summary")
+        lines.append("")
+        lines.append(f"- Video ID: `{bundle.video_id}`")
+        lines.append(f"- Transcript source: `{bundle.transcript_source}`")
+
+        canonical_url = bundle.metadata.get("canonical_url")
+        if canonical_url:
+            lines.append(f"- Canonical URL: {canonical_url}")
+
+        lines.append("")
+
+        # ── Overview (new beautiful section) ───────────────────
+        overview = self._build_overview(bundle, clean_atoms)
+        if overview:
+            lines.append("## Overview")
+            lines.append("")
+            for para in overview:
+                lines.append(para)
+            lines.append("")
+            lines.append("---")
+            lines.append("")
+
+        # ── Executive Summary (legacy — tests assert "stands out in") ──
+        executive_summary = self._build_executive_summary(bundle, clean_atoms)
+        if executive_summary:
+            lines.append("## Executive Summary")
+            lines.append("")
+            for line in executive_summary:
+                lines.append(f"- {line}")
+            lines.append("")
+
+        # ── Key Takeaways (legacy — tests assert this structure) ──
+        grouped = self._group_atoms(clean_atoms)
+        if any(grouped.values()):
+            lines.append("## Key Takeaways")
+            lines.append("")
+            self._append_group(
+                lines,
+                "Commands",
+                grouped["terminal_command"],
+                formatter=lambda atom: f"- `{atom.content}`",
+            )
+            self._append_group(
+                lines,
+                "Files & Config",
+                grouped["configuration_snippet"],
+                formatter=lambda atom: f"- `{atom.content}`",
+            )
+            self._append_group(
+                lines,
+                "Concepts",
+                grouped["core_concept"],
+                formatter=lambda atom: f"- `{atom.content}`: {self._display_explanation(atom)}",
+            )
+            self._append_group(
+                lines,
+                "Workflows",
+                grouped["workflow_step"] + grouped["best_practice"],
+                formatter=lambda atom: f"- {atom.content}",
+            )
+            self._append_group(
+                lines,
+                "Code Blocks",
+                grouped["code_block"],
+                formatter=lambda atom: f"- `{atom.content}`",
+            )
+            self._append_group(
+                lines,
+                "Command Sequences",
+                grouped["command_sequence"],
+                formatter=lambda atom: f"- `{atom.content}`",
+            )
+
+        # ── Topic Notes (legacy — tests assert atom details) ───
+        lines.append("## Topic Notes")
+        lines.append("")
+
+        atoms_by_topic = defaultdict(list)
+        for atom in clean_atoms:
+            topic_key = self._topic_key_from_path(atom.topic_path)
+            atoms_by_topic[topic_key].append(atom)
+
+        rendered_topics: set[str] = set()
+        for topic in bundle.topic_segments:
+            rendered_topics.add(topic.id)
+            lines.append(f"## {topic.title} ({topic.start:.1f}s–{topic.end:.1f}s)")
+            lines.append("")
+            if topic.sentences:
+                lines.append(f"- Summary: {topic.sentences[0]}")
+            lines.append("")
+
+            for atom in atoms_by_topic.get(topic.id, []):
+                lines.append(
+                    f"### {atom.atom_type.replace('_', ' ').title()}: {atom.content}"
+                )
+                lines.append(f"- Confidence: {atom.confidence:.2f}")
+                lines.append(f"- Explanation: {atom.explanation}")
+                for evidence in atom.evidence:
+                    lines.append(
+                        f"- Evidence: `{evidence.text}` "
+                        f"({evidence.start:.1f}s-{evidence.end:.1f}s, {evidence.source})"
+                    )
+                for timestamp in atom.timestamps:
+                    lines.append(
+                        f"- Watch: https://www.youtube.com/watch"
+                        f"?v={bundle.video_id}&t={int(timestamp)}s"
+                    )
+                lines.append("")
+
+        for topic_key, atoms in atoms_by_topic.items():
+            if topic_key in rendered_topics:
+                continue
+            display_name = (
+                atoms[0].topic_path[0] if atoms and atoms[0].topic_path else "Ungrouped"
+            )
+            lines.append(f"## {display_name}")
+            lines.append("")
+            for atom in atoms:
+                lines.append(
+                    f"### {atom.atom_type.replace('_', ' ').title()}: {atom.content}"
+                )
+                lines.append(f"- Confidence: {atom.confidence:.2f}")
+                lines.append(f"- Explanation: {atom.explanation}")
+                for evidence in atom.evidence:
+                    lines.append(
+                        f"- Evidence: `{evidence.text}` "
+                        f"({evidence.start:.1f}s-{evidence.end:.1f}s, {evidence.source})"
+                    )
+                for timestamp in atom.timestamps:
+                    lines.append(
+                        f"- Watch: https://www.youtube.com/watch"
+                        f"?v={bundle.video_id}&t={int(timestamp)}s"
+                    )
+                lines.append("")
+
+        # ── Stats footer ───────────────────────────────────────
+        lines.append("")
+        lines.append("---")
+        lines.append("")
+        lines.append("## Stats")
+        lines.append("")
+        lines.append(f"- Total knowledge atoms: {len(bundle.knowledge_atoms)}")
+        type_counts: dict[str, int] = {}
+        for atom in bundle.knowledge_atoms:
+            type_counts[atom.atom_type] = type_counts.get(atom.atom_type, 0) + 1
+        for atype, count in sorted(type_counts.items()):
+            lines.append(f"- {atype.replace('_', ' ').title()}: {count}")
+
+        lines.append("")
+        lines.append(
+            f"*Generated by knowledge-distiller v2.0"
+            f" • {len(bundle.knowledge_atoms)} knowledge atoms extracted*"
+        )
+
+        output_path.write_text("\n".join(lines), encoding="utf-8")
+
+    # ── Sanitization helpers ───────────────────────────────────────
+
+    @classmethod
+    def _is_garbage(cls, atom: Any, *, source: str = "auto") -> bool:
+        """Return True when an atom is noise that shouldn't appear in output.
+
+        Universal checks (all sources):
+        - Very low confidence
+        - && join artifacts from heuristic extractor
+        - Terminal commands with slash prefix + boilerplate explanation
+        - Workflow steps with heuristic template explanation
+        - Core concepts with truncated descriptions
+
+        Auto/ASR only checks:
+        - Mid-sentence fragments (lowercase start)
+        - Too few words
+        - Truncated caption endings
+        - Natural language command_sequence fragments
+
+        Note on "template" rules: an atom with a heuristic-style template
+        explanation (e.g. "This sentence expresses an ordered workflow
+        instruction.") is only treated as noise when it has no transcript
+        evidence attached. Real tutorial extractions always carry evidence
+        with a start/end timestamp pointing back to the source caption, so
+        keeping those atoms preserves the most useful tutorial knowledge
+        rather than silently dropping it. v2.0 originally filtered these
+        unconditionally; that turned out to discard the bulk of the
+        workflow_step and command_sequence atoms from real YouTube
+        tutorial transcripts (validated on vRYBG_R8JAI, 2026-06-07).
+        """
+        content = str(atom.content).strip()
+        explanation = str(getattr(atom, "explanation", "")).strip()
+        has_evidence = bool(getattr(atom, "evidence", None))
+
+        # ── Universal garbage patterns ──────────────────────────
+
+        # Confidence too low
+        if atom.confidence < 0.5:
+            return True
+
+        # Join artifacts from heuristic extractor (always noise)
+        # KEEP if the atom has transcript evidence — heuristic joins are
+        # noise when fabricating, but legitimate when each step is grounded
+        # in the source transcript.
+        if "&&" in content and not has_evidence:
+            return True
+
+        # Heuristic template workflow steps (not real instructions)
+        # KEEP if the atom has transcript evidence — same reasoning.
+        if (
+            atom.atom_type == "workflow_step"
+            and explanation == "This sentence expresses an ordered workflow instruction."
+            and not has_evidence
+        ):
+            return True
+
+        # Core concept with truncated (very short) description
+        grounded_chinese = has_evidence and len(re.findall(r"[\u4e00-\u9fff]", content + explanation)) >= 4
+        if atom.atom_type == "core_concept" and len(explanation) < 10 and not grounded_chinese:
+            return True
+
+        # Heuristic template core concept (a/an X is a Y) — keep if
+        # evidence is present so we surface real tutorial concepts.
+        if (
+            atom.atom_type == "core_concept"
+            and "mentioned in the video that relates to" in explanation
+            and not has_evidence
+        ):
+            return True
+
+        # ── Auto/ASR only weak-signal patterns ──────────────────
+        if source not in ("auto", "asr"):
+            return False
+
+        # Chinese clauses do not use spaces as word boundaries. English word
+        # counts otherwise discard every grounded Chinese ASR instruction.
+        if grounded_chinese:
+            return False
+
+        # Terminal commands that are auto-caption truncations
+        if (
+            atom.atom_type == "terminal_command"
+            and content.startswith("/")
+            and "as shown in the transcript" in explanation
+        ):
+            return True
+
+        # Core concept with template-generated explanation (auto captions only)
+        if atom.atom_type == "core_concept" and (
+            explanation
+            == "Important Claude Code workflow concept mentioned in the transcript."
+        ):
+            return True
+        if content and content[0].islower() and atom.atom_type != "terminal_command":
+            return True
+
+        # Too short and not a terminal command
+        word_count = len(content.split())
+        if word_count < 5 and atom.atom_type != "terminal_command":
+            return True
+
+        # Truncated auto-caption endings
+        if cls._TRUNCATION_ENDINGS.search(content):
+            return True
+
+        # Command sequence atoms that are natural language, not commands
+        if atom.atom_type == "command_sequence" and cls._NATURAL_LANGUAGE_FRAGMENT.match(
+            content
+        ):
+            return True
+
+        return False
+
+    @classmethod
+    def clean_content(cls, text: str) -> str:
+        """Sanitize a single piece of content text."""
+        text = text.strip()
+        text = re.sub(r"\s*(?:stands out|is used|is covered|is discussed)\s+in\s+.*$", "", text)
+        if text and text[0].islower():
+            text = text[0].upper() + text[1:]
+        return text
+
+    @classmethod
+    def clean_tag(cls, tag: str) -> str:
+        """Produce a clean Obsidian-safe tag."""
+        tag = tag.strip()
+        tag = tag.replace("\n", " ").replace("\r", " ")
+        tag = re.sub(r"[.,;!?()\s]+$", "", tag)
+        tag = re.sub(r"^[.,;!?()\s]+", "", tag)
+        tag = cls._YAML_SPECIAL_RE.sub("", tag)
+        tag = tag.replace(",", "-")
+        tag = tag.replace(" ", "-")
+        tag = re.sub(r"-+", "-", tag)
+        tag = tag.strip("-")
+        if re.match(r"^topic-\d+$", tag):
+            return ""
+        if len(tag) < 3:
+            return ""
+        if len(tag.split("-")) >= 5:
+            return ""
+        return tag
+
+    # ── Overview builder ───────────────────────────────────────────
+
+    def _build_overview(self, bundle: Any, clean_atoms: list) -> list[str]:
+        """Build 2-3 sentence overview from topic segments."""
+        paragraphs: list[str] = []
+        sentences: list[str] = []
+        for topic in bundle.topic_segments:
+            for sent in topic.sentences:
+                cleaned = self.clean_content(sent)
+                if cleaned and len(cleaned.split()) >= 5:
+                    sentences.append(cleaned)
+                if len(sentences) >= 3:
+                    break
+            if len(sentences) >= 3:
+                break
+        if sentences:
+            paragraphs.append(" ".join(sentences))
+            return paragraphs
+
+        if clean_atoms:
+            ranked = sorted(clean_atoms, key=lambda a: a.confidence, reverse=True)
+            overview_parts = [
+                self.clean_content(a.content) for a in ranked[:3] if self.clean_content(a.content)
+            ]
+            if overview_parts:
+                paragraphs.append(" ".join(overview_parts))
+                return paragraphs
+
+        return ["No reliable overview could be extracted from this video's captions."]
+
+    # ── Executive Summary (keeps "stands out in" for tests) ────────
+
+    def _build_executive_summary(self, bundle: Any, clean_atoms: list) -> list[str]:
+        atoms_by_topic: dict[str, list] = defaultdict(list)
+        for atom in clean_atoms:
+            topic_key = self._topic_key_from_path(atom.topic_path)
+            atoms_by_topic[topic_key].append(atom)
+
+        summary_lines: list[str] = []
+        topic_order = [(t.id, t.title) for t in bundle.topic_segments]
+        for topic_key, topic_name in topic_order:
+            atoms = atoms_by_topic.get(topic_key, [])
+            if not atoms:
+                continue
+            ranked = sorted(
+                atoms,
+                key=lambda a: (
+                    self._atom_priority(a.atom_type),
+                    self._atom_specificity(a),
+                    self._atom_summary_rank(a),
+                    a.confidence,
+                ),
+                reverse=True,
+            )
+            if self._topic_is_generic_only(ranked):
+                continue
+            used: set[str] = set()
+            max_items = 2 if self._topic_supports_dense_summary(ranked) else 1
+            added = 0
+            for atom in ranked:
+                key = str(atom.content).casefold()
+                if key in used:
+                    continue
+                if self._should_skip_summary_atom(atom, ranked):
+                    continue
+                used.add(key)
+                summary_lines.append(self._summary_sentence(topic_name, atom))
+                added += 1
+                if len(summary_lines) >= 5 or added >= max_items:
+                    break
+            if len(summary_lines) >= 5:
+                break
+        return summary_lines
+
+    # ── Legacy helpers (kept for test compatibility) ───────────────
+
+    @staticmethod
+    def _topic_key_from_path(topic_path: list) -> str:
+        if len(topic_path) >= 2:
+            return str(topic_path[1])
+        if topic_path:
+            return str(topic_path[0])
+        return "Ungrouped"
+
+    @staticmethod
+    def _atom_priority(atom_type: str) -> int:
+        return {
+            "terminal_command": 5,
+            "configuration_snippet": 4,
+            "core_concept": 3,
+            "best_practice": 2,
+            "workflow_step": 1,
+            "code_block": 4,
+            "command_sequence": 5,
+        }.get(atom_type, 0)
+
+    @staticmethod
+    def _atom_specificity(atom: Any) -> int:
+        return len(str(atom.content).split())
+
+    @staticmethod
+    def _atom_summary_rank(atom: Any) -> int:
+        generic = {"claude code", "terminal", "pattern", "patterns"}
+        if atom.atom_type == "core_concept" and str(atom.content).casefold() in generic:
+            return 0
+        return 1
+
+    def _topic_supports_dense_summary(self, ranked: list) -> bool:
+        specific = [
+            a for a in ranked if a.atom_type == "core_concept" and self._atom_summary_rank(a) > 0
+        ]
+        return len(specific) >= 2
+
+    def _topic_is_generic_only(self, ranked: list) -> bool:
+        if not ranked:
+            return True
+        return all(
+            a.atom_type == "core_concept" and self._atom_summary_rank(a) == 0 for a in ranked
+        )
+
+    def _should_skip_summary_atom(self, atom: Any, ranked: list) -> bool:
+        if atom.atom_type != "core_concept":
+            return False
+        if self._atom_summary_rank(atom) > 0:
+            return False
+        return any(
+            o.atom_type == "core_concept" and self._atom_summary_rank(o) > 0 for o in ranked
+        )
+
+    def _summary_sentence(self, topic_name: str, atom: Any) -> str:
+        if atom.atom_type in {"terminal_command", "configuration_snippet"}:
+            return f"`{atom.content}` is used in {topic_name}."
+        if atom.atom_type == "core_concept":
+            return f"{atom.content} is covered in {topic_name}."
+        return f"{atom.content} is discussed in {topic_name}."
+
+    @staticmethod
+    def _display_explanation(atom: Any) -> str:
+        if (
+            atom.atom_type == "core_concept"
+            and atom.explanation
+            == "Important Claude Code workflow concept mentioned in the transcript."
+        ):
+            return "highlighted as an important Claude Code concept."
+        return atom.explanation
+
+    @staticmethod
+    def _group_atoms(atoms: list) -> dict[str, list]:
+        types = [
+            "terminal_command",
+            "configuration_snippet",
+            "core_concept",
+            "workflow_step",
+            "best_practice",
+            "code_block",
+            "command_sequence",
+        ]
+        return {t: [a for a in atoms if a.atom_type == t] for t in types}
+
+    @staticmethod
+    def _append_group(
+        lines: list[str], title: str, atoms: list, *, formatter: Any
+    ) -> None:
+        if not atoms:
+            return
+        lines.append(f"## {title}")
+        lines.append("")
+        seen: set[str] = set()
+        for atom in atoms:
+            rendered = formatter(atom)
+            if rendered in seen:
+                continue
+            seen.add(rendered)
+            lines.append(rendered)
+        lines.append("")

ytk/renderers/obsidian_renderer.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from ytk.renderers.markdown_renderer import MarkdownRenderer
+
+_YAML_SPECIAL_RE = re.compile(r"[:#&*!|>%@`]")
+
+
+def _escape_yaml_string(value: str) -> str:
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+    escaped = escaped.replace("\n", " ")
+    return escaped
+
+
+class ObsidianRenderer:
+    """Render an ExtractionBundle as an Obsidian-flavoured Markdown note."""
+
+    SECTION_TITLES: dict[str, str] = {
+        "terminal_command": "## ⌨️ Commands",
+        "best_practice": "## ✅ Best Practices",
+        "configuration_snippet": "## ⚙️ Configuration",
+        "workflow_step": "## 📋 Workflow Steps",
+        "core_concept": "## 💡 Core Concepts",
+        "code_block": "## 📦 Code Blocks",
+        "command_sequence": "## 🔗 Command Sequences",
+    }
+
+    def render(self, bundle: Any, output_path: Path, **kwargs: Any) -> None:
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        video_url = bundle.metadata.get(
+            "canonical_url",
+            f"https://www.youtube.com/watch?v={bundle.video_id}",
+        )
+        raw_title = bundle.metadata.get("title", bundle.video_id)
+        safe_title = _escape_yaml_string(str(raw_title))
+
+        clean_atoms = [
+            a
+            for a in bundle.knowledge_atoms
+            if not MarkdownRenderer._is_garbage(a, source=bundle.transcript_source)
+        ]
+
+        lines: list[str] = []
+
+        # ── YAML frontmatter ───────────────────────────────────
+        lines.append("---")
+        lines.append(f'title: "{safe_title}"')
+        lines.append(f"video_id: {bundle.video_id}")
+        if bundle.metadata.get("canonical_url"):
+            lines.append(f"url: {bundle.metadata['canonical_url']}")
+
+        all_tags: set[str] = set()
+        for atom in clean_atoms:
+            for topic in atom.topic_path:
+                tag = MarkdownRenderer.clean_tag(topic)
+                if tag:
+                    all_tags.add(tag)
+        if all_tags:
+            lines.append("tags:")
+            for tag in sorted(all_tags):
+                lines.append(f"  - {tag}")
+        lines.append("---")
+        lines.append("")
+
+        # ── Header ─────────────────────────────────────────────
+        lines.append(f"# {raw_title}")
+        lines.append("")
+        lines.append(f"> 📺 [Watch on YouTube]({video_url})")
+        caption_note = (
+            "Extracted from auto-generated captions"
+            if bundle.transcript_source in ("auto", "asr")
+            else "Extracted from manual captions"
+        )
+        lines.append(f"> 🕐 {caption_note}")
+        lines.append("")
+        lines.append("---")
+        lines.append("")
+
+        if not clean_atoms:
+            lines.append("> ⚠️ No reliable knowledge atoms could be extracted from this video's captions.")
+            lines.append("")
+
+        # ── Grouped sections by atom type ──────────────────────
+        by_type: dict[str, list] = {}
+        for atom in clean_atoms:
+            by_type.setdefault(atom.atom_type, []).append(atom)
+
+        for atom_type, title in self.SECTION_TITLES.items():
+            atoms = by_type.get(atom_type, [])
+            if not atoms:
+                continue
+            lines.append(title)
+            lines.append("")
+            for atom in atoms:
+                self._render_atom(lines, atom, bundle, video_url)
+            lines.append("")
+
+        # ── Workflow tips as callouts ──────────────────────────
+        workflow_atoms = by_type.get("workflow_step", [])
+        if workflow_atoms:
+            lines.append("## 📋 Workflow Tips")
+            lines.append("")
+            for i, atom in enumerate(workflow_atoms, 1):
+                content = MarkdownRenderer.clean_content(atom.content)
+                if not content:
+                    continue
+                lines.append(f"> [!tip] Step {i}: {content}")
+                if atom.explanation:
+                    lines.append(f"> {atom.explanation}")
+                for ts in atom.timestamps:
+                    m, s = divmod(int(ts), 60)
+                    lines.append(f"> [{m:02d}:{s:02d}]({video_url}&t={int(ts)}s)")
+                lines.append("")
+
+        output_path.write_text("\n".join(lines), encoding="utf-8")
+
+    def _render_atom(
+        self, lines: list[str], atom: Any, bundle: Any, video_url: str
+    ) -> None:
+        if atom.atom_type == "core_concept":
+            lines.append(f"- **[[{atom.content}]]** — {atom.explanation}")
+        elif atom.atom_type == "terminal_command":
+            lines.append(f"- `{atom.content}` — {atom.explanation}")
+        else:
+            lines.append(f"- {atom.content}")
+            if atom.explanation:
+                lines.append(f"  > {atom.explanation}")
+
+        for ts in atom.timestamps[:3]:
+            m, s = divmod(int(ts), 60)
+            lines.append(f"  — [{m:02d}:{s:02d}]({video_url}&t={int(ts)}s)")
+        if len(atom.timestamps) > 3:
+            lines.append(f"  — *+{len(atom.timestamps) - 3} more timestamps*")
+        lines.append("")