kd-engine 1.0.0__py3-none-any.whl

ytk/renderers/knowledge_doc_renderer.py

@@ -0,0 +1,1984 @@
+"""Render an ExtractionBundle as a single, structured knowledge document.
+
+Unlike the other renderers (which produce a multi-file bundle: obsidian note,
+markdown notes, summary, skill package, JSON), this renderer asks MiniMax to
+rewrite the raw transcript into ONE polished markdown file. It targets the
+"give me a single, clean, knowledge document" workflow: no skill package
+scaffolding, no per-atom JSON, no per-section files. Just the distilled
+knowledge in the reader's preferred language.
+
+Output: a single .md file with overview, core concepts, workflows, code
+samples, configuration, and timestamp-anchored citations. Filler words
+("uh", "so", "you know", ...) are removed, fragmented segments are merged,
+and the document is written in the configured language (Chinese or English).
+
+Language selection (in priority order):
+  1. Explicit ``YTK_DOC_LANGUAGE`` env var ("zh" or "en")
+  2. The user's shell locale ($LANG / $LC_ALL / $LC_MESSAGES, sampled for
+     "zh" or "en")
+  3. Default: "zh" (preserves v1.0.0 behavior for existing users)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import math
+import os
+import re
+import tempfile
+import threading
+import time
+from collections.abc import Callable
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, ClassVar, Literal, TypedDict
+
+import httpx
+
+from ytk.config import AppSettings
+from ytk.renderers.citation_alignment import (
+    CitationAlignmentError,
+    validate_citation_alignment,
+)
+
+logger = logging.getLogger(__name__)
+
+DocLanguage = Literal["zh", "en"]
+
+
+class _ProgressBusy(RuntimeError):
+    """Another process currently owns this output's model dispatch."""
+
+
+def complete_doc_status(output_dir: Path) -> bool:
+    """Check the status and exact knowledge.md bytes before reporting completion."""
+    try:
+        status = json.loads((output_dir / ".knowledge-doc-status.json").read_text(encoding="utf-8"))
+        output = output_dir / "knowledge.md"
+        return (status.get("schema") == 1 and status.get("state") == "COMPLETE"
+                and status.get("output_file") == output.name
+                and status.get("output_sha256") == hashlib.sha256(output.read_bytes()).hexdigest())
+    except (OSError, UnicodeError, ValueError, AttributeError, TypeError):
+        return False
+
+
+class _SectionLabels(TypedDict):
+    """Localization labels for one output language."""
+
+    title_template: str
+    source: str
+    overview: str
+    no_transcript: str
+    topic_segments: str
+    knowledge_atoms: str
+    type_titles: dict[str, str]
+    full_transcript: str
+    overview_separator: str
+
+
+# Mirror ytk.ingestion.providers.minimax._BASE_URLS so this renderer targets
+# the same backend the configured region was issued for.
+_MINIMAX_BASE_URLS: dict[str, str] = {
+    "cn": "https://api.minimaxi.com",
+    "global": "https://api.minimax.io",
+}
+
+# Same regex as ytk.ingestion.providers.minimax._THINK_RE so the leading
+# `<think>...</think>` block the model emits in thinking mode is stripped
+# before we write the document to disk.
+_THINK_RE = re.compile(r"(?is)^\s*<think\b.*?</think\s*>\s*")
+
+
+_PROMPT_TEMPLATES: dict[str, str] = {
+    "zh": """你是知识整理助手。下面是一个 YouTube 教程的转录（带时间戳，格式 `{ts_format} 文本`）。请把它改写成一篇干净、结构化、**中文**知识文档，直接保存为 markdown 文件使用。
+
+# 视频元数据
+- 标题: {title}
+- URL: {url}
+- 时长: {duration} 秒
+
+# 转录（带时间戳）
+{transcript}
+
+# 要求
+1. **必须用中文输出**（专有名词如产品名、API、命令保留英文原文）。**专有名词必须逐字沿用转录里的原始拼写**（产品名、模型名、游戏名、数据集名、人名、API、命令、URL），转录怎么写就怎么写；**严禁**用同领域更知名的缩写或同类术语去"纠正"、"归一"或"补全"它（反例：转录里的 `Jev` 不得改写成 `JEPA`，转录里的 `howlight` 不得"更正"成别的游戏名）。拼写存疑时保留转录原样，并在该名词后用括号标注 `（拼写依转录）`，不要自行替换。
+2. **去口语化**：删除 "uh", "so", "you know", "ok", "right", "alright", "well", "I mean", "like", "basically", "let's go ahead and", "you know what", "kinda", "sort of" 等填充词和口头禅
+3. **整合碎片**：把同一主题的多个片段合并成连贯段落；不要按时间顺序罗列，要按主题组织
+4. **结构化**：使用以下 sections（按需保留相关 sections，去掉空 sections）：
+   - `# 概述`（一段话总结视频讲什么、为什么重要）
+   - `## 核心概念`（关键技术名词 + 简短解释）
+   - `## 工作流程`（步骤化、清晰的指令，去掉所有口语）
+   - `## 代码与命令`（具体可执行的内容，标注 `bash` 代码块）
+   - `## 配置与设置`（配置文件、参数）
+   - `## 关键时间点`（标注 `{citation_format}` 时间戳，方便回看，列 5-10 个最重要的时刻）
+5. **不引入视频外的内容**——只整理视频里讲的
+6. **不使用 emoji**
+7. 引用关键事实时附 `{citation_format}` 时间戳，**写在括号内**而不是塞在句子里
+8. 全文使用中文标点（，。；：）而非英文标点
+9. 文档长度 1500-4000 中文字
+10. **直接输出 markdown**，不要加前言（如"以下是..."），不要加元评论
+11. {hour_rule}
+
+# 输出格式
+直接以 `# 概述` 开头。
+""",
+    "en": """You are a knowledge-curation assistant. Below is the transcript of a YouTube tutorial with timestamps in `{ts_format}` format. Please rewrite it into a clean, structured, **English** knowledge document, ready to be saved as a markdown file.
+
+# Video metadata
+- Title: {title}
+- URL: {url}
+- Duration: {duration} seconds
+
+# Transcript (with timestamps)
+{transcript}
+
+# Requirements
+1. **Output MUST be in English** (keep product names, APIs, and commands in their original English form). **Preserve every proper noun exactly as spelled in the transcript** (product, model, game, dataset, and people names, APIs, commands, URLs). **Never** "correct", normalize, or expand a name into a more famous acronym or a similar term from the same field (counter-example: `Jev` in the transcript must NOT become `JEPA`). When the spelling is unclear, keep the transcript's form and append `(spelling per transcript)`.
+2. **Remove filler words**: drop "uh", "so", "you know", "ok", "right", "alright", "well", "I mean", "like", "basically", "let's go ahead and", "you know what", "kinda", "sort of", and similar verbal tics
+3. **Merge fragments**: combine multiple segments on the same topic into coherent paragraphs; organize by topic, not chronologically
+4. **Structure**: use the following sections (keep relevant ones, drop empty ones):
+   - `# Overview` (one paragraph: what the video covers and why it matters)
+   - `## Core Concepts` (key technical terms + short explanations)
+   - `## Workflow` (step-by-step instructions, no spoken-language fluff)
+   - `## Code & Commands` (concrete runnable content, marked with `bash` code blocks)
+   - `## Configuration` (config files, parameters)
+   - `## Key Moments` (annotate `{citation_format}` timestamps so the reader can jump back, list 5-10 most important moments)
+5. **Do not introduce content from outside the video** — only reorganize what was said
+6. **No emoji**
+7. When citing key facts, attach `{citation_format}` timestamps in parentheses, not inline in the sentence
+8. Use English punctuation (.,;:)
+9. Document length 1500-4000 English words
+10. **Output the markdown directly** — no preamble (e.g. "Below is..."), no meta-commentary
+11. {hour_rule}
+
+# Output format
+Start directly with `# Overview`.
+""",
+}
+
+
+_HOUR_RULE_ZH_SHORT = (
+    "时间戳引证统一使用 `[mm:ss]` 格式（本视频不足 1 小时，无需小时位）"
+)
+_HOUR_RULE_ZH_LONG = (
+    "**时间戳硬约束：本视频时长超过 1 小时，所有时间戳引证必须写成 `[h:mm:ss]` 全局格式"
+    "（必须含小时位），严禁丢掉小时位（反例：把 1:02:01 写成 02:01）；"
+    "输出前逐一自查每条时间戳都带小时位且为视频全局时间**"
+)
+_HOUR_RULE_EN_SHORT = (
+    "Cite timestamps as `[mm:ss]` (this video is under one hour; no hour component needed)"
+)
+_HOUR_RULE_EN_LONG = (
+    "**Hard timestamp rule: this video is longer than one hour, so every timestamp citation "
+    "must be written as a global `[h:mm:ss]` timestamp (hour component mandatory). Never drop "
+    "the hour (counter-example: 1:02:01 written as 02:01); self-check every timestamp before "
+    "finishing**"
+)
+
+
+# ---------------------------------------------------------------------------
+# Reviewer-scaffolding block
+#
+# When the CLI is invoked with `--with-reviewer-scaffolding`, the renderer
+# appends a deterministic footer to the knowledge doc so that downstream
+# reviewers (multi-model 4-rubric scoring) see:
+#   1. An A/B/C source list. A-class and C-class entries are populated from
+#      real bundle metadata (the source video URL is both the primary source
+#      and the project-experience source). B-class is an explicitly-marked
+#      empty placeholder, because the extractor cannot know which community
+#      sources a human editor will judge relevant.
+#   2. A generic image-asset manifest template (cover / mindmap / flowchart /
+#      code image). The content column is a placeholder slot, NOT a
+#      topic-specific description — the extractor does not know the video's
+#      subject, so it must not invent one (e.g. it must not claim a "four
+#      primitives" cover for a cooking video).
+#   3. A closing CTA that points the reader at the doc body (which always
+#      exists) rather than at a named section that may or may not be emitted
+#      by the LLM/fallback path.
+#
+# Content is bilingual-ready via the ``language`` arg (zh / en). The builder
+# is a pure function of (language, title, source_url) — no LLM call, no
+# datetime, no random — so reviewer scores are reproducible across runs.
+# ---------------------------------------------------------------------------
+
+# Marker used in the B-class list and the image-manifest content slots to
+# make it visually obvious to a human editor (and to a downstream reviewer)
+# that the slot is a template waiting to be populated, not real evidence.
+_PLACEHOLDER_MARKER_ZH = "_(发布前请补充)_"  # noqa: RUF001 - intentional wide underscore
+_PLACEHOLDER_MARKER_EN = "_(populate before publishing)_"
+
+
+def _a_class_entries_zh(title: str, source_url: str) -> str:
+    """A-class: the source video is itself a primary source. Always non-empty."""
+    label = title.strip() or "源视频"
+    url = source_url.strip() or "_(源 URL 缺失)_"
+    return f"- [{label}]({url}) — 视频本身就是一手素材（讲解者亲自演示）"
+
+
+def _a_class_entries_en(title: str, source_url: str) -> str:
+    label = title.strip() or "Source video"
+    url = source_url.strip() or "_(source URL missing)_"
+    return f"- [{label}]({url}) — the video itself is the primary material (presenter's own demo)"
+
+
+def _c_class_entries_zh(source_url: str) -> str:
+    """C-class: the video's demos ARE project experience. Always non-empty."""
+    url = source_url.strip()
+    if not url:
+        return "- _(源 URL 缺失)_ — 视频里呈现的实战演示属于 C 类（项目经验），可按时间戳标记"
+    # Use a descriptive label (not the bare URL) so the link renders cleanly
+    # even if the URL contains markdown-significant characters.
+    return f"- [视频作者的实战演示（C 类项目经验）]({url}) — 可按时间戳标记"
+
+
+def _c_class_entries_en(source_url: str) -> str:
+    url = source_url.strip()
+    if not url:
+        return "- _(source URL missing)_ — demos shown in the video are C-class (project experience); tag with timestamps"
+    return f"- [Presenter's live demo (C-class project experience)]({url}) — tag with timestamps"
+
+
+# The image manifest is intentionally generic. Each row's "content" column is
+# a placeholder slot (the renderer does not know the video's subject), and the
+# "renderer" column names the tool that would produce that asset type. A human
+# editor (or a downstream image pipeline) replaces the placeholder text with
+# topic-specific descriptions before publishing.
+_IMAGE_MANIFEST_ROWS_ZH = (
+    "| 1 | `00-cover.png` | {_ph} 封面图 | drawio MCP / PIL |",
+    "| 2 | `01-mindmap-overview.png` | {_ph} 核心概念思维导图 | drawio MCP |",
+    "| 3 | `02-flowchart.png` | {_ph} 关键工作流图 | mmdc |",
+    "| 4 | `03-code-snippet.png` | {_ph} 关键代码或命令截图（若适用） | freeze + PIL |",
+)
+_IMAGE_MANIFEST_ROWS_EN = (
+    "| 1 | `00-cover.png` | {_ph} cover art | drawio MCP / PIL |",
+    "| 2 | `01-mindmap-overview.png` | {_ph} mindmap of core concepts | drawio MCP |",
+    "| 3 | `02-flowchart.png` | {_ph} key workflow diagram | mmdc |",
+    "| 4 | `03-code-snippet.png` | {_ph} key code/command screenshot (if applicable) | freeze + PIL |",
+)
+
+
+def _image_manifest_zh() -> str:
+    rows = "\n".join(row.format(_ph=_PLACEHOLDER_MARKER_ZH) for row in _IMAGE_MANIFEST_ROWS_ZH)
+    return "| # | 文件 | 内容 | 渲染方式 |\n| --- | --- | --- | --- |\n" + rows
+
+
+def _image_manifest_en() -> str:
+    rows = "\n".join(row.format(_ph=_PLACEHOLDER_MARKER_EN) for row in _IMAGE_MANIFEST_ROWS_EN)
+    return "| # | File | Content | Renderer |\n| --- | --- | --- | --- |\n" + rows
+
+
+_CTA_BODY_ZH = (
+    "1. 回到本文开头的概述，用一句话向同事复述这篇文档解决什么问题。\n"
+    "2. 从正文中挑一条最具体的命令或概念，在本地照做一次，记录实际输出。\n"
+    "3. 把你照做时遇到的偏差（命令不存在、参数变了、结果不一致）写回这份文档的复盘区。\n\n"
+    "完成这三步，这份文档就从『读过的』变成『跑通的』。\n"
+)
+_CTA_BODY_EN = (
+    "1. Re-read the overview at the top and explain in one sentence what this doc solves.\n"
+    "2. Pick the most concrete command or concept in the body, run it locally, and record the actual output.\n"
+    "3. Write any deviation you hit (missing command, changed flag, mismatched result) back into this doc.\n\n"
+    "After these three steps the doc has gone from 'read' to 'run'.\n"
+)
+
+
+def build_reviewer_scaffolding(
+    language: DocLanguage,
+    *,
+    title: str = "",
+    source_url: str = "",
+) -> str:
+    """Return the reviewer-scaffolding footer for the given language.
+
+    The footer is appended to the rendered knowledge doc. It is a pure
+    function of (language, title, source_url) — no LLM call, no datetime,
+    no random — so reviewer scoring is reproducible across runs.
+
+    Real metadata (``title``, ``source_url``) populates the A-class and
+    C-class source entries. B-class and image-manifest content slots are
+    explicitly-marked placeholders, because the extractor cannot know which
+    community sources a human editor will judge relevant, nor the video's
+    subject matter.
+    """
+    # Treat anything that is not explicitly "en" as Chinese (the documented
+    # default — matches detect_doc_language's fallback). This preserves the
+    # contract that unknown / "auto" / None → zh.
+    is_zh = language != "en"
+    parts: list[str] = []
+    # Leading blank line separates the footer from the body.
+    parts.append("")
+
+    # --- A / B / C source list ---
+    if is_zh:
+        parts.append("## 参考来源（A / B / C 三类）")
+        parts.append("视频本身就是一手素材；下列清单按来源可信度分三类，B 类由人工补充：")
+    else:
+        parts.append("## References (A / B / C classes)")
+        parts.append("The video itself is primary material; the list below splits sources by credibility. B-class is populated by a human editor:")
+    parts.append("")
+
+    if is_zh:
+        parts.append("### A 类：官方 / 一手")
+        parts.append(_a_class_entries_zh(title, source_url))
+        parts.append("")
+        parts.append("### B 类：社区 / 开源")
+        parts.append(f"- {_PLACEHOLDER_MARKER_ZH} 视频提到的第三方仓库、博文或工具链接")
+        parts.append("")
+        parts.append("### C 类：项目经验（视频作者演示）")
+        parts.append(_c_class_entries_zh(source_url))
+    else:
+        parts.append("### A class: Official / primary")
+        parts.append(_a_class_entries_en(title, source_url))
+        parts.append("")
+        parts.append("### B class: Community / OSS")
+        parts.append(f"- {_PLACEHOLDER_MARKER_EN} third-party repos, blog posts, or tools mentioned in the video")
+        parts.append("")
+        parts.append("### C class: Project experience (presenter's demo)")
+        parts.append(_c_class_entries_en(source_url))
+    parts.append("")
+
+    # --- Image-asset manifest (generic template) ---
+    if is_zh:
+        parts.append("## 配套图示（模板）")
+        parts.append("下列图示为通用模板，发布前请把「内容」列的占位符替换为本视频的具体描述：")
+        parts.append("")
+        parts.append(_image_manifest_zh())
+    else:
+        parts.append("## Companion visuals (template)")
+        parts.append("The visual plan below is a generic template; replace the Content-column placeholders with this video's specifics before publishing:")
+        parts.append("")
+        parts.append(_image_manifest_en())
+    parts.append("")
+
+    # --- Closing CTA (references the body, not a named section) ---
+    if is_zh:
+        parts.append("## 现在就开始")
+        parts.append(_CTA_BODY_ZH)
+    else:
+        parts.append("## Get started now")
+        parts.append(_CTA_BODY_EN)
+
+    return "\n".join(parts) + "\n"
+
+
+_SECTION_TITLES: dict[str, _SectionLabels] = {
+    "zh": {
+        "title_template": "# {title}",
+        "source": "来源：{url}",
+        "overview": "## 概述",
+        "no_transcript": "（无转录内容）",
+        "topic_segments": "## 主题分段",
+        "knowledge_atoms": "## 提取的知识要点",
+        "type_titles": {
+            "core_concept": "核心概念",
+            "workflow_step": "工作流程",
+            "terminal_command": "命令",
+            "command_sequence": "命令序列",
+            "configuration_snippet": "配置",
+            "code_block": "代码块",
+            "best_practice": "最佳实践",
+        },
+        "full_transcript": "## 完整转录（去填充词）",
+        "overview_separator": "",
+    },
+    "en": {
+        "title_template": "# {title}",
+        "source": "Source: {url}",
+        "overview": "## Overview",
+        "no_transcript": "(no transcript content)",
+        "topic_segments": "## Topic Segments",
+        "knowledge_atoms": "## Extracted Knowledge Atoms",
+        "type_titles": {
+            "core_concept": "Core Concepts",
+            "workflow_step": "Workflow Steps",
+            "terminal_command": "Commands",
+            "command_sequence": "Command Sequences",
+            "configuration_snippet": "Configuration",
+            "code_block": "Code Blocks",
+            "best_practice": "Best Practices",
+        },
+        "full_transcript": "## Full Transcript (filler words removed)",
+        "overview_separator": "",
+    },
+}
+
+
+_TIMESTAMP_HEAD_RE = re.compile(r"^\[(\d{1,2}:\d{1,2}(?::\d{1,2})?)\]")
+
+
+def _transcript_has_hour_anchor(transcript: str) -> bool:
+    """True when any transcript line is anchored at >=1h (the `[h:mm:ss]`
+    contract's single decision point)."""
+    for line in transcript.splitlines():
+        match = _TIMESTAMP_HEAD_RE.match(line.strip())
+        if not match:
+            continue
+        parts = [int(p) for p in match.group(1).split(":")]
+        seconds = (
+            parts[0] * 3600 + parts[1] * 60 + parts[2]
+            if len(parts) == 3
+            else parts[0] * 60 + parts[1]
+        )
+        if seconds >= 3600:
+            return True
+    return False
+
+
+def _citation_format(expect_hours: bool) -> str:
+    return "[h:mm:ss]" if expect_hours else "[mm:ss]"
+
+
+def _fmt_ts(seconds: float) -> str:
+    """Format seconds as [mm:ss] (or [h:mm:ss] for >1h)."""
+    total = int(seconds)
+    h, rem = divmod(total, 3600)
+    m, s = divmod(rem, 60)
+    if h > 0:
+        return f"{h}:{m:02d}:{s:02d}"
+    return f"{m:02d}:{s:02d}"
+
+
+# ---------------------------------------------------------------------------
+# Chunked rendering (roadmap 2026-10-06 §3.1.3)
+#
+# A >=1h transcript no longer goes through one MiniMax call (the 10/04
+# kLZgQWjnUz0 single call hit the 16K-token output cap and dropped every
+# hour component). Chunk boundary rule, locked by Q14c: real video chapters
+# when available, fixed time windows otherwise. Embedding-derived topic
+# blocks are never chunk boundaries (their boundary quality is unstable —
+# the 10/04 final embedding block spanned 133s→14916s).
+# ---------------------------------------------------------------------------
+
+CHUNK_WINDOW_SECONDS = 1800.0  # 30-minute fixed windows when no chapters
+BOUNDED_CHUNK_CHARS = 12000  # rendered transcript characters, not tokens
+UNBOUND_BOUNDED_PLANNER = "bounded-transcript-v1"
+BOUNDED_PLANNER = "bounded-transcript-v2"
+
+
+@dataclass(frozen=True)
+class ChunkWindow:
+    start: float
+    end: float
+    title: str
+
+
+def valid_chapter_list(chapters: list | None) -> list[dict]:
+    """Normalize chapter dicts to usable {start,end,title} windows.
+
+    Idempotent: accepts both the raw yt-dlp spelling (start_time/end_time)
+    and its own output (start/end), so a caller that already validated the
+    list can pass it straight through (2026-10-06 review: the list was
+    computed twice with two independent code paths)."""
+    valid: list[dict] = []
+    for chapter in chapters or []:
+        if not isinstance(chapter, dict):
+            continue
+        start = chapter.get("start_time", chapter.get("start"))
+        end = chapter.get("end_time", chapter.get("end"))
+        title = chapter.get("title")
+        if (
+            not isinstance(start, int | float)
+            or not isinstance(end, int | float)
+            or not isinstance(title, str)
+        ):
+            continue
+        if start < 0 or end <= start:
+            continue
+        valid.append({"start": float(start), "end": float(end), "title": title})
+    return valid
+
+
+def _generic_window_title(index: int, start: float, end: float, is_zh: bool) -> str:
+    if is_zh:
+        return f"第 {index} 段（{_fmt_ts(start)}–{_fmt_ts(end)}）"
+    return f"Part {index} ({_fmt_ts(start)}–{_fmt_ts(end)})"
+
+
+def plan_chunk_windows(
+    chapters: list | None,
+    max_time: float,
+    *,
+    window_seconds: float = CHUNK_WINDOW_SECONDS,
+    language: str = "zh",
+) -> list[ChunkWindow]:
+    """Tile [0, max_time] with render windows: chapters when usable, else
+    fixed windows of ``window_seconds``. Windows never gap or overlap, so
+    every transcript segment lands in exactly one chunk (last segment at the
+    final boundary rides the last window)."""
+    is_zh = language != "en"
+    max_time = float(max_time)
+    valid = valid_chapter_list(chapters)
+    starts = sorted(
+        {c["start"] for c in valid if c["start"] < max_time}
+    )
+    if starts:
+        if starts[0] > 0:
+            starts.insert(0, 0.0)
+        title_by_start = {c["start"]: c["title"].strip() for c in valid}
+        windows: list[ChunkWindow] = []
+        for index, start in enumerate(starts):
+            end = starts[index + 1] if index + 1 < len(starts) else max(max_time, start + 1.0)
+            title = title_by_start.get(start) or _generic_window_title(
+                index + 1, start, end, is_zh
+            )
+            windows.append(ChunkWindow(start=start, end=end, title=title))
+        return windows
+
+    total = max(1, math.ceil(max_time / window_seconds)) if max_time > 0 else 1
+    return [
+        ChunkWindow(
+            start=i * window_seconds,
+            end=(i + 1) * window_seconds,
+            title=_generic_window_title(i + 1, i * window_seconds, (i + 1) * window_seconds, is_zh),
+        )
+        for i in range(total)
+    ]
+
+
+def _dedupe_titles(titles: list[str], is_zh: bool) -> list[str]:
+    """Give duplicate headings a unique numeric suffix so the assembled doc
+    has no duplicated section headings."""
+    seen: dict[str, int] = {}
+    out: list[str] = []
+    for title in titles:
+        count = seen.get(title, 0) + 1
+        seen[title] = count
+        if count == 1:
+            out.append(title)
+        elif is_zh:
+            out.append(f"{title}（{count}）")
+        else:
+            out.append(f"{title} ({count})")
+    return out
+
+
+_HEADING_RE = re.compile(r"^(#{1,6})\s+(.*?)\s*$")
+
+
+def _normalize_chunk_content(
+    content: str,
+    expected_title: str,
+    emitted_headings: set[str],
+) -> str:
+    """Normalize one chunk's LLM output to start with its ``## expected_title``
+    heading: keep a matching heading, drop one that duplicates an already
+    emitted heading (seam duplication), otherwise prepend the heading."""
+    lines = content.strip().splitlines()
+    first_idx = next((i for i, line in enumerate(lines) if line.strip()), None)
+    if first_idx is not None:
+        match = _HEADING_RE.match(lines[first_idx].strip())
+        if match:
+            heading_text = match.group(2).strip()
+            if heading_text == expected_title:
+                emitted_headings.add(expected_title)
+                return "\n".join(lines).strip()
+            if heading_text in emitted_headings:
+                # Seam duplication: drop the echoed heading, fall through to
+                # prepend the chunk's own heading.
+                del lines[first_idx]
+            else:
+                # Unexpected heading: keep it below the expected heading.
+                lines.insert(first_idx, f"## {expected_title}")
+                emitted_headings.add(expected_title)
+                return "\n".join(lines).strip()
+    emitted_headings.add(expected_title)
+    return "\n".join([f"## {expected_title}", *lines]).strip()
+
+
+def assemble_chunked_doc(
+    *,
+    title: str,
+    url: str,
+    windows: list[ChunkWindow],
+    contents: list[str],
+    language: str,
+    boundary_source: str,
+    citation_format: str,
+    final_titles: list[str] | None = None,
+) -> str:
+    """Assemble validated chunk outputs into one knowledge document with a
+    deterministic overview map and a machine-readable provenance comment."""
+    is_zh = language != "en"
+    labels = _SECTION_TITLES[language]
+    if final_titles is None:
+        final_titles = _dedupe_titles([w.title for w in windows], is_zh)
+    parts: list[str] = [labels["title_template"].format(title=title), ""]
+    if url:
+        parts += [labels["source"].format(url=url), ""]
+    parts += [
+        (
+            f"<!-- ytk-knowledge-doc: chunked; boundary={boundary_source}; "
+            f"chunks={len(windows)}; citation_format={citation_format} -->"
+        ),
+        "",
+        labels["overview"],
+        "",
+    ]
+    # strict=False on both zips below: final_titles/contents are caller contracts
+    # (1:1 with windows at every in-repo call site); strict=True would raise on a
+    # length mismatch where the previous code truncated.
+    for window, final_title in zip(windows, final_titles, strict=False):
+        if is_zh:
+            parts.append(f"- {final_title}（{_fmt_ts(window.start)}–{_fmt_ts(window.end)}）")
+        else:
+            parts.append(f"- {final_title} ({_fmt_ts(window.start)}–{_fmt_ts(window.end)})")
+    parts.append("")
+    emitted: set[str] = set()
+    for _window, final_title, content in zip(windows, final_titles, contents, strict=False):
+        parts.append(
+            _normalize_chunk_content(content, final_title, emitted)
+        )
+        parts.append("")
+    return "\n".join(parts).rstrip()
+
+
+def _strip_leading_heading(content: str) -> str:
+    lines = content.strip().splitlines()
+    first_idx = next((i for i, line in enumerate(lines) if line.strip()), None)
+    if first_idx is not None and _HEADING_RE.match(lines[first_idx].strip()):
+        del lines[first_idx]
+    return "\n".join(lines)
+
+
+def verify_chunk_assembly(
+    assembled: str,
+    windows: list[ChunkWindow],
+    contents: list[str],
+    *,
+    language: str = "zh",
+    final_titles: list[str] | None = None,
+) -> list[str]:
+    """Seam-consistency check (acceptance §3.1 ⑤): every chunk body must
+    appear exactly once and every expected heading exactly once.
+
+    ``final_titles`` lets a caller that already de-duplicated the headings
+    hand the SAME list to assembler and verifier — recomputing it here
+    would let the two drift (the check would then validate headings that
+    were never written; 2026-10-06 review finding)."""
+    is_zh = language != "en"
+    if final_titles is None:
+        final_titles = _dedupe_titles([w.title for w in windows], is_zh)
+    problems: list[str] = []
+    # strict=False: a caller-supplied final_titles may be shorter than contents;
+    # the verifier must report the gap as a problem instead of raising.
+    for index, (content, final_title) in enumerate(
+        zip(contents, final_titles, strict=False), start=1
+    ):
+        body = _strip_leading_heading(content).strip()
+        if not body:
+            problems.append(f"chunk {index} ({final_title}): empty content")
+            continue
+        occurrences = assembled.count(body)
+        if occurrences == 0:
+            problems.append(f"chunk {index} ({final_title}): content missing from assembled doc")
+        elif occurrences > 1:
+            problems.append(
+                f"chunk {index} ({final_title}): content duplicated {occurrences}x"
+            )
+        heading = f"## {final_title}"
+        heading_count = len(
+            re.findall(f"^{re.escape(heading)}$", assembled, flags=re.MULTILINE)
+        )
+        if heading_count != 1:
+            problems.append(
+                f"chunk {index}: heading '{heading}' present {heading_count}x (expected 1)"
+            )
+    return problems
+
+
+def detect_doc_language(explicit: str | None = None) -> DocLanguage:
+    """Resolve the doc output language.
+
+    Resolution order (highest priority first):
+      1. ``explicit`` argument (typically the ``YTK_DOC_LANGUAGE`` env var
+         value, or a constructor argument the CLI passed in).
+      2. Shell locale: $LC_MESSAGES → $LC_ALL → $LANG. If any of these
+         contains "zh" we return "zh"; if it contains "en" we return "en".
+         (Locale strings look like ``zh_CN.UTF-8`` or ``en_US.UTF-8``.)
+      3. Default: "zh" (preserves v1.0.0 behavior for existing users).
+
+    Only the canonical codes "zh" and "en" are accepted. Any other explicit
+    value is logged and treated as "auto" (fall through to locale probing).
+    """
+    if explicit:
+        candidate = explicit.strip().lower()
+        if candidate in ("zh", "en"):
+            return candidate  # type: ignore[return-value]
+        if candidate != "auto":
+            logger.warning(
+                "YTK_DOC_LANGUAGE=%r is not one of {zh, en, auto}; ignoring.",
+                explicit,
+            )
+
+    for env_var in ("LC_MESSAGES", "LC_ALL", "LANG"):
+        value = os.environ.get(env_var, "")
+        if not value:
+            continue
+        normalized = value.lower().replace("-", "_")
+        if normalized.startswith("zh"):
+            return "zh"
+        if normalized.startswith("en"):
+            return "en"
+    return "zh"
+
+
+
+# ---------------------------------------------------------------------------
+# v2 knowledge-doc extension (T33.3)
+#
+# The v1 path above stays byte-identical.  v2 bundles are planned from their
+# ContentBundle blocks instead of raw-transcript.json:
+#   * video      -> time-range blocks become (start, text) segments and reuse
+#                   the existing bounded time chunker unchanged;
+#   * image_note -> blocks are grouped in reading order under the same
+#                   character budget, with no block dropped or duplicated, and
+#                   citations use 图 N / 第 N 段 (never a timestamp, A22).
+# Prompt classification (tutorial / general knowledge / image note) is applied
+# through ``_classification_suffix``; with no v2 render in flight it returns ""
+# so every v1 prompt and checkpoint stays byte-identical.
+# ---------------------------------------------------------------------------
+
+IMAGE_NOTE_PLANNER = "image-note-chunk-v1"
+
+#: Atom types that make a source actionable enough to drive a tutorial doc.
+ACTIONABLE_ATOM_TYPES: frozenset[str] = frozenset(
+    {
+        "terminal_command",
+        "command_sequence",
+        "configuration_snippet",
+        "code_block",
+        "workflow_step",
+    }
+)
+
+DocKind = Literal["tutorial", "general", "image_note"]
+
+_IMAGE_CITATION_FORMAT: dict[str, str] = {
+    "zh": "[图 N] / [第 N 段]",
+    "en": "[Image N] / [Paragraph N]",
+}
+
+_IMAGE_NOTE_TEMPLATES: dict[str, str] = {
+    "zh": """你是知识整理助手。下面是一篇**图文笔记**（来自小红书等平台）的内容块，按原帖阅读顺序排列，每块以定位标记开头（格式 `[图 N]` 或 `[第 N 段]`）。请把它改写成一篇干净、结构化的**中文**知识文档，直接保存为 markdown 文件使用。
+
+# 笔记元数据
+- 标题: {title}
+- URL: {url}
+
+# 内容块（按原帖顺序）
+{blocks}
+
+# 要求
+1. **必须用中文输出**（专有名词保留原文）。
+2. 按图片与正文的原始顺序组织内容，不要打乱图片顺序。
+3. 引用内容时使用 `{citation_format}` 形式的定位标记，写在括号内；**禁止出现任何时间戳**（图文没有时间轴）。
+4. 不引入笔记之外的内容；没有操作步骤时不要编造步骤。
+5. 不使用 emoji；直接输出 markdown，不要加前言。
+
+# 输出格式
+直接以 `# 概述` 开头。
+""",
+    "en": """You are a knowledge-curation assistant. Below is an **image note** (e.g. a Xiaohongshu post) given as content blocks in the original reading order; each block starts with its locator marker (`[Image N]` or `[Paragraph N]`). Rewrite it into a clean, structured **English** markdown knowledge document.
+
+# Note metadata
+- Title: {title}
+- URL: {url}
+
+# Content blocks (original order)
+{blocks}
+
+# Requirements
+1. **Output MUST be in English** (keep proper nouns as written).
+2. Keep the original image/paragraph order; never reorder images.
+3. Cite with `{citation_format}` locator markers in parentheses; **never emit a timestamp** (an image note has no timeline).
+4. Do not introduce content from outside the note; never invent steps when none exist.
+5. No emoji; output markdown directly with no preamble.
+
+# Output format
+Start directly with `# Overview`.
+""",
+}
+
+
+@dataclass(frozen=True)
+class V2DocSource:
+    """Normalized v2 input for the knowledge-doc renderer."""
+
+    kind: Literal["video", "image_note"]
+    blocks: list[Any]
+    segments: list[tuple[float, str]]
+    metadata: dict[str, Any]
+    primary: Any = None
+    content: Any = None
+
+
+@dataclass(frozen=True)
+class ImageNoteChunk:
+    """One bounded image-note plan unit (blocks keep their reading order)."""
+
+    index: int
+    block_ids: tuple[str, ...]
+    lines: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class _VideoDocShim:
+    """Minimal v1-compatible view for the existing LLM doc pipeline."""
+
+    metadata: dict[str, Any]
+    video_id: str
+
+
+def is_v2_bundle(bundle: Any) -> bool:
+    """True for an :class:`ExtractionBundleV2` (v2 render path)."""
+    from ytk.models.content import ExtractionBundleV2
+
+    return isinstance(bundle, ExtractionBundleV2)
+
+
+def classify_doc_kind(bundle: Any) -> DocKind:
+    """Classify the source for prompt selection: tutorial / general / image note."""
+    content_types = {
+        content.source.content_type for content in getattr(bundle, "contents", [])
+    }
+    if "image_note" in content_types:
+        return "image_note"
+    atom_types = {atom.atom_type for atom in getattr(bundle, "knowledge", [])}
+    if atom_types & ACTIONABLE_ATOM_TYPES:
+        return "tutorial"
+    return "general"
+
+
+def image_note_block_line(block: Any, *, language: str = "zh") -> str:
+    """One image-note block as ``[图 N] text`` / ``[第 N 段] text``."""
+    from ytk.renderers.source_links import readable_locator
+
+    text = (block.cleaned_text or block.raw_text).strip()
+    marker = readable_locator(block.locator, language=language)
+    return f"[{marker}] {text}" if marker else text
+
+
+def plan_image_note_chunks(
+    blocks: list[Any], *, max_chars: int = BOUNDED_CHUNK_CHARS, language: str = "zh"
+) -> list[ImageNoteChunk]:
+    """Group image-note blocks in order under a character budget.
+
+    Blocks are never split, dropped or duplicated: every input block lands in
+    exactly one chunk, in its original order.  A single block larger than the
+    budget fails *before* any paid dispatch (same contract as the transcript
+    planner).
+    """
+    chunks: list[ImageNoteChunk] = []
+    current_ids: list[str] = []
+    current_lines: list[str] = []
+    size = 0
+    for block in blocks:
+        line = image_note_block_line(block, language=language)
+        if len(line) > max_chars:
+            raise RuntimeError("an image-note block exceeds the bounded chunk size")
+        if current_lines and size + len(line) + 1 > max_chars:
+            chunks.append(
+                ImageNoteChunk(len(chunks) + 1, tuple(current_ids), tuple(current_lines))
+            )
+            current_ids, current_lines, size = [], [], 0
+        current_ids.append(block.block_id)
+        current_lines.append(line)
+        size += len(line) + 1
+    if current_lines:
+        chunks.append(ImageNoteChunk(len(chunks) + 1, tuple(current_ids), tuple(current_lines)))
+    return chunks
+
+
+def verify_image_note_plan(chunks: list[ImageNoteChunk], blocks: list[Any]) -> list[str]:
+    """Check the plan covers every block exactly once, in order."""
+    problems: list[str] = []
+    planned = [block_id for chunk in chunks for block_id in chunk.block_ids]
+    expected = [block.block_id for block in blocks]
+    if planned != expected:
+        problems.append(
+            f"image-note plan covers blocks {planned!r}, expected {expected!r} "
+            "(dropped, duplicated or reordered blocks)"
+        )
+    return problems
+
+
+def _image_chunk_title(index: int, language: str) -> str:
+    if language == "en":
+        return f"Part {index}"
+    return f"第 {index} 部分"
+
+
+def assemble_image_note_doc(
+    *,
+    title: str,
+    url: str,
+    chunks: list[ImageNoteChunk],
+    contents: list[str],
+    language: str,
+    final_titles: list[str] | None = None,
+) -> str:
+    """Assemble validated image-note chunk outputs (no timestamps anywhere)."""
+    is_zh = language != "en"
+    labels = _SECTION_TITLES[language]
+    if final_titles is None:
+        final_titles = _dedupe_titles(
+            [_image_chunk_title(chunk.index, language) for chunk in chunks], is_zh
+        )
+    parts: list[str] = [labels["title_template"].format(title=title), ""]
+    if url:
+        parts += [labels["source"].format(url=url), ""]
+    parts += [
+        (
+            f"<!-- ytk-knowledge-doc: image-note; chunks={len(chunks)}; "
+            f"citation_format={_IMAGE_CITATION_FORMAT[language]} -->"
+        ),
+        "",
+        labels["overview"],
+        "",
+    ]
+    # strict=False: final_titles/contents are caller contracts (1:1 with chunks at
+    # every in-repo call site); strict=True would raise where the previous code
+    # truncated.
+    for chunk, final_title in zip(chunks, final_titles, strict=False):
+        if is_zh:
+            parts.append(f"- {final_title}（{len(chunk.block_ids)} 个内容块）")
+        else:
+            parts.append(f"- {final_title} ({len(chunk.block_ids)} content blocks)")
+    parts.append("")
+    emitted: set[str] = set()
+    for final_title, content in zip(final_titles, contents, strict=False):
+        parts.append(_normalize_chunk_content(content, final_title, emitted))
+        parts.append("")
+    return "\n".join(parts).rstrip()
+
+
+class KnowledgeDocRenderer:
+    """Rewrite a transcript into a single knowledge document via MiniMax.
+
+    Output language is selectable (zh/en). See module docstring for the
+    resolution order.
+    """
+
+    SUPPORTED_LANGUAGES: ClassVar[tuple[str, ...]] = ("zh", "en")
+
+    def __init__(self, language: str | None = None, *, settings: AppSettings | None = None) -> None:
+        self._api_key: str | None = settings.minimax_api_key if settings is not None else os.environ.get("YTK_MINIMAX_API_KEY") or None
+        self._region: str = settings.minimax_region if settings is not None else os.environ.get("YTK_MINIMAX_REGION", "cn")
+        self._model: str = settings.minimax_model if settings is not None else os.environ.get("YTK_MINIMAX_MODEL", "MiniMax-M3")
+        self._base_url: str = _MINIMAX_BASE_URLS.get(self._region, _MINIMAX_BASE_URLS["cn"])
+        self._timeout: float = settings.knowledge_doc_timeout if settings is not None else float(os.environ.get("YTK_KNOWLEDGE_DOC_TIMEOUT", "300.0"))
+        self._total_timeout: float = float(os.environ.get("YTK_KNOWLEDGE_DOC_TOTAL_TIMEOUT", "1200.0"))
+        if not math.isfinite(self._total_timeout) or self._total_timeout <= 0:
+            raise ValueError("YTK_KNOWLEDGE_DOC_TOTAL_TIMEOUT must be positive and finite")
+        self._checkpoint_path: Path | None = None
+        self._deadline: float | None = None
+        self._doc_kind: DocKind | None = None
+        self._instance_lock = threading.Lock()
+        # Allow longer outputs than the ingestion path — the knowledge doc is
+        # often the only artifact the user keeps, so trimming it hurts.
+        self._max_tokens: int = settings.knowledge_doc_max_tokens if settings is not None else int(os.environ.get("YTK_KNOWLEDGE_DOC_MAX_TOKENS", "16384"))
+        # Resolve language: explicit ctor arg wins; otherwise YTK_DOC_LANGUAGE
+        # env var, otherwise locale probe, otherwise "zh".
+        explicit_env = settings.doc_language if settings is not None else os.environ.get("YTK_DOC_LANGUAGE")
+        self._language: DocLanguage = detect_doc_language(language or explicit_env)
+
+    @property
+    def language(self) -> DocLanguage:
+        """Return the resolved output language (zh or en)."""
+        return self._language
+
+    def render(self, bundle: Any, output_path: Path, **kwargs: Any) -> None:
+        if not self._instance_lock.acquire(blocking=False):
+            raise _ProgressBusy("knowledge-doc renderer is already in use")
+        try:
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            self._checkpoint_path = output_path.parent / ".knowledge-doc-progress.json"
+            with self._progress_lock(self._checkpoint_path):
+                self._render_locked(bundle, output_path, **kwargs)
+        finally:
+            self._instance_lock.release()
+
+    def _render_locked(self, bundle: Any, output_path: Path, **kwargs: Any) -> None:
+        status_path = output_path.parent / ".knowledge-doc-status.json"
+        self._write_progress(status_path, {"schema": 1, "state": "RUNNING"})
+        if is_v2_bundle(bundle):
+            self._render_locked_v2(bundle, output_path, status_path, **kwargs)
+            return
+        segments = self._load_transcript_segments(output_path.parent / "raw-transcript.json")
+        # Build the transcript text ONCE (it was re-parsed from disk up to
+        # three times per render — 2026-10-06 review finding).
+        transcript = self._transcript_text(segments)
+        reason: str | None = None
+        if not self._api_key:
+            # No LLM key — fall back to a deterministic, no-fluff document
+            # built from the raw transcript and the bundle's existing
+            # knowledge atoms. Useful for offline demos / fixture runs.
+            logger.warning(
+                "YTK_MINIMAX_API_KEY not set; KnowledgeDocRenderer is falling back "
+                "to a deterministic document built from the raw transcript. "
+                "Set YTK_MINIMAX_API_KEY in .env for the LLM-rewritten version."
+            )
+            content = self._fallback_doc(bundle, transcript)
+            reason = "NO_API_KEY"
+        else:
+            try:
+                content = self._render_llm_document(bundle, segments)
+            except RuntimeError as exc:
+                # LLM failure OR citation-alignment failure: the deterministic
+                # fallback keeps the doc usable, and the warning keeps the
+                # degradation non-silent (roadmap §3.1.2: misaligned LLM
+                # output must never land as-is).
+                logger.warning(
+                    "MiniMax knowledge-doc rewrite rejected; falling back to the "
+                    "deterministic document: %s",
+                    exc,
+                )
+                content = self._fallback_doc(bundle, transcript)
+                message = str(exc)
+                if message == "knowledge-doc total time budget exhausted":
+                    reason = "TOTAL_TIMEOUT"
+                elif message == "knowledge-doc chunk has an unresolved or invalid prior dispatch":
+                    reason = "UNRESOLVED_OR_INVALID_DISPATCH"
+                elif message == "knowledge-doc progress cannot be safely reused":
+                    reason = "PROGRESS_MISMATCH"
+                else:
+                    reason = "REWRITE_FAILED"
+                try:
+                    checkpoint_path = self._checkpoint_path
+                    if checkpoint_path is None:  # defensive: no checkpoint on this path
+                        raise OSError("knowledge-doc checkpoint path is not configured")
+                    progress = json.loads(checkpoint_path.read_text(encoding="utf-8"))
+                    chunks = progress.get("chunks", [])
+                    if isinstance(chunks, list) and chunks and isinstance(chunks[-1], dict) and chunks[-1].get("state") == "DISPATCHING":
+                        reason = "TOTAL_TIMEOUT_WITH_UNRESOLVED_DISPATCH" if reason == "TOTAL_TIMEOUT" else "UNRESOLVED_OR_INVALID_DISPATCH"
+                except (OSError, ValueError, TypeError, AttributeError):
+                    pass
+            finally:
+                self._deadline = None
+
+        if kwargs.get("with_reviewer_scaffolding"):
+            # Pull real metadata from the bundle so A-class and C-class source
+            # entries are actual citations (the source video URL), not
+            # placeholder text. B-class and the image manifest stay as
+            # explicitly-marked template slots.
+            metadata = getattr(bundle, "metadata", None) or {}
+            title = str(metadata.get("title", "") or "")
+            source_url = str(metadata.get("canonical_url", "") or "")
+            content = (
+                content.rstrip()
+                + "\n"
+                + build_reviewer_scaffolding(
+                    self._language,
+                    title=title,
+                    source_url=source_url,
+                )
+            )
+
+        if reason:
+            content = f"<!-- ytk-knowledge-doc: fallback; reason={reason} -->\n\n" + content
+        rendered = content.strip() + "\n"
+        destination = output_path
+        if reason and output_path.exists():
+            destination = output_path.with_name(output_path.stem + ".fallback" + output_path.suffix)
+        self._write_text_atomic(destination, rendered)
+        self._write_progress(status_path, {"schema": 1, "state": "FALLBACK" if reason else "COMPLETE",
+                                          "reason": reason, "output_file": destination.name,
+                                          "output_sha256": hashlib.sha256(rendered.encode()).hexdigest()})
+
+    def _fallback_doc(self, bundle: Any, transcript: str) -> str:
+        """Build a deterministic knowledge document without LLM.
+
+        Strips common fillers from the raw transcript, lists each topic
+        segment with its first sentence, and dumps the surviving knowledge
+        atoms grouped by type. This is a degraded mode — the LLM-rewritten
+        path produces a far better document, but this fallback keeps
+        `ytk extract --format doc` working in offline / fixture scenarios
+        where no API key is available.
+
+        Output language follows ``self._language``.
+        """
+        labels = _SECTION_TITLES[self._language]
+        title = str(bundle.metadata.get("title", bundle.video_id))
+        url = str(bundle.metadata.get("canonical_url", ""))
+
+        filler_re = re.compile(
+            r"\b(?:uh+|um+|ah+|er+|hmm|"
+            r"so|so basically|basically|"
+            r"you know|i mean|like|"
+            r"right|alright|okay|ok|"
+            r"well|honestly|literally|"
+            r"kinda|sort of|"
+            r"and then|so then|"
+            r"let's go ahead and|now let's)\b[,]?",
+            re.IGNORECASE,
+        )
+
+        cleaned_lines: list[str] = []
+        for line in transcript.splitlines():
+            stripped = filler_re.sub("", line).strip()
+            stripped = re.sub(r"\s{2,}", " ", stripped)
+            # Strip leading/trailing punctuation left over from filler removal.
+            stripped = re.sub(r"^[\s,.;:]+", "", stripped)
+            stripped = re.sub(r"[\s,.;:]+$", "", stripped)
+            if stripped:
+                cleaned_lines.append(stripped)
+
+        sections: list[str] = [labels["title_template"].format(title=title), ""]
+        if url:
+            sections.append(labels["source"].format(url=url))
+            sections.append("")
+
+        sections.append(labels["overview"])
+        sections.append("")
+        overview = " ".join(cleaned_lines[:3]).strip() or labels["no_transcript"]
+        sections.append(overview)
+        sections.append("")
+
+        if bundle.topic_segments:
+            sections.append(labels["topic_segments"])
+            sections.append("")
+            for topic in bundle.topic_segments:
+                first_sentence = topic.sentences[0] if topic.sentences else ""
+                sections.append(
+                    f"- `{topic.title}` ({topic.start:.0f}s-{topic.end:.0f}s)"
+                    + (f" — {first_sentence}" if first_sentence else "")
+                )
+            sections.append("")
+
+        if bundle.knowledge_atoms:
+            sections.append(labels["knowledge_atoms"])
+            sections.append("")
+            by_type: dict[str, list] = {}
+            for atom in bundle.knowledge_atoms:
+                by_type.setdefault(atom.atom_type, []).append(atom)
+            for atom_type, atoms in by_type.items():
+                localized = labels["type_titles"].get(atom_type, atom_type)
+                sections.append(f"### {localized}")
+                sections.append("")
+                for atom in atoms:
+                    evidence = atom.evidence[0] if atom.evidence else None
+                    cite = (
+                        f" `[{_fmt_ts(evidence.start)}]`"
+                        if evidence is not None
+                        else ""
+                    )
+                    sections.append(f"- {atom.content}{cite}")
+                sections.append("")
+
+        sections.append(labels["full_transcript"])
+        sections.append("")
+        sections.extend(cleaned_lines)
+
+        return "\n".join(sections)
+
+    @staticmethod
+    def _load_transcript_segments(raw_path: Path) -> list[tuple[float, str]]:
+        """Load raw-transcript.json as (start_seconds, text) pairs."""
+        if not raw_path.exists():
+            logger.warning("raw-transcript.json not found at %s; emitting empty doc", raw_path)
+            return []
+        try:
+            payload = json.loads(raw_path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            logger.warning("Failed to parse raw-transcript.json: %s", exc)
+            return []
+        segments = payload.get("segments") if isinstance(payload, dict) else payload
+        if not isinstance(segments, list):
+            return []
+        loaded: list[tuple[float, str]] = []
+        for seg in segments:
+            if not isinstance(seg, dict):
+                continue
+            text = str(seg.get("text", "")).strip()
+            if not text:
+                continue
+            loaded.append((float(seg.get("start", 0.0)), text))
+        return loaded
+
+    @staticmethod
+    def _transcript_text(segments: list[tuple[float, str]]) -> str:
+        """Render loaded segments as `[mm:ss] text` lines. Timestamps use
+        `_fmt_ts`, so transcripts of >=1h videos already carry `[h:mm:ss]`
+        anchors regardless of the prompt format contract."""
+        return "\n".join(
+            f"[{_fmt_ts(start)}] {text}" for start, text in segments
+        )
+
+    @classmethod
+    def _load_transcript(cls, raw_path: Path) -> str:
+        """Concatenate raw-transcript.json segments with timestamp prefixes."""
+        return cls._transcript_text(cls._load_transcript_segments(raw_path))
+
+    def _build_prompt(
+        self, bundle: Any, transcript: str, *, expect_hours: bool | None = None
+    ) -> str:
+        title = str(bundle.metadata.get("title", bundle.video_id))
+        url = str(bundle.metadata.get("canonical_url", ""))
+        duration = bundle.metadata.get("duration")
+        if duration is None:
+            # fall back to last segment end if available
+            duration = "未知" if self._language == "zh" else "unknown"
+        # Dynamic citation format (roadmap §3.1.1): >=1h videos cite [h:mm:ss].
+        # Single source of truth for the decision (the transcript's own
+        # `_fmt_ts` anchors are authoritative; metadata duration is the
+        # hint). The render path already computed it from the segments and
+        # passes it in so the two can never disagree.
+        if expect_hours is None:
+            expect_hours = _transcript_has_hour_anchor(transcript)
+        citation_format = _citation_format(expect_hours)
+        if self._language == "zh":
+            hour_rule = _HOUR_RULE_ZH_LONG if expect_hours else _HOUR_RULE_ZH_SHORT
+        else:
+            hour_rule = _HOUR_RULE_EN_LONG if expect_hours else _HOUR_RULE_EN_SHORT
+        template = _PROMPT_TEMPLATES[self._language]
+        prompt = template.format(
+            title=title,
+            url=url,
+            duration=duration,
+            transcript=transcript,
+            ts_format=citation_format,
+            citation_format=citation_format,
+            hour_rule=hour_rule,
+        )
+        # v2 prompt classification; "" for every v1 render, so existing
+        # prompts and checkpoints stay byte-identical.
+        return prompt + self._classification_suffix()
+
+    def _chunk_scope_block(
+        self, index: int, total: int, window: ChunkWindow, citation_format: str
+    ) -> str:
+        """Chunk framing appended to the base prompt: absolute global times
+        only, expected heading, and no document-level structure."""
+        span = f"{_fmt_ts(window.start)}–{_fmt_ts(window.end)}"
+        if self._language == "zh":
+            return (
+                f"\n\n# 本次改写范围（分段渲染 {index}/{total}）\n"
+                f"- 本段标题：{window.title}\n"
+                f"- 本段范围：{span}（视频全局时间）\n"
+                f"- 只改写本段转录内容；**所有时间戳引证必须使用视频全局时间"
+                f"（不是段内相对时间），格式 {citation_format}**\n"
+                f"- 输出以 `## {window.title}` 小节标题开头，直接写正文；"
+                f"不要输出 `# 概述` 等文档级结构，不要重复视频标题，"
+                f"不要写其他段的内容"
+            )
+        return (
+            f"\n\n# Rewrite scope (chunked rendering {index}/{total})\n"
+            f"- Chunk title: {window.title}\n"
+            f"- Chunk span: {span} (global video time)\n"
+            f"- Rewrite THIS chunk's transcript only; **every timestamp citation "
+            f"must use global video time (not chunk-relative time), "
+            f"formatted {citation_format}**\n"
+            f"- Start your output with the `## {window.title}` heading and go "
+            f"straight into content; do NOT emit document-level structure like "
+            f"`# Overview`, do NOT repeat the video title, do NOT write other "
+            f"chunks' content"
+        )
+
+    def _render_llm_document(self, bundle: Any, segments: list[tuple[float, str]]) -> str:
+        """Plan bounded work before dispatch, preserving older durable plans."""
+        if not segments:
+            raise RuntimeError("empty transcript cannot be sent for knowledge-doc rewriting")
+        starts = [start for start, _ in segments]
+        max_start = max(starts) if starts else 0.0
+        duration = bundle.metadata.get("duration")
+        expect_hours = (
+            isinstance(duration, int | float) and duration >= 3600
+        ) or max_start >= 3600
+        # (passed to the prompt/chunk prompts so the format decision is made
+        # exactly once per render — see _build_prompt's expect_hours arg)
+
+        # Old progress files have no planner marker. Preserve their exact old
+        # prompts and checkpoint identity, including UNKNOWN dispatches; never
+        # turn a timeout into a fresh set of paid calls.
+        planner: str | None = BOUNDED_PLANNER
+        if self._checkpoint_path is not None and self._checkpoint_path.exists():
+            try:
+                old_progress = json.loads(self._checkpoint_path.read_text(encoding="utf-8"))
+                if not isinstance(old_progress, dict):
+                    raise ValueError("invalid progress")
+                planner = old_progress.get("planner")
+                if planner not in (None, UNBOUND_BOUNDED_PLANNER, BOUNDED_PLANNER):
+                    raise ValueError("unknown planner")
+            except (OSError, UnicodeError, ValueError, TypeError):
+                raise RuntimeError("knowledge-doc progress cannot be safely reused") from None
+
+        source_sha: str | None = None
+        if planner == BOUNDED_PLANNER:
+            try:
+                source = json.dumps(segments, ensure_ascii=False, allow_nan=False, separators=(",", ":"))
+            except (TypeError, ValueError):
+                raise RuntimeError("transcript segments cannot be safely bound") from None
+            source_sha = hashlib.sha256(source.encode("utf-8")).hexdigest()
+
+        transcript_chars = sum(len(f"[{_fmt_ts(start)}] {text}\n") for start, text in segments)
+        long_enough = (isinstance(duration, int | float) and duration >= CHUNK_WINDOW_SECONDS) or max_start >= CHUNK_WINDOW_SECONDS
+        should_chunk = expect_hours or (planner is not None and (long_enough or transcript_chars > BOUNDED_CHUNK_CHARS))
+        if should_chunk:
+            chapters = bundle.metadata.get("chapters")
+            chapters = chapters if isinstance(chapters, list) else None
+            return self._render_chunked(bundle, segments, chapters, expect_hours,
+                                        bounded=planner is not None, planner=planner, source_sha=source_sha)
+
+        transcript = "\n".join(f"[{_fmt_ts(start)}] {text}" for start, text in segments)
+        prompt = self._build_prompt(bundle, transcript, expect_hours=expect_hours)
+        return self._execute_rewrite_plan([prompt], [segments], expect_hours,
+                                          planner=planner, source_sha=source_sha)[0]
+
+    @staticmethod
+    @contextmanager
+    def _progress_lock(path: Path):
+        """Use an OS-held lock; process death releases it, the journal does not."""
+        lock_path = path.with_name(path.name + ".lock")
+        flags = os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0)
+        try:
+            fd = os.open(lock_path, flags, 0o600)
+        except OSError as exc:
+            raise _ProgressBusy("unable to open knowledge-doc progress lock") from exc
+        locked = False
+        try:
+            try:
+                if os.name == "nt":
+                    import msvcrt
+                    if os.fstat(fd).st_size == 0:
+                        os.write(fd, b"0")
+                    os.lseek(fd, 0, os.SEEK_SET)
+                    # typeshed ships an empty msvcrt stub off Windows; these two
+                    # calls only ever run when os.name == "nt".
+                    msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)  # type: ignore[attr-defined]
+                else:
+                    import fcntl
+                    fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                locked = True
+            except OSError as exc:
+                raise _ProgressBusy("knowledge-doc output is already being rendered") from exc
+            yield
+        finally:
+            if locked:
+                if os.name == "nt":
+                    import msvcrt
+                    os.lseek(fd, 0, os.SEEK_SET)
+                    msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)  # type: ignore[attr-defined]
+                else:
+                    import fcntl
+                    fcntl.flock(fd, fcntl.LOCK_UN)
+            os.close(fd)
+
+    @staticmethod
+    def _write_text_atomic(path: Path, content: str) -> None:
+        tmp_path: str | None = None
+        try:
+            with tempfile.NamedTemporaryFile(mode="w", encoding="utf-8", dir=path.parent,
+                                             prefix=".knowledge-doc-", delete=False) as tmp:
+                tmp_path = tmp.name
+                tmp.write(content)
+                tmp.flush()
+                os.fsync(tmp.fileno())
+            os.replace(tmp_path, path)
+            tmp_path = None
+            if os.name != "nt":
+                fd = os.open(path.parent, os.O_RDONLY)
+                try:
+                    os.fsync(fd)
+                finally:
+                    os.close(fd)
+        except OSError as exc:
+            raise RuntimeError("unable to persist knowledge-doc progress") from exc
+        finally:
+            if tmp_path is not None:
+                try:
+                    os.unlink(tmp_path)
+                except FileNotFoundError:
+                    pass
+
+    @classmethod
+    def _write_progress(cls, path: Path, progress: dict[str, Any]) -> None:
+        """Persist the dispatch intent before the paid call, and results afterwards."""
+        cls._write_text_atomic(path, json.dumps(progress, ensure_ascii=False))
+
+    def _execute_rewrite_plan(
+        self, prompts: list[str], line_buckets: list[list[tuple[float, str]]], expect_hours: bool,
+        planner: str | None = None, source_sha: str | None = None,
+        validator: Callable[[int, str, list[tuple[float, str]]], None] | None = None,
+    ) -> list[str]:
+        total = len(prompts)
+        plan = {"prompts": prompts, "model": self._model, "base_url": self._base_url,
+                "max_tokens": self._max_tokens}
+        if source_sha is not None:
+            plan["segment_source_sha256"] = source_sha
+        plan_sha = hashlib.sha256(json.dumps(plan, ensure_ascii=False, sort_keys=True).encode()).hexdigest()
+        path = self._checkpoint_path
+        progress: dict[str, Any] = {"schema": 1, "plan_sha256": plan_sha, "chunks": []}
+        if planner:
+            progress["planner"] = planner
+        if source_sha is not None:
+            progress["segment_source_sha256"] = source_sha
+        if path is not None and path.exists():
+            try:
+                progress = json.loads(path.read_text(encoding="utf-8"))
+                if (not isinstance(progress, dict) or progress.get("schema") != 1
+                        or progress.get("plan_sha256") != plan_sha
+                        or progress.get("planner") != planner
+                        or progress.get("segment_source_sha256") != source_sha
+                        or not isinstance(progress.get("chunks"), list)
+                        or len(progress["chunks"]) > total):
+                    raise ValueError("progress does not match current inputs")
+            except (OSError, UnicodeError, ValueError, TypeError) as exc:
+                raise RuntimeError("knowledge-doc progress cannot be safely reused") from exc
+
+        contents: list[str] = []
+        self._deadline = time.monotonic() + self._total_timeout
+        # strict=False: prompts and line_buckets are built in lockstep by every
+        # in-repo caller; strict=True would raise where the previous code truncated.
+        for index, (lines, prompt) in enumerate(
+            zip(line_buckets, prompts, strict=False), start=1
+        ):
+            entries = progress["chunks"]
+            prompt_sha = hashlib.sha256(prompt.encode()).hexdigest()
+            if index <= len(entries):
+                entry = entries[index - 1]
+                if (not isinstance(entry, dict) or entry.get("index") != index
+                        or entry.get("prompt_sha256") != prompt_sha
+                        or entry.get("state") != "COMPLETE"
+                        or not isinstance(entry.get("content"), str)
+                        or hashlib.sha256(entry["content"].encode()).hexdigest() != entry.get("content_sha256")):
+                    raise RuntimeError("knowledge-doc chunk has an unresolved or invalid prior dispatch")
+                raw = entry["content"]
+            else:
+                if time.monotonic() >= self._deadline:
+                    raise RuntimeError("knowledge-doc total time budget exhausted")
+                entries.append({"index": index, "prompt_sha256": prompt_sha, "state": "DISPATCHING"})
+                if path is not None:
+                    self._write_progress(path, progress)
+                raw = self._call_minimax(prompt)
+            if validator is not None:
+                # v2 image-note chunks are locator-based (图/段), not time-based;
+                # the caller supplies the locator-aware validator.
+                validator(index, raw, lines)
+            else:
+                # zyr: validate the chunk against ITS OWN window's segments —
+                # the full-video start list let any chunk's citation satisfy
+                # itself against a segment anywhere in a multi-hour video.
+                chunk_starts = [start for start, _ in lines]
+                report = validate_citation_alignment(
+                    raw, chunk_starts, expect_hours=expect_hours,
+                    require_citations=True,
+                    segment_texts=[text for _, text in lines])
+                if not report.ok:
+                    raise CitationAlignmentError(report)
+            if index == len(entries) and entries[index - 1].get("state") == "DISPATCHING":
+                entries[index - 1] = {"index": index, "prompt_sha256": prompt_sha, "state": "COMPLETE",
+                                      "content": raw, "content_sha256": hashlib.sha256(raw.encode()).hexdigest()}
+                if path is not None:
+                    self._write_progress(path, progress)
+            contents.append(raw)
+
+        return contents
+
+    def _render_chunked(
+        self,
+        bundle: Any,
+        segments: list[tuple[float, str]],
+        chapters: list | None,
+        expect_hours: bool,
+        *, bounded: bool = False, planner: str | None = None, source_sha: str | None = None,
+    ) -> str:
+        starts = [start for start, _ in segments]
+        max_time = max(starts) if starts else 0.0
+        usable_chapters = valid_chapter_list(chapters)
+        boundary_source = "chapter" if usable_chapters else "fixed_window"
+        planned = plan_chunk_windows(usable_chapters, max_time, language=self._language)
+
+        # Assign every segment to exactly one window (last-segment-at-final-
+        # boundary rides the last window).
+        assigned: list[tuple[ChunkWindow, list[tuple[float, str]]]] = [
+            (window, []) for window in planned
+        ]
+        for start, text in segments:
+            for window, bucket in assigned:
+                if window.start <= start < window.end:
+                    bucket.append((start, text))
+                    break
+            else:
+                assigned[-1][1].append((start, text))
+
+        if bounded:
+            # Keep real chapter boundaries and global timestamps. Split long
+            # chapter buckets by input size; additionally split sub-hour and
+            # single-chapter spans by time so a long sparse chapter does not
+            # become a single unbounded request. Segment text is never cut.
+            rebucketed: list[tuple[ChunkWindow, list[tuple[float, str]]]] = []
+            bound_time = not expect_hours or len(usable_chapters) <= 1
+            for window, lines in assigned:
+                groups: list[list[tuple[float, str]]] = []
+                group: list[tuple[float, str]] = []
+                size = 0
+                for start, text in lines:
+                    line_size = len(f"[{_fmt_ts(start)}] {text}\n")
+                    if line_size > BOUNDED_CHUNK_CHARS:
+                        raise RuntimeError("a transcript segment exceeds the bounded chunk size")
+                    if group and (size + line_size > BOUNDED_CHUNK_CHARS
+                                  or (bound_time and start - group[0][0] >= CHUNK_WINDOW_SECONDS)):
+                        groups.append(group)
+                        group, size = [], 0
+                    group.append((start, text))
+                    size += line_size
+                if group:
+                    groups.append(group)
+                for index, group in enumerate(groups):
+                    start = window.start if index == 0 else group[0][0]
+                    end = groups[index + 1][0][0] if index + 1 < len(groups) else window.end
+                    rebucketed.append((ChunkWindow(start, end, window.title), group))
+            assigned = rebucketed
+
+        rendered = [(window, lines) for window, lines in assigned if lines]
+        citation_format = _citation_format(expect_hours)
+        total = len(rendered)
+        prompts: list[str] = []
+        for index, (window, lines) in enumerate(rendered, start=1):
+            chunk_transcript = "\n".join(
+                f"[{_fmt_ts(start)}] {text}" for start, text in lines
+            )
+            prompts.append(self._build_prompt(
+                bundle, chunk_transcript, expect_hours=expect_hours
+            ) + self._chunk_scope_block(index, total, window, citation_format))
+
+        contents = self._execute_rewrite_plan(prompts, [lines for _, lines in rendered], expect_hours,
+                                              planner, source_sha)
+
+        windows = [window for window, _ in rendered]
+        final_titles = _dedupe_titles([w.title for w in windows], self._language != "en")
+        assembled = assemble_chunked_doc(
+            title=str(bundle.metadata.get("title", bundle.video_id)),
+            url=str(bundle.metadata.get("canonical_url", "")),
+            windows=windows,
+            contents=contents,
+            language=self._language,
+            boundary_source=boundary_source,
+            citation_format=citation_format,
+            final_titles=final_titles,
+        )
+        problems = verify_chunk_assembly(
+            assembled, windows, contents, language=self._language,
+            final_titles=final_titles,
+        )
+        if problems:
+            raise RuntimeError(
+                "chunk assembly consistency check failed: " + "; ".join(problems)
+            )
+        return assembled
+
+    # ------------------------------------------------------------------
+    # v2 path (T33.3) — additive; the v1 path above is untouched
+    # ------------------------------------------------------------------
+
+    def _classification_suffix(self) -> str:
+        """Prompt-classification note for v2 renders (empty for every v1 render)."""
+        kind = getattr(self, "_doc_kind", None)
+        if not kind or kind == "image_note":
+            # The image-note template already states "no timestamps"; adding a
+            # second note would only drift from it.
+            return ""
+        if self._language == "zh":
+            if kind == "tutorial":
+                return (
+                    "\n\n# 内容类型\n"
+                    "本内容是可操作教程：优先整理可执行步骤、命令与配置；步骤顺序不得打乱，"
+                    "没有依据的步骤不要补写。"
+                )
+            return (
+                "\n\n# 内容类型\n"
+                "本内容是通用知识：侧重概念、原理与结论；来源没有操作步骤时不要编造步骤。"
+            )
+        if kind == "tutorial":
+            return (
+                "\n\n# Content type\n"
+                "This source is an actionable tutorial: prioritise executable steps, commands "
+                "and configuration; keep step order and never invent missing steps."
+            )
+        return (
+            "\n\n# Content type\n"
+            "This source is general knowledge: focus on concepts, principles and conclusions; "
+            "do not invent steps the source does not contain."
+        )
+
+    def _v2_doc_source(self, bundle: Any, raw_transcript_path: Path) -> V2DocSource:
+        """Normalize a v2 bundle into blocks/segments (+ display metadata)."""
+        from ytk.models.content import TimeRangeLocator, VideoFrameLocator
+        from ytk.renderers.source_links import display_title
+
+        contents = list(getattr(bundle, "contents", []))
+        content = contents[0] if contents else None
+        primary = content.source if content is not None else None
+        metadata: dict[str, Any] = dict(getattr(bundle, "metadata", {}) or {})
+        title = metadata.get("title")
+        if not isinstance(title, str) or not title.strip():
+            title = display_title(primary) if primary is not None else "Knowledge"
+        metadata["title"] = title
+        if primary is not None:
+            metadata["canonical_url"] = primary.canonical_url
+            metadata.setdefault("content_type", primary.content_type)
+        blocks = list(content.blocks) if content is not None else []
+        blocks.sort(key=lambda block: (block.order, block.block_id))
+        is_image_note = primary is not None and primary.content_type == "image_note"
+        if is_image_note:
+            return V2DocSource(
+                kind="image_note",
+                blocks=blocks,
+                segments=[],
+                metadata=metadata,
+                primary=primary,
+                content=content,
+            )
+        segments: list[tuple[float, str]] = []
+        for block in blocks:
+            text = (block.cleaned_text or block.raw_text).strip()
+            if not text:
+                continue
+            locator = block.locator
+            if isinstance(locator, TimeRangeLocator):
+                segments.append((locator.time.start, text))
+            elif isinstance(locator, VideoFrameLocator):
+                segments.append((locator.time, text))
+        if content is not None and isinstance(content.metadata, dict):
+            duration = content.metadata.get("duration")
+            if isinstance(duration, int | float) and not isinstance(duration, bool):
+                metadata["duration"] = duration
+            chapters = content.metadata.get("chapters")
+            if isinstance(chapters, list):
+                metadata["chapters"] = chapters
+        if not segments:
+            segments = self._load_transcript_segments(raw_transcript_path)
+        return V2DocSource(
+            kind="video",
+            blocks=blocks,
+            segments=segments,
+            metadata=metadata,
+            primary=primary,
+            content=content,
+        )
+
+    def _render_locked_v2(
+        self, bundle: Any, output_path: Path, status_path: Path, **kwargs: Any
+    ) -> None:
+        """v2 branch of :meth:`_render_locked` (same journal/status contract)."""
+        source = self._v2_doc_source(bundle, output_path.parent / "raw-transcript.json")
+        reason: str | None = None
+        # Cloud text generation is opt-in (plan §4.6 / A25): the caller decides
+        # from the resolved platform settings; a local-only run must never POST
+        # the transcript to a cloud provider just because an API key is present.
+        allow_cloud = bool(kwargs.get("allow_cloud", True))
+        if not allow_cloud:
+            logger.warning(
+                "cloud text generation is disabled for this platform; falling back to the "
+                "deterministic v2 document (no network call)."
+            )
+            content = self._fallback_doc_v2(bundle, source)
+            reason = "CLOUD_TEXT_DISABLED"
+        elif not self._api_key:
+            logger.warning(
+                "YTK_MINIMAX_API_KEY not set; KnowledgeDocRenderer is falling back "
+                "to the deterministic v2 document."
+            )
+            content = self._fallback_doc_v2(bundle, source)
+            reason = "NO_API_KEY"
+        else:
+            try:
+                content = self._render_v2_document(bundle, source)
+            except RuntimeError as exc:
+                logger.warning(
+                    "MiniMax v2 knowledge-doc rewrite rejected; falling back to the "
+                    "deterministic document: %s",
+                    exc,
+                )
+                content = self._fallback_doc_v2(bundle, source)
+                reason = self._failure_reason(exc)
+            finally:
+                self._deadline = None
+                self._doc_kind = None
+
+        if kwargs.get("with_reviewer_scaffolding"):
+            metadata = source.metadata
+            content = content.rstrip() + "\n" + build_reviewer_scaffolding(
+                self._language,
+                title=str(metadata.get("title", "") or ""),
+                source_url=str(metadata.get("canonical_url", "") or ""),
+            )
+
+        if reason:
+            content = f"<!-- ytk-knowledge-doc: fallback; reason={reason} -->\n\n" + content
+        rendered = content.strip() + "\n"
+        destination = output_path
+        if reason and output_path.exists():
+            destination = output_path.with_name(output_path.stem + ".fallback" + output_path.suffix)
+        self._write_text_atomic(destination, rendered)
+        self._write_progress(
+            status_path,
+            {
+                "schema": 1,
+                "state": "FALLBACK" if reason else "COMPLETE",
+                "reason": reason,
+                "output_file": destination.name,
+                "output_sha256": hashlib.sha256(rendered.encode()).hexdigest(),
+            },
+        )
+
+    def _failure_reason(self, exc: RuntimeError) -> str:
+        """Map a v2 rewrite failure to the same reason codes as the v1 path."""
+        message = str(exc)
+        if message == "knowledge-doc total time budget exhausted":
+            reason = "TOTAL_TIMEOUT"
+        elif message == "knowledge-doc chunk has an unresolved or invalid prior dispatch":
+            reason = "UNRESOLVED_OR_INVALID_DISPATCH"
+        elif message == "knowledge-doc progress cannot be safely reused":
+            reason = "PROGRESS_MISMATCH"
+        else:
+            reason = "REWRITE_FAILED"
+        try:
+            checkpoint_path = self._checkpoint_path
+            if checkpoint_path is None:  # defensive: no checkpoint on this path
+                raise OSError("knowledge-doc checkpoint path is not configured")
+            progress = json.loads(checkpoint_path.read_text(encoding="utf-8"))
+            chunks = progress.get("chunks", [])
+            if (
+                isinstance(chunks, list)
+                and chunks
+                and isinstance(chunks[-1], dict)
+                and chunks[-1].get("state") == "DISPATCHING"
+            ):
+                reason = (
+                    "TOTAL_TIMEOUT_WITH_UNRESOLVED_DISPATCH"
+                    if reason == "TOTAL_TIMEOUT"
+                    else "UNRESOLVED_OR_INVALID_DISPATCH"
+                )
+        except (OSError, ValueError, TypeError, AttributeError):
+            pass
+        return reason
+
+    def _render_v2_document(self, bundle: Any, source: V2DocSource) -> str:
+        """Plan and rewrite a v2 source (video: time chunks; image note: blocks)."""
+        self._doc_kind = classify_doc_kind(bundle)
+        if source.kind == "image_note":
+            return self._render_v2_image_note(bundle, source)
+        shim = _VideoDocShim(
+            metadata=dict(source.metadata),
+            video_id=str(source.primary.content_id if source.primary is not None else "video"),
+        )
+        return self._render_llm_document(shim, source.segments)
+
+    def _render_v2_image_note(self, bundle: Any, source: V2DocSource) -> str:
+        """Bounded block-based rewrite for image notes (no timestamps)."""
+        from ytk.renderers.citation_alignment import validate_citation_alignment_v2
+
+        if not source.blocks:
+            raise RuntimeError("empty image note cannot be sent for knowledge-doc rewriting")
+        chunks = plan_image_note_chunks(source.blocks, language=self._language)
+        problems = verify_image_note_plan(chunks, source.blocks)
+        if problems:
+            raise RuntimeError("image-note chunk plan is inconsistent: " + "; ".join(problems))
+        source_sha = hashlib.sha256(
+            json.dumps(
+                [(chunk.block_ids, chunk.lines) for chunk in chunks],
+                ensure_ascii=False,
+                separators=(",", ":"),
+            ).encode("utf-8")
+        ).hexdigest()
+        total = len(chunks)
+        prompts = [
+            self._build_image_note_prompt(source.metadata, chunk, total) for chunk in chunks
+        ]
+        buckets: list[list[tuple[float, str]]] = [[] for _ in chunks]
+        block_ids_by_index = {chunk.index: set(chunk.block_ids) for chunk in chunks}
+        source_id = source.primary.source_id if source.primary is not None else None
+
+        def validate_chunk(index: int, raw: str, lines: list[tuple[float, str]]) -> None:
+            report = validate_citation_alignment_v2(
+                raw,
+                bundle,
+                source_id=source_id,
+                block_ids=block_ids_by_index.get(index),
+                require_citations=True,
+            )
+            if not report.ok:
+                raise CitationAlignmentError(report)
+
+        contents = self._execute_rewrite_plan(
+            prompts,
+            buckets,
+            False,
+            planner=IMAGE_NOTE_PLANNER,
+            source_sha=source_sha,
+            validator=validate_chunk,
+        )
+        final_titles = _dedupe_titles(
+            [_image_chunk_title(chunk.index, self._language) for chunk in chunks],
+            self._language != "en",
+        )
+        assembled = assemble_image_note_doc(
+            title=str(source.metadata.get("title") or "Image note"),
+            url=str(source.metadata.get("canonical_url") or ""),
+            chunks=chunks,
+            contents=contents,
+            language=self._language,
+            final_titles=final_titles,
+        )
+        window_shims = [ChunkWindow(0.0, 0.0, title) for title in final_titles]
+        problems = verify_chunk_assembly(
+            assembled,
+            window_shims,
+            contents,
+            language=self._language,
+            final_titles=final_titles,
+        )
+        if problems:
+            raise RuntimeError(
+                "image-note assembly consistency check failed: " + "; ".join(problems)
+            )
+        return assembled
+
+    def _build_image_note_prompt(
+        self, metadata: dict[str, Any], chunk: ImageNoteChunk, total: int
+    ) -> str:
+        template = _IMAGE_NOTE_TEMPLATES[self._language]
+        citation_format = _IMAGE_CITATION_FORMAT[self._language]
+        title = str(metadata.get("title") or "Image note")
+        url = str(metadata.get("canonical_url") or "")
+        prompt = template.format(
+            title=title,
+            url=url or ("（无）" if self._language == "zh" else "(none)"),
+            blocks="\n".join(chunk.lines),
+            citation_format=citation_format,
+        )
+        return prompt + self._image_chunk_scope_block(chunk, total, citation_format)
+
+    def _image_chunk_scope_block(
+        self, chunk: ImageNoteChunk, total: int, citation_format: str
+    ) -> str:
+        title = _image_chunk_title(chunk.index, self._language)
+        if self._language == "zh":
+            return (
+                f"\n\n# 本次改写范围（图文分块 {chunk.index}/{total}）\n"
+                f"- 本部分标题：{title}\n"
+                f"- 只改写本部分内容块；引用使用 {citation_format} 定位标记\n"
+                f"- **禁止出现任何时间戳**（图文没有时间轴）\n"
+                f"- 输出以 `## {title}` 开头，直接写正文；不要输出 `# 概述` 等文档级结构，"
+                f"不要写其他部分的内容"
+            )
+        return (
+            f"\n\n# Rewrite scope (image-note chunk {chunk.index}/{total})\n"
+            f"- Chunk title: {title}\n"
+            f"- Rewrite THIS chunk's blocks only; cite with {citation_format} locator markers\n"
+            f"- **Never emit a timestamp** (an image note has no timeline)\n"
+            f"- Start your output with the `## {title}` heading and go straight into content; "
+            f"do NOT emit document-level structure like `# Overview`, do NOT write other "
+            f"chunks' content"
+        )
+
+    def _fallback_doc_v2(self, bundle: Any, source: V2DocSource) -> str:
+        """Deterministic v2 document: formatted evidence, no invented timestamps."""
+        from ytk.renderers.evidence_formatter import format_evidence_refs
+        from ytk.renderers.source_links import format_seconds, image_markdown_ref
+
+        labels = _SECTION_TITLES[self._language]
+        title = str(source.metadata.get("title") or "Knowledge")
+        url = str(source.metadata.get("canonical_url") or "")
+        sections: list[str] = [labels["title_template"].format(title=title), ""]
+        if url:
+            sections += [labels["source"].format(url=url), ""]
+        sections += [labels["overview"], ""]
+        first_texts = [
+            (block.cleaned_text or block.raw_text).strip() for block in source.blocks[:3]
+        ]
+        overview = " ".join(text for text in first_texts if text) or labels["no_transcript"]
+        sections += [overview, ""]
+
+        image_assets = [
+            asset
+            for asset in (getattr(source.content, "assets", []) or [])
+            if asset.media_type == "image"
+        ]
+        if image_assets:
+            sections += ["## 图片" if self._language != "en" else "## Images", ""]
+            for index, asset in enumerate(image_assets, start=1):
+                alt = f"图 {index}" if self._language != "en" else f"Image {index}"
+                sections.append(image_markdown_ref(asset.relative_path, alt=alt))
+                sections.append("")
+
+        knowledge = list(getattr(bundle, "knowledge", []))
+        if knowledge:
+            sections += [labels["knowledge_atoms"], ""]
+            by_type: dict[str, list[Any]] = {}
+            for atom in knowledge:
+                by_type.setdefault(atom.atom_type, []).append(atom)
+            for atom_type, atoms in by_type.items():
+                localized = labels["type_titles"].get(atom_type, atom_type)
+                sections += [f"### {localized}", ""]
+                for atom in atoms:
+                    evidence = [
+                        bundle.evidence_index[evidence_id]
+                        for evidence_id in atom.evidence_ids
+                        if evidence_id in bundle.evidence_index
+                    ]
+                    citations = format_evidence_refs(
+                        evidence, bundle, language=self._language, validate=False
+                    )
+                    suffix = f" {' '.join(citations)}" if citations else ""
+                    sections.append(f"- {atom.content}{suffix}")
+                sections.append("")
+
+        sections += [labels["full_transcript"], ""]
+        if source.kind == "image_note":
+            sections.extend(image_note_block_line(block, language=self._language) for block in source.blocks)
+        else:
+            sections.extend(f"[{format_seconds(start)}] {text}" for start, text in source.segments)
+        if not source.blocks and not source.segments:
+            sections.append(labels["no_transcript"])
+        return "\n".join(sections)
+
+    def _call_minimax(self, prompt: str) -> str:
+        url = f"{self._base_url}/v1/chat/completions"
+        headers = {"Authorization": f"Bearer {self._api_key}"}
+        payload = {
+            "model": self._model,
+            "messages": [{"role": "user", "content": prompt}],
+            "max_completion_tokens": self._max_tokens,
+        }
+        try:
+            if self._deadline is None:
+                with httpx.Client(timeout=self._timeout) as client:
+                    resp = client.post(url, headers=headers, json=payload)
+                    resp.raise_for_status()
+                    result = resp.json()
+            else:
+                remaining = self._deadline - time.monotonic()
+                if remaining <= 0:
+                    raise RuntimeError("knowledge-doc total time budget exhausted")
+                # Inspect every received fragment against the wall-clock deadline.
+                # The read inactivity bound limits overshoot even for slow streams.
+                timeout = min(self._timeout, remaining, 60.0)
+                chunks: list[bytes] = []
+                received = 0
+                with httpx.Client(timeout=timeout) as client:
+                    stream_headers = {**headers, "Accept-Encoding": "identity"}
+                    with client.stream("POST", url, headers=stream_headers, json=payload) as resp:
+                        resp.raise_for_status()
+                        if resp.headers.get("Content-Encoding", "identity").lower() not in ("", "identity"):
+                            raise RuntimeError("knowledge-doc response has unexpected compression")
+                        for chunk in resp.iter_raw():
+                            if time.monotonic() >= self._deadline:
+                                raise RuntimeError("knowledge-doc total time budget exhausted")
+                            received += len(chunk)
+                            if received > 10 * 1024 * 1024:
+                                raise RuntimeError("knowledge-doc response exceeds size limit")
+                            chunks.append(chunk)
+                if time.monotonic() >= self._deadline:
+                    raise RuntimeError("knowledge-doc total time budget exhausted")
+                result = json.loads(b"".join(chunks))
+            choice = result["choices"][0]
+            if choice.get("finish_reason") != "stop":
+                raise RuntimeError("knowledge-doc response was incomplete or has no completion reason")
+            raw = choice["message"]["content"]
+        except (KeyError, json.JSONDecodeError, httpx.HTTPError) as exc:
+            raise RuntimeError(f"MiniMax knowledge-doc call failed: {exc}") from exc
+        return _THINK_RE.sub("", raw).strip()