devlyn-cli 0.5.2 → 0.5.4

package/optional-skills/dokkit/references/hwpx-structure.md

@@ -0,0 +1,159 @@
+# HWPX XML Structure Reference
+
+## Unpacking an HWPX
+
+```bash
+mkdir -p .dokkit/template_work
+cd .dokkit/template_work
+unzip -o /path/to/template.hwpx
+```
+
+## Reading Section XML
+
+```python
+import xml.etree.ElementTree as ET
+
+# Parse section file
+tree = ET.parse("Contents/section0.xml")
+root = tree.getroot()
+
+# HWPX namespaces
+ns = {
+    "hp": "http://www.hancom.co.kr/hwpml/2011/paragraph",
+    "hs": "http://www.hancom.co.kr/hwpml/2011/section",
+    "hc": "http://www.hancom.co.kr/hwpml/2011/core",
+    "hh": "http://www.hancom.co.kr/hwpml/2011/head",
+    "opf": "http://www.idpf.org/2007/opf",
+}
+
+# Find all paragraphs
+for p in root.iter("{http://www.hancom.co.kr/hwpml/2011/paragraph}p"):
+    texts = []
+    for t in p.iter("{http://www.hancom.co.kr/hwpml/2011/paragraph}t"):
+        if t.text:
+            texts.append(t.text)
+    if texts:
+        print("".join(texts))
+```
+
+## CRITICAL: Preserving Namespace Declarations
+
+Python's `xml.etree.ElementTree` **strips unused namespace declarations** when re-serializing XML. This breaks Hancom/Polaris Office, which requires ALL original namespace declarations on EVERY XML root element, even if no elements use those prefixes.
+
+**This applies to ALL HWPX XML files**, not just `section0.xml`:
+- `Contents/section0.xml` — root `<hs:sec>` needs 14+ xmlns
+- `Contents/content.hpf` — root `<opf:package>` needs 14+ xmlns
+- `Contents/header.xml` — root `<hh:head>` needs 14+ xmlns
+
+**After any ET-based XML modification**, you MUST restore the original namespace declarations:
+
+```python
+# After tree.write(), fix the root element:
+import re
+
+with open(section_xml_path, 'r', encoding='utf-8') as f:
+    content = f.read()
+
+# Capture original namespace declarations BEFORE any ET parsing
+ORIGINAL_ROOT_NS = (
+    'xmlns:ha="http://www.hancom.co.kr/hwpml/2011/app" '
+    'xmlns:hp="http://www.hancom.co.kr/hwpml/2011/paragraph" '
+    'xmlns:hp10="http://www.hancom.co.kr/hwpml/2016/paragraph" '
+    'xmlns:hs="http://www.hancom.co.kr/hwpml/2011/section" '
+    'xmlns:hc="http://www.hancom.co.kr/hwpml/2011/core" '
+    'xmlns:hh="http://www.hancom.co.kr/hwpml/2011/head" '
+    'xmlns:hhs="http://www.hancom.co.kr/hwpml/2011/history" '
+    'xmlns:hm="http://www.hancom.co.kr/hwpml/2011/master-page" '
+    'xmlns:hpf="http://www.hancom.co.kr/schema/2011/hpf" '
+    'xmlns:dc="http://purl.org/dc/elements/1.1/" '
+    'xmlns:ooxmlchart="http://www.hancom.co.kr/hwpml/2016/ooxmlchart" '
+    'xmlns:epub="http://www.idpf.org/2007/ops" '
+    'xmlns:config="urn:oasis:names:tc:opendocument:xmlns:config:1.0" '
+    'xmlns:opf="http://www.idpf.org/2007/opf/"'
+)
+
+# Replace stripped root with full original declarations
+content = re.sub(
+    r'<hs:sec\s+xmlns:[^>]+>',
+    f'<hs:sec {ORIGINAL_ROOT_NS}>',
+    content, count=1
+)
+
+# Also restore XML declaration to original format
+content = re.sub(
+    r"<\?xml version='1\.0' encoding='UTF-8'\?>",
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>',
+    content, count=1
+)
+
+with open(section_xml_path, 'w', encoding='utf-8') as f:
+    f.write(content)
+```
+
+**Also remove newlines** that ET inserts between the XML declaration and root element:
+```python
+content = content.replace('?>\n<', '?><')
+```
+
+**Best practice**: Before calling `ET.parse()`, save the original root opening tag. After `tree.write()`, replace the new root tag with the saved original. Apply this to EVERY HWPX XML file you modify (section0.xml, content.hpf, header.xml).
+
+## Repackaging an HWPX
+
+CRITICAL: The `mimetype` file must be first and uncompressed.
+
+```python
+import zipfile
+import os
+
+def repackage_hwpx(work_dir, output_path):
+    """Repackage modified XML files into a valid HWPX."""
+    with zipfile.ZipFile(output_path, 'w') as zf:
+        # mimetype MUST be first and uncompressed
+        mimetype_path = os.path.join(work_dir, "mimetype")
+        if os.path.exists(mimetype_path):
+            zf.write(mimetype_path, "mimetype", compress_type=zipfile.ZIP_STORED)
+
+        # Add all other files with compression
+        for root, dirs, files in os.walk(work_dir):
+            for file in files:
+                if file == "mimetype":
+                    continue
+                file_path = os.path.join(root, file)
+                arcname = os.path.relpath(file_path, work_dir)
+                zf.write(file_path, arcname, compress_type=zipfile.ZIP_DEFLATED)
+```
+
+## BinData and Image Handling
+
+### BinData Directory
+The `BinData/` directory (at the archive root) stores embedded binary resources — primarily images. Files are named sequentially: `image1.png`, `image2.jpg`, etc.
+
+### Image Registration — Manifest Only
+Images are registered ONLY in `Contents/content.hpf` via `<opf:item>` elements:
+```xml
+<opf:item id="image1" href="BinData/image1.png" media-type="image/png" isEmbeded="1"/>
+```
+
+**Critical**: Do NOT add `<hh:binDataItems>` entries to `header.xml` for images. The `content.hpf` manifest is the sole registration point. No entries are needed in `META-INF/manifest.xml` either.
+
+### Image Elements Use `hc:` Namespace
+The `<img>` element inside `<hp:pic>` uses the **core** namespace (`hc:`), not the paragraph namespace (`hp:`):
+```xml
+<!-- CORRECT -->
+<hc:img binaryItemIDRef="image1" bright="0" contrast="0" effect="REAL_PIC" alpha="0"/>
+
+<!-- WRONG — will not render -->
+<hp:img binaryItemIDRef="image1" .../>
+```
+
+See the `dokkit-image-sourcing` skill for the complete `<hp:pic>` element structure with all required children.
+
+## Critical Rules for HWPX Surgery
+
+1. **`mimetype` must be first in ZIP** — stored uncompressed
+2. **Preserve `hp:rPr` elements** — character formatting
+3. **Don't modify `hp:cellSpan`** — cell merging must remain intact
+4. **Keep `hp:cellAddr` — and ensure `rowAddr` = row index** — Each `<hp:tc>` has `<hp:cellAddr colAddr="C" rowAddr="R"/>` where `R` MUST equal the 0-based index of the parent `<hp:tr>` within the `<hp:tbl>`. If two rows share the same `rowAddr`, Polaris Office **silently hides** the duplicate — the table renders with missing data and no error. After any row insertion, deletion, or reordering, re-index ALL `rowAddr` values and update `<hp:tbl rowCnt="N">`.
+5. **Preserve paragraph properties** — `hp:pPr` controls alignment, spacing
+6. **Korean font references** — don't change `hangulFont`, `latinFont` attributes
+7. **Section boundaries** — each section file is independent

package/optional-skills/dokkit/references/image-opportunity-heuristics.md

@@ -0,0 +1,121 @@
+# Image Opportunity Heuristics for Section Content Fields
+
+Guide for detecting image insertion opportunities within `section_content` fields. These heuristics help the analyzer identify where AI-generated images can be interleaved with text to create visually rich proposals.
+
+## Content Signal Keywords
+
+Scan the `mapped_value` text for these signal keywords that indicate an image would add value.
+
+### By `content_type`
+
+| content_type | Korean keywords | English keywords |
+|---|---|---|
+| flowchart | 프로세스, 절차, 단계, 흐름, 순서, 워크플로우 | process, procedure, step, flow, workflow, pipeline |
+| diagram | 구조, 아키텍처, 시스템, 모듈, 구성도, 체계 | architecture, structure, system, module, framework, topology |
+| data | 시장규모, 성장률, 통계, 수치, 비율, 점유율, 매출 | market size, growth rate, statistics, data, ratio, share, revenue |
+| concept | 개념, 비전, 전략, 핵심, 모델, 방법론, 기술 | concept, vision, strategy, core, model, methodology, technology |
+| infographic | 비교, 장점, 특징, 차별점, 효과, 기대효과 | comparison, advantage, feature, differentiation, effect, benefit |
+
+### Signal strength
+
+- **Strong signal** (2+ keywords in same paragraph): high-priority opportunity
+- **Moderate signal** (1 keyword): include if surrounding context supports it
+- **Weak signal** (keyword in passing mention): skip unless the paragraph is >300 chars
+
+## Placement Rules
+
+### Where to insert
+
+- **After the paragraph** that introduces the concept — not before, not mid-paragraph
+- `insertion_point.strategy` = `"after_paragraph"`
+- `insertion_point.anchor_text` = a distinctive phrase (5-15 words) from the paragraph that signals the concept. Choose a phrase that is unique within the field's mapped_value.
+
+### Where NOT to insert
+
+- Never as the first element (before any text)
+- Never as the last element (after all text)
+- Never between two consecutive images (min 150 chars of text between image opportunities)
+- Never inside bulleted/numbered list sequences
+- Never right after a heading (insert after the explanatory paragraph instead)
+
+## Prompt Composition Strategy
+
+For each detected opportunity:
+
+1. **Read the anchor paragraph** in Korean
+2. **Identify the core concept** being described
+3. **Compose an English generation prompt** that:
+   - Describes the visual content (what to show)
+   - Specifies the style (technical diagram, data chart, concept illustration)
+   - Includes domain context (e.g., "for a government R&D proposal")
+   - Avoids text/labels in the image (these are hard to control)
+4. **Map to a preset**: `technical_illustration` (default for diagram, flowchart, concept), `infographic` (for data, infographic)
+
+### Prompt template
+
+```
+[content_type] showing [core concept from paragraph].
+Context: [section name] of a Korean government R&D project proposal.
+Style: Clean, professional, minimal text labels.
+Color scheme: Modern, corporate blue/teal tones.
+```
+
+## Skip Conditions
+
+Do NOT create image opportunities when:
+
+1. **Short content**: `mapped_value` < 400 characters total
+2. **Team/personnel lists**: Content is primarily names, roles, and qualifications (look for patterns like `이름:`, `직책:`, `담당:`, `학력:`, `경력:`)
+3. **Budget/financial tables**: Content is primarily numbers, amounts, costs (look for `원`, `만원`, `억원`, `비용`, `예산`)
+4. **Already has explicit image fields**: If the section already contains `field_type: "image"` fields in analysis.json, reduce max opportunities to 1
+5. **Simple form data**: Content is short key-value pairs without narrative text
+6. **Repeating field**: If the same section has multiple `section_content` fields that overlap in content
+
+## Limits and Spacing
+
+| Constraint | Value |
+|---|---|
+| Max opportunities per `section_content` field | 3 |
+| Min chars before first opportunity | 200 |
+| Min chars between opportunities | 150 |
+| Min total mapped_value length | 400 chars |
+| Max total opportunities across all sections | 12 |
+
+## Output Schema
+
+Each opportunity is added to the field's `image_opportunities` array:
+
+```json
+{
+  "opportunity_id": "imgop_{field_id}_{seq}",
+  "insertion_point": {
+    "strategy": "after_paragraph",
+    "anchor_text": "AI 유사도 탐색 알고리즘을 통해 기존 특허와의 유사성을 분석"
+  },
+  "generation_prompt": "Technical architecture diagram of an AI-powered IP similarity search system showing document ingestion, vector embedding, and similarity matching pipeline. Context: Korean government R&D proposal. Style: Clean, professional, minimal text. Color: Modern blue/teal.",
+  "preset": "technical_illustration",
+  "content_type": "diagram",
+  "rationale": "Text describes the AI algorithm workflow; a diagram clarifies the system architecture",
+  "dimensions": {
+    "width_hwpml": 36000,
+    "height_hwpml": 24000,
+    "width_emu": 4572000,
+    "height_emu": 3048000
+  },
+  "image_file": null,
+  "status": "pending"
+}
+```
+
+### Field meanings
+
+- `opportunity_id`: Unique ID, format `imgop_{field_id}_{sequence_number}`
+- `insertion_point.strategy`: Always `"after_paragraph"` for section content
+- `insertion_point.anchor_text`: Distinctive Korean phrase from the paragraph (used by filler to locate insertion point)
+- `generation_prompt`: English prompt for AI image generation
+- `preset`: Maps to `scripts/source_images.py` preset parameter
+- `content_type`: One of `flowchart`, `diagram`, `data`, `concept`, `infographic`
+- `rationale`: Brief explanation of why an image helps here
+- `dimensions`: Default size — filler may adjust based on content_type
+- `image_file`: `null` until sourced (set by fill-doc orchestrator)
+- `status`: `"pending"` → `"sourced"` → `"inserted"` (or `"skipped"`)

package/optional-skills/dokkit/references/image-xml-patterns.md

@@ -0,0 +1,338 @@
+# Image XML Patterns
+
+## DOCX Image Pattern
+
+### Required Namespace Declarations
+These namespaces must be present on the root `<w:document>` element:
+```xml
+xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing"
+xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main"
+xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture"
+xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+```
+
+### Relationship Entry (word/_rels/document.xml.rels)
+```xml
+<Relationship
+  Id="rId8"
+  Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image"
+  Target="media/image1.png"/>
+```
+
+### Content_Types Entry ([Content_Types].xml)
+Add if the image extension is not already registered:
+```xml
+<!-- For PNG images -->
+<Default Extension="png" ContentType="image/png"/>
+
+<!-- For JPEG images -->
+<Default Extension="jpeg" ContentType="image/jpeg"/>
+<Default Extension="jpg" ContentType="image/jpeg"/>
+```
+
+### Drawing Element (in document.xml)
+Wrap in a `<w:r>` element within a paragraph in the target cell:
+```xml
+<w:r>
+  <w:drawing>
+    <wp:inline distT="0" distB="0" distL="0" distR="0">
+      <wp:extent cx="914400" cy="1219200"/>
+      <wp:docPr id="1" name="Picture 1"/>
+      <a:graphic xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">
+        <a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture">
+          <pic:pic xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture">
+            <pic:nvPicPr>
+              <pic:cNvPr id="1" name="image1.png"/>
+              <pic:cNvPicPr/>
+            </pic:nvPicPr>
+            <pic:blipFill>
+              <a:blip r:embed="rId8"/>
+              <a:stretch><a:fillRect/></a:stretch>
+            </pic:blipFill>
+            <pic:spPr>
+              <a:xfrm>
+                <a:off x="0" y="0"/>
+                <a:ext cx="914400" cy="1219200"/>
+              </a:xfrm>
+              <a:prstGeom prst="rect"><a:avLst/></a:prstGeom>
+            </pic:spPr>
+          </pic:pic>
+        </a:graphicData>
+      </a:graphic>
+    </wp:inline>
+  </w:drawing>
+</w:r>
+```
+
+## HWPX Image Pattern
+
+### A. Registration — Manifest Only
+
+Images are registered ONLY in `Contents/content.hpf` manifest. Do NOT add `<hh:binDataItems>` to `header.xml`. No entries needed in `META-INF/manifest.xml`.
+
+```xml
+<!-- Contents/content.hpf — add <opf:item> for each image -->
+<opf:item id="image1" href="BinData/image1.png" media-type="image/png" isEmbeded="1"/>
+```
+
+The `id` attribute becomes the `binaryItemIDRef` in the `<hc:img>` element below.
+
+### B. Paragraph Structure (CRITICAL)
+
+Images MUST be placed **inside** the `<hp:run>` element, with `<hp:t/>` **after** the `<hp:pic>`. This matches real Hancom Office output.
+
+```xml
+<!-- CORRECT: pic inside run, t after pic -->
+<hp:p id="..." paraPrIDRef="..." styleIDRef="0" pageBreak="0" columnBreak="0" merged="0">
+  <hp:linesegarray>
+    <hp:lineseg textpos="0" vertpos="0" vertsize="{H}" textheight="{H}"
+                baseline="{H*0.85}" spacing="500" horzpos="0" horzsize="..." flags="393216"/>
+  </hp:linesegarray>
+  <hp:run charPrIDRef="0">
+    <hp:pic ...>...</hp:pic>
+    <hp:t/>
+  </hp:run>
+</hp:p>
+
+<!-- WRONG: pic as sibling of run — images will NOT render -->
+<hp:run charPrIDRef="0"><hp:t/></hp:run>
+<hp:pic ...>...</hp:pic>
+```
+
+### C. Complete `<hp:pic>` Structure (Hancom Canonical Order)
+
+Element order matches real Hancom Office output. Every child element listed is **required**. Do NOT include `<hp:lineShape>` (not present in real Hancom files).
+
+```xml
+<hp:pic id="{seq_id}" zOrder="{z}" numberingType="PICTURE" textWrap="TOP_AND_BOTTOM"
+        textFlow="BOTH_SIDES" lock="0" dropcapstyle="None"
+        href="" groupLevel="0" instid="{seq_id}" reverse="0">
+  <!-- Group 1: Geometry (Hancom canonical order) -->
+  <hp:offset x="0" y="0"/>
+  <hp:orgSz width="{W}" height="{H}"/>
+  <hp:curSz width="{W}" height="{H}"/>
+  <hp:flip horizontal="0" vertical="0"/>
+  <hp:rotationInfo angle="0" centerX="{W_half}" centerY="{H_half}" rotateimage="1"/>
+  <hp:renderingInfo>
+    <hc:transMatrix e1="1" e2="0" e3="0" e4="0" e5="1" e6="0"/>
+    <hc:scaMatrix e1="1" e2="0" e3="0" e4="0" e5="1" e6="0"/>
+    <hc:rotMatrix e1="1" e2="-0" e3="0" e4="0" e5="1" e6="0"/>
+  </hp:renderingInfo>
+  <!-- Group 2: Image data -->
+  <hp:imgRect>
+    <hc:pt0 x="0" y="0"/>
+    <hc:pt1 x="{W}" y="0"/>
+    <hc:pt2 x="{W}" y="{H}"/>
+    <hc:pt3 x="0" y="{H}"/>
+  </hp:imgRect>
+  <hp:imgClip left="0" right="{pixW}" top="0" bottom="{pixH}"/>
+  <hp:inMargin left="0" right="0" top="0" bottom="0"/>
+  <hp:imgDim dimwidth="{pixW}" dimheight="{pixH}"/>
+  <hc:img binaryItemIDRef="{manifest_id}" bright="0" contrast="0" effect="REAL_PIC" alpha="0"/>
+  <!-- Group 3: Layout (AFTER hc:img in Hancom canonical order) -->
+  <hp:sz width="{W}" widthRelTo="ABSOLUTE" height="{H}" heightRelTo="ABSOLUTE" protect="0"/>
+  <hp:pos treatAsChar="1" affectLSpacing="0" flowWithText="0" allowOverlap="0"
+          holdAnchorAndSO="0" vertRelTo="PARA" horzRelTo="COLUMN"
+          vertAlign="TOP" horzAlign="LEFT" vertOffset="0" horzOffset="0"/>
+  <hp:outMargin left="0" right="0" top="0" bottom="0"/>
+</hp:pic>
+```
+
+**Variable definitions**:
+- `{W}` / `{H}` — Display size in HWPML units (1/7200 inch). Use defaults from Size Calculations table or analysis.json dimensions.
+- `{W_half}` / `{H_half}` — Half of W/H for rotation center.
+- `{pixW}` / `{pixH}` — Actual pixel dimensions from PIL/Pillow `Image.open(path).size`.
+- `{manifest_id}` — The `id` attribute from the `<opf:item>` in `content.hpf`.
+- `{seq_id}` — Sequential ID: find max existing `id` in section XML + 1.
+- `{z}` — zOrder: find max existing `zOrder` in section XML + 1.
+
+### D. Python `build_hwpx_pic_element()` Function
+
+```python
+import xml.etree.ElementTree as ET
+from PIL import Image
+
+HP = "http://www.hancom.co.kr/hwpml/2011/paragraph"
+HC = "http://www.hancom.co.kr/hwpml/2011/core"
+
+def build_hwpx_pic_element(
+    manifest_id: str,
+    image_path: str,
+    width_hwpml: int,
+    height_hwpml: int,
+    seq_id: int,
+    z_order: int,
+) -> ET.Element:
+    """Build a complete <hp:pic> element for HWPX image insertion.
+    Uses Hancom canonical element order (verified against real Hancom Office output).
+
+    Args:
+        manifest_id: The id from content.hpf <opf:item> (e.g. "image1")
+        image_path: Path to the image file (for reading pixel dimensions)
+        width_hwpml: Display width in HWPML units (1/7200 inch)
+        height_hwpml: Display height in HWPML units (1/7200 inch)
+        seq_id: Sequential element ID (max existing + 1)
+        z_order: Z-order value (max existing + 1)
+    """
+    with Image.open(image_path) as img:
+        pix_w, pix_h = img.size
+
+    W = str(width_hwpml)
+    H = str(height_hwpml)
+    W_half = str(width_hwpml // 2)
+    H_half = str(height_hwpml // 2)
+    pixW = str(pix_w)
+    pixH = str(pix_h)
+    sid = str(seq_id)
+
+    pic = ET.Element(f"{{{HP}}}pic", {
+        "id": sid, "zOrder": str(z_order), "numberingType": "PICTURE",
+        "textWrap": "TOP_AND_BOTTOM", "textFlow": "BOTH_SIDES", "lock": "0",
+        "dropcapstyle": "None", "href": "", "groupLevel": "0",
+        "instid": sid, "reverse": "0",
+    })
+
+    # Hancom canonical order: offset, orgSz, curSz, flip, rotationInfo,
+    # renderingInfo, imgRect, imgClip, inMargin, imgDim, hc:img, sz, pos, outMargin
+    ET.SubElement(pic, f"{{{HP}}}offset", x="0", y="0")
+    ET.SubElement(pic, f"{{{HP}}}orgSz", width=W, height=H)
+    ET.SubElement(pic, f"{{{HP}}}curSz", width=W, height=H)
+    ET.SubElement(pic, f"{{{HP}}}flip", horizontal="0", vertical="0")
+    ET.SubElement(pic, f"{{{HP}}}rotationInfo", {
+        "angle": "0", "centerX": W_half, "centerY": H_half, "rotateimage": "1",
+    })
+
+    ri = ET.SubElement(pic, f"{{{HP}}}renderingInfo")
+    ET.SubElement(ri, f"{{{HC}}}transMatrix",
+                  e1="1", e2="0", e3="0", e4="0", e5="1", e6="0")
+    ET.SubElement(ri, f"{{{HC}}}scaMatrix",
+                  e1="1", e2="0", e3="0", e4="0", e5="1", e6="0")
+    ET.SubElement(ri, f"{{{HC}}}rotMatrix",
+                  e1="1", e2="-0", e3="0", e4="0", e5="1", e6="0")
+
+    imgRect = ET.SubElement(pic, f"{{{HP}}}imgRect")
+    ET.SubElement(imgRect, f"{{{HC}}}pt0", x="0", y="0")
+    ET.SubElement(imgRect, f"{{{HC}}}pt1", x=W, y="0")
+    ET.SubElement(imgRect, f"{{{HC}}}pt2", x=W, y=H)
+    ET.SubElement(imgRect, f"{{{HC}}}pt3", x="0", y=H)
+
+    ET.SubElement(pic, f"{{{HP}}}imgClip",
+                  left="0", right=pixW, top="0", bottom=pixH)
+    ET.SubElement(pic, f"{{{HP}}}inMargin",
+                  left="0", right="0", top="0", bottom="0")
+    ET.SubElement(pic, f"{{{HP}}}imgDim", dimwidth=pixW, dimheight=pixH)
+    ET.SubElement(pic, f"{{{HC}}}img", {
+        "binaryItemIDRef": manifest_id, "bright": "0", "contrast": "0",
+        "effect": "REAL_PIC", "alpha": "0",
+    })
+
+    # sz, pos, outMargin come AFTER hc:img (Hancom canonical order)
+    ET.SubElement(pic, f"{{{HP}}}sz", {
+        "width": W, "widthRelTo": "ABSOLUTE",
+        "height": H, "heightRelTo": "ABSOLUTE", "protect": "0",
+    })
+    ET.SubElement(pic, f"{{{HP}}}pos", {
+        "treatAsChar": "1", "affectLSpacing": "0", "flowWithText": "0",
+        "allowOverlap": "0", "holdAnchorAndSO": "0",
+        "vertRelTo": "PARA", "horzRelTo": "COLUMN",
+        "vertAlign": "TOP", "horzAlign": "LEFT",
+        "vertOffset": "0", "horzOffset": "0",
+    })
+    ET.SubElement(pic, f"{{{HP}}}outMargin",
+                  left="0", right="0", top="0", bottom="0")
+
+    return pic
+```
+
+### E. Critical Rules for HWPX `<hp:pic>`
+
+> **All 9 rules must be followed. Violating any one causes broken image rendering.**
+
+| # | Rule | Correct | Wrong |
+|---|------|---------|-------|
+| 1 | **`<img>` uses `hc:` namespace** | `<hc:img binaryItemIDRef="..."/>` | `<hp:img .../>` |
+| 2 | **`<imgRect>` has 4 `<hc:pt>` children** | `<hc:pt0 x="0" y="0"/>` ... `<hc:pt3>` | Inline `x1/y1/x2/y2` attributes |
+| 3 | **All required children present** | `offset`, `orgSz`, `curSz`, `flip`, `rotationInfo`, `renderingInfo`, `inMargin` | Missing any of these |
+| 4 | **No spurious elements** | Do NOT include `hp:lineShape` | `hp:caption`, `hp:shapeComment`, `hp:lineShape` |
+| 5 | **`imgClip` right/bottom = pixel dims** | `right="{pixW}" bottom="{pixH}"` | All zeros |
+| 6 | **Hancom canonical element order** | offset, orgSz, ..., hc:img, **then** sz, pos, outMargin | sz/pos first (pre-2026 incorrect order) |
+| 7 | **Register in `content.hpf` only** | `<opf:item>` in manifest | `<hh:binDataItems>` in header.xml |
+| 8 | **`hp:pos` attributes** | `flowWithText="0"` `horzRelTo="COLUMN"` | `flowWithText="1"` `horzRelTo="PARA"` |
+| 9 | **pic INSIDE run, t AFTER pic** | `<hp:run><hp:pic>...</hp:pic><hp:t/></hp:run>` | `<hp:run><hp:t/></hp:run><hp:pic>` |
+
+## Size Calculations
+
+### Dimension Conversion
+- **DOCX**: Uses EMUs (English Metric Units)
+  - 1 inch = 914,400 EMU
+  - 1 mm = 36,000 EMU
+  - Formula: `emu = mm * 36000`
+- **HWPX**: Uses HWPML units (1/7200 inch)
+  - 1 inch = 7,200 units
+  - 1 mm ≈ 283.46 units
+  - Formula: `hwpml = mm * 283.46` (or `inches * 7200`)
+  - Typical A4 text width: ~46,648 units (~165mm)
+
+### Default Dimensions by Image Type (Cell Images)
+| image_type | Width (mm) | Height (mm) | DOCX cx (EMU) | DOCX cy (EMU) | HWPX width | HWPX height |
+|-----------|-----------|------------|--------------|--------------|-----------|------------|
+| photo | 35 | 45 | 1,260,000 | 1,620,000 | 9,922 | 12,757 |
+| logo | 50 | 50 | 1,800,000 | 1,800,000 | 14,173 | 14,173 |
+| signature | 40 | 15 | 1,440,000 | 540,000 | 11,339 | 4,252 |
+| figure (cell) | — | — | — | — | Fit to cell | Fit to cell |
+
+**Cell images**: Use `cellSz` width/height minus margins for aspect-ratio-preserving fit.
+
+### Default Dimensions for Section Content Images
+| content_type | HWPX width | HWPX height | Approx mm | Note |
+|---|---|---|---|---|
+| diagram | 36,000 | 24,000 | 127x85 | ~77% of page width |
+| flowchart | 36,000 | 24,000 | 127x85 | ~77% of page width |
+| data (charts) | 36,000 | 20,000 | 127x71 | Wide format |
+| concept | 28,000 | 28,000 | 99x99 | Square |
+| infographic | 36,000 | 24,000 | 127x85 | ~77% of page width |
+
+### Python Code Snippet for DOCX Drawing Element Construction
+```python
+import xml.etree.ElementTree as ET
+
+def build_drawing_element(rel_id: str, width_emu: int, height_emu: int, pic_id: int, filename: str) -> ET.Element:
+    """Build a w:drawing element for image insertion."""
+    WP = "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing"
+    A = "http://schemas.openxmlformats.org/drawingml/2006/main"
+    PIC = "http://schemas.openxmlformats.org/drawingml/2006/picture"
+    R = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+    W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+
+    drawing = ET.Element(f"{{{W}}}drawing")
+    inline = ET.SubElement(drawing, f"{{{WP}}}inline",
+                           distT="0", distB="0", distL="0", distR="0")
+    ET.SubElement(inline, f"{{{WP}}}extent",
+                  cx=str(width_emu), cy=str(height_emu))
+    ET.SubElement(inline, f"{{{WP}}}docPr",
+                  id=str(pic_id), name=f"Picture {pic_id}")
+
+    graphic = ET.SubElement(inline, f"{{{A}}}graphic")
+    graphicData = ET.SubElement(graphic, f"{{{A}}}graphicData",
+                                uri="http://schemas.openxmlformats.org/drawingml/2006/picture")
+
+    pic = ET.SubElement(graphicData, f"{{{PIC}}}pic")
+    nvPicPr = ET.SubElement(pic, f"{{{PIC}}}nvPicPr")
+    ET.SubElement(nvPicPr, f"{{{PIC}}}cNvPr", id=str(pic_id), name=filename)
+    ET.SubElement(nvPicPr, f"{{{PIC}}}cNvPicPr")
+
+    blipFill = ET.SubElement(pic, f"{{{PIC}}}blipFill")
+    ET.SubElement(blipFill, f"{{{A}}}blip", attrib={f"{{{R}}}embed": rel_id})
+    stretch = ET.SubElement(blipFill, f"{{{A}}}stretch")
+    ET.SubElement(stretch, f"{{{A}}}fillRect")
+
+    spPr = ET.SubElement(pic, f"{{{PIC}}}spPr")
+    xfrm = ET.SubElement(spPr, f"{{{A}}}xfrm")
+    ET.SubElement(xfrm, f"{{{A}}}off", x="0", y="0")
+    ET.SubElement(xfrm, f"{{{A}}}ext", cx=str(width_emu), cy=str(height_emu))
+    prstGeom = ET.SubElement(spPr, f"{{{A}}}prstGeom", prst="rect")
+    ET.SubElement(prstGeom, f"{{{A}}}avLst")
+
+    return drawing
+```