devlyn-cli 0.5.1 → 0.5.3

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
+```