/ky-markdown-rebuilder

name: ky-markdown-rebuilder
description: Rebuild visual documents into reliable Markdown by combining text extraction with page or screenshot alignment. Use when converting or cleaning up PDFs, slide decks, PPT/PPTX files, HTML pages, long screenshots, Word-like reports, whitepapers, course materials, business decks, scanned documents, or visually dense documents where plain text extraction may jumble layout, charts, timelines, diagrams, tables, screenshots, or logos.
metadata:
  short-description: Rebuild visual documents into page-aligned Markdown

KY Markdown Rebuilder

Use this skill when a document should become Markdown but the visual layout matters. The goal is not just conversion; it is content reconstruction with a reliable visual source of truth.

Core principle:

> Extract text first, render visual pages second, then rebuild Markdown from a page-aligned source of truth.

Default deliverable principle:

> Use intermediate files as working evidence, but deliver only the final calibrated Markdown and, when requested, an outline Markdown.

Host Compatibility

This package is portable across Codex, Claude Code, and Antigravity:

• Codex install path: `~/.codex/skills/ky-markdown-rebuilder/`
• Claude Code install path: `~/.claude/skills/ky-markdown-rebuilder/`
• Antigravity: copy the package into the workspace (e.g. `<workspace>/ky-markdown-rebuilder/`) and follow SKILL.md manually
• Shared assets: `scripts/` and `references/`
• Codex-only UI metadata: `agents/openai.yaml`

Both hosts should use the same workflow below. If a host cannot access one helper script or renderer, use its native browser/document tools for that step and keep the output contract unchanged.

When To Use

Use for:

• PDF reports, PPT-style PDFs, whitepapers, course packs, proposal decks.
• PPT/PPTX decks, slide exports, Keynote-like slide files.
• Scanned documents and photographed books (Scanned-Document route, `transcribe` mode).
• HTML pages or local web pages that need Markdown reconstruction.
• Long screenshots or image-heavy documents.
• Word/document files that contain diagrams, tables, screenshots, or complex layout.

Do not use for simple text-only files where normal conversion is enough.

Output Contract (LOCKED)

This is a hard contract, not a suggestion. `check_output.py` enforces the exact strings below. Do not invent alternative labels, languages, heading levels, or punctuation — every past "format drift" incident came from improvising here.

Language rules:

1. Structural labels are ALWAYS the exact Chinese strings defined below, regardless of the document language. 2. Body content and page titles follow the source document language (Chinese, English, Thai, or anything else). Never translate content inside the calibrated file; translation is a separate deliverable (see Filenames). 3. `## Page NN: Title` uses a half-width colon and zero-padded page numbers (minimum 2 digits). Never use a full-width colon in the heading.

Document header — the first lines of every calibrated file:

# <文档标题>

> 重建说明：模式 <fast|page-aligned|deep-visual|transcribe>；来源 `<源文件名>`；共 <M> 页；原图逐页查看 <N>/<M> 页。

The `原图逐页查看 N/M` count must be TRUE: only pages opened at original resolution count. Contact-sheet thumbnails do NOT count as inspection. Never claim more inspection than actually happened; if only 10 of 50 pages were opened, write `10/50`.

Page section template — identical for `## Page NN:` / `## Region NN:` / `## Screen NN:` routes; `## Sheet: 名称` uses the same four labels:

## Page 01: <页标题，跟随原文语言>

源图：[page-01.png](pages/page-01.png)

### 页面目的

- ...

### 布局地图

- ...

### 按区域确认内容

#### 区域 1：<位置与形态，如 左侧 2x2 卡片区>

...

### 视觉备注

- ...

Transcribe-mode page template (`transcribe` mode only — 1:1 content reproduction, no visual commentary):

## Page 01: <页标题；无标题页用 第 01 页>

源图：[page-01.png](pages/page-01.png)

<该页全部内容 1:1 转写：正文按原文语言，表格转 Markdown 表，保留空单元格与 "-" 占位>

Contract details:

• The only accepted section labels are `### 页面目的`, `### 布局地图`, `### 按区域确认内容`, `### 视觉备注` — exact spelling, H3 level, no colon suffix. English labels (`Page purpose` etc.) and bare-text labels (`页面目的:`) are contract violations. (`transcribe` mode omits the four sections entirely — never mix the two shapes in one file.)
• Region subsections under 按区域确认内容 use `#### 区域 N：<位置>` (full-width colon inside this label is correct).
• Source line: during validation use `源图：[page-NN.png](pages/page-NN.png)`. In the final deliverable (screenshots removed) replace with `源页：第 N 页` (PDF/scan), `源页：Slide NN` (PPT), or `源图：<原始输入文件名>` (single-image input). Every section has exactly one 源图/源页 line, directly under the `##` heading.
• Screenshot links are always RELATIVE paths (`pages/page-01.png`). Absolute paths become dead links the moment the work folder moves or is cleaned; if the pages directory will not survive delivery, use 源页 notes instead of links.
• Title/transition pages may keep each section to a single bullet, but all four sections stay present in page-aligned/deep-visual outputs.
• 视觉备注 must be page-specific. The checker fails when the identical note line appears on 3+ pages. Do not rotate canned sentences.
• Never wrap page body in a full-page code fence. Code fences are only for actual code or verbatim ASCII art. Tables become Markdown tables; the checker fails oversized fences.
• Every table needs a blank line before it. A table glued to the preceding text line (`หน่วย : ล้านบาท` directly above `| ... |`) renders as plain text, not a table. `scripts/fix_tables.py` inserts the missing blank lines; the checker fails glued tables.
• Chemistry/math notation uses `<sub>`/`<sup>` (e.g. H₂O, Zn + H₂SO₄), never code fences, never bare-text approximations.
• Never use HTML whitespace entities (`&nbsp;`, `&emsp;`, `&ensp;`, `&thinsp;`) to imitate the source's indentation or alignment — they render as garbage in plain-Markdown viewers. Visual indentation is l