devlyn-cli 0.5.1 → 0.5.3

package/optional-skills/dokkit/references/section-image-interleaving.md

@@ -0,0 +1,346 @@
+# Section Content Image Interleaving
+
+Algorithm and code patterns for inserting AI-generated images within `section_content` fields, interleaved between text paragraphs.
+
+## Overview
+
+When a `section_content` field has `image_opportunities` in analysis.json, the filler must:
+1. Resolve each opportunity's anchor text to a specific paragraph in the XML
+2. Build an image paragraph (`<hp:p>` or `<w:p>`) containing the image element
+3. Insert the image paragraph **after** the anchor paragraph
+4. Register the image in the document manifest
+
+## Algorithm: `fill_section_content_with_images()`
+
+```python
+def fill_section_content_with_images(
+    section_root,       # The section XML root element
+    content_elements,   # List of XML elements in the section_content range
+    mapped_value,       # The text content (markdown string)
+    image_opportunities,# List of image opportunity dicts from analysis.json
+    format_context,     # Dict with charPrIDs, header_path, etc.
+    template_type,      # "hwpx" or "docx"
+    work_dir,           # Path to template_work directory
+):
+    """Fill section content with text AND interleaved images.
+
+    Strategy:
+    1. First, fill the section content with formatted text (existing logic)
+    2. Then, for each sourced image opportunity, find the anchor paragraph
+       and insert an image paragraph after it
+    """
+    # Step 1: Fill text content using existing fill_section_content() logic
+    # (This creates all the text paragraphs with markdown formatting)
+    fill_section_content(section_root, content_elements, mapped_value, format_context, template_type)
+
+    # Step 2: Insert images at anchor points
+    sourced = [op for op in image_opportunities if op.get("status") == "sourced" and op.get("image_file")]
+
+    for opportunity in sourced:
+        anchor_text = opportunity["insertion_point"]["anchor_text"]
+        image_file = opportunity["image_file"]
+        dims = opportunity.get("dimensions", {})
+
+        # Find the anchor paragraph
+        anchor_p = find_anchor_paragraph(section_root, content_elements, anchor_text, template_type)
+        if anchor_p is None:
+            print(f"WARNING: Anchor text not found for {opportunity['opportunity_id']}, skipping image")
+            opportunity["status"] = "skipped"
+            continue
+
+        # Build image paragraph
+        if template_type == "hwpx":
+            img_p = build_hwpx_image_paragraph(
+                image_file, dims, format_context, work_dir
+            )
+        else:
+            img_p = build_docx_image_paragraph(
+                image_file, dims, format_context, work_dir
+            )
+
+        # Insert after anchor paragraph
+        insert_after_element(section_root, anchor_p, img_p)
+        opportunity["status"] = "inserted"
+```
+
+## Anchor Text Resolution
+
+The anchor text is a distinctive Korean phrase from the paragraph where the image should be inserted **after**.
+
+```python
+def find_anchor_paragraph(section_root, content_elements, anchor_text, template_type):
+    """Find the paragraph element containing the anchor text.
+
+    Search strategy:
+    1. Exact substring match in paragraph text
+    2. Normalized match (strip whitespace differences)
+    3. Partial match (first 20 chars of anchor)
+
+    Returns the <hp:p> or <w:p> element, or None if not found.
+    """
+    ns_t = "{http://www.hancom.co.kr/hwpml/2011/paragraph}t" if template_type == "hwpx" else "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}t"
+    ns_p = "{http://www.hancom.co.kr/hwpml/2011/paragraph}p" if template_type == "hwpx" else "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}p"
+
+    # Collect all paragraphs within the content range
+    paragraphs = []
+    for elem in content_elements:
+        if elem.tag == ns_p:
+            paragraphs.append(elem)
+        for child_p in elem.iter(ns_p):
+            if child_p not in paragraphs:
+                paragraphs.append(child_p)
+
+    # Strategy 1: Exact substring match
+    for p in paragraphs:
+        text = "".join(t.text or "" for t in p.iter(ns_t))
+        if anchor_text in text:
+            return p
+
+    # Strategy 2: Normalized match (collapse whitespace)
+    import re
+    normalized_anchor = re.sub(r'\s+', ' ', anchor_text.strip())
+    for p in paragraphs:
+        text = "".join(t.text or "" for t in p.iter(ns_t))
+        normalized_text = re.sub(r'\s+', ' ', text.strip())
+        if normalized_anchor in normalized_text:
+            return p
+
+    # Strategy 3: Partial match (first 20 chars)
+    partial = anchor_text[:20]
+    for p in paragraphs:
+        text = "".join(t.text or "" for t in p.iter(ns_t))
+        if partial in text:
+            return p
+
+    return None  # Not found — caller should skip with warning
+```
+
+## Image Paragraph Construction
+
+### HWPX: `<hp:p>` with `<hp:pic>`
+
+```python
+def find_center_parapr(header_path):
+    """Find first center-aligned paraPr from header.xml for image paragraphs."""
+    HH = "http://www.hancom.co.kr/hwpml/2011/head"
+    tree = ET.parse(header_path)
+    for pp in tree.getroot().iter(f"{{{HH}}}paraPr"):
+        align = pp.find(f"{{{HH}}}align")
+        if align is not None and align.get("horizontal") == "CENTER":
+            return pp.get("id")
+    return "0"  # fallback to default
+
+
+def build_hwpx_image_paragraph(image_file, dims, format_context, work_dir):
+    """Build an <hp:p> element containing an <hp:pic> for inline image display.
+
+    The paragraph contains:
+    - A <hp:run> with an empty <hp:t> (required for valid paragraph structure)
+    - A <hp:pic> element (the actual image)
+    - Center-aligned paraPrIDRef from header.xml
+    """
+    HP = "http://www.hancom.co.kr/hwpml/2011/paragraph"
+
+    # Use dimensions from opportunity, with defaults (~77% of A4 page width)
+    width_hwpml = dims.get("width_hwpml", 36000)   # ~127mm default
+    height_hwpml = dims.get("height_hwpml", 24000)  # ~85mm default
+
+    # Override small legacy defaults (15000 = ~53mm, too small for page)
+    if width_hwpml <= 16000:
+        width_hwpml = 36000
+    if height_hwpml <= 12000:
+        height_hwpml = int(width_hwpml * 0.667)
+
+    # Copy image to BinData/ and register in manifest
+    manifest_id, bin_path = register_image_in_manifest(image_file, work_dir)
+
+    # Get next sequential ID and zOrder from section XML
+    seq_id = format_context["next_seq_id"]
+    z_order = format_context["next_z_order"]
+    format_context["next_seq_id"] += 1
+    format_context["next_z_order"] += 1
+
+    # Find center-aligned paraPrIDRef from header.xml
+    center_parapr_id = format_context.get("center_parapr_id")
+    if center_parapr_id is None:
+        center_parapr_id = find_center_parapr(
+            os.path.join(work_dir, "Contents", "header.xml")
+        )
+        format_context["center_parapr_id"] = center_parapr_id
+
+    # Build the paragraph with center alignment
+    p = ET.Element(f"{{{HP}}}p")
+    p.set("paraPrIDRef", str(center_parapr_id))
+    p.set("styleIDRef", "0")
+    p.set("pageBreak", "0")
+    p.set("columnBreak", "0")
+    p.set("merged", "0")
+
+    # Hancom structure: <hp:run><hp:pic>...</hp:pic><hp:t/></hp:run>
+    # pic goes INSIDE run, t AFTER pic (verified against real Hancom Office output)
+    run = ET.SubElement(p, f"{{{HP}}}run")
+    run.set("charPrIDRef", str(format_context.get("normal_charpr_id", "0")))
+
+    # Build <hp:pic> element and append INSIDE the run
+    pic = build_hwpx_pic_element(
+        manifest_id=manifest_id,
+        image_path=bin_path,
+        width_hwpml=width_hwpml,
+        height_hwpml=height_hwpml,
+        seq_id=seq_id,
+        z_order=z_order,
+    )
+    run.append(pic)
+
+    # Empty <hp:t/> goes AFTER <hp:pic> inside the run
+    ET.SubElement(run, f"{{{HP}}}t")
+
+    return p
+```
+
+### DOCX: `<w:p>` with `<w:drawing>`
+
+```python
+def build_docx_image_paragraph(image_file, dims, format_context, work_dir):
+    """Build a <w:p> element containing a <w:drawing> for inline image display."""
+    W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+
+    width_emu = dims.get("width_emu", 5400000)    # 150mm default
+    height_emu = dims.get("height_emu", 3600000)   # 100mm default
+
+    # Copy image to word/media/ and register relationship
+    rel_id, media_path = register_image_in_docx(image_file, work_dir)
+    pic_id = format_context["next_pic_id"]
+    format_context["next_pic_id"] += 1
+    filename = os.path.basename(media_path)
+
+    # Build the paragraph
+    p = ET.Element(f"{{{W}}}p")
+
+    # Center alignment for the image paragraph
+    pPr = ET.SubElement(p, f"{{{W}}}pPr")
+    jc = ET.SubElement(pPr, f"{{{W}}}jc")
+    jc.set(f"{{{W}}}val", "center")
+
+    # Build the run with drawing
+    r = ET.SubElement(p, f"{{{W}}}r")
+    # Use build_drawing_element() from dokkit-image-sourcing skill
+    drawing = build_drawing_element(rel_id, width_emu, height_emu, pic_id, filename)
+    r.append(drawing)
+
+    return p
+```
+
+## Element Insertion
+
+```python
+def insert_after_element(root, anchor_elem, new_elem):
+    """Insert new_elem immediately after anchor_elem in the parent's children.
+
+    Handles both direct children and nested elements by building a parent map.
+    """
+    parent_map = {c: p for p in root.iter() for c in p}
+    parent = parent_map.get(anchor_elem)
+    if parent is None:
+        return False
+
+    children = list(parent)
+    idx = children.index(anchor_elem)
+    parent.insert(idx + 1, new_elem)
+    return True
+```
+
+## Image Registration (same rules as cell-level images)
+
+### HWPX Registration
+```python
+def register_image_in_manifest(image_file, work_dir):
+    """Copy image to BinData/ and register in content.hpf manifest.
+
+    Returns (manifest_id, bin_path).
+    Same rules as cell-level image registration:
+    - Register in content.hpf ONLY
+    - Do NOT add to header.xml binDataItems
+    """
+    import shutil
+    import os
+
+    # Find next available image number
+    bindata_dir = os.path.join(work_dir, "BinData")
+    os.makedirs(bindata_dir, exist_ok=True)
+    existing = [f for f in os.listdir(bindata_dir) if f.startswith("image")]
+    next_n = len(existing) + 1
+    ext = os.path.splitext(image_file)[1]
+    filename = f"image{next_n}{ext}"
+    bin_path = os.path.join(bindata_dir, filename)
+    shutil.copy2(image_file, bin_path)
+
+    # Register in content.hpf
+    manifest_id = f"image{next_n}"
+    content_hpf = os.path.join(work_dir, "Contents", "content.hpf")
+    # Add <opf:item id="imageN" href="BinData/imageN.ext" media-type="image/png" isEmbeded="1"/>
+    # (Filler agent performs the actual XML modification)
+
+    return manifest_id, bin_path
+```
+
+### DOCX Registration
+```python
+def register_image_in_docx(image_file, work_dir):
+    """Copy image to word/media/ and register in relationships and Content_Types.
+
+    Returns (rel_id, media_path).
+    Same rules as cell-level image registration:
+    - Add relationship in word/_rels/document.xml.rels
+    - Add Content_Types entry if extension not registered
+    """
+    import shutil
+    import os
+
+    media_dir = os.path.join(work_dir, "word", "media")
+    os.makedirs(media_dir, exist_ok=True)
+    existing = [f for f in os.listdir(media_dir) if f.startswith("image")]
+    next_n = len(existing) + 1
+    ext = os.path.splitext(image_file)[1]
+    filename = f"image{next_n}{ext}"
+    media_path = os.path.join(media_dir, filename)
+    shutil.copy2(image_file, media_path)
+
+    # Generate next relationship ID
+    rel_id = f"rId{next_n + 10}"  # offset to avoid conflicts
+    # (Filler agent adds the actual relationship XML and Content_Types entry)
+
+    return rel_id, media_path
+```
+
+## Edge Cases
+
+### Anchor text not found
+- **Action**: Skip the image opportunity, set `status: "skipped"`, log a warning
+- **Cause**: Text may have been modified during markdown rendering, or anchor was not distinctive enough
+- **Mitigation**: Analyzer should choose anchor text that is unique within the field
+
+### Image generation failure
+- **Action**: The image_file will be null and status remains "pending" (fill-doc sets to "skipped" on failure)
+- **Filler behavior**: Skip opportunities where `status != "sourced"`, proceed with text-only fill
+- **No fallback**: Do not insert placeholder images or broken references
+
+### Multiple images in same paragraph area
+- **Rule**: Min 150 chars between image opportunities (enforced by analyzer)
+- **If violated**: Insert images in order; later images shift down naturally
+
+### Content too short after formatting
+- **Rule**: If the filled section has fewer paragraphs than expected (e.g., due to markdown rendering differences), skip any opportunities whose anchor text cannot be found
+- **Never force**: Do not insert images at approximate positions if anchor resolution fails
+
+## Dimension Defaults for Section Content Images
+
+HWPML units are 1/7200 inch (NOT hundredths of mm). ~77% of A4 text width = 36,000 units.
+
+| content_type | HWPML width | HWPML height | Approx mm | EMU cx | EMU cy |
+|---|---|---|---|---|---|
+| diagram | 36,000 | 24,000 | 127x85 | 4,572,000 | 3,048,000 |
+| flowchart | 36,000 | 24,000 | 127x85 | 4,572,000 | 3,048,000 |
+| data | 36,000 | 20,000 | 127x71 | 4,572,000 | 2,540,000 |
+| concept | 28,000 | 28,000 | 99x99 | 3,556,000 | 3,556,000 |
+| infographic | 36,000 | 24,000 | 127x85 | 4,572,000 | 3,048,000 |

package/optional-skills/dokkit/references/section-range-detection.md

@@ -0,0 +1,118 @@
+# Section Content Range Detection (HWPX)
+
+## Problem
+
+When `analysis.json` records `element_path: "section/children[N:M]"` for `section_content` fields, those indices refer to the **pre-tip-removal** state of the document. Tip box removal (Phase 2) deletes standalone tip paragraphs from the section root, shifting all subsequent child indices.
+
+Using stale indices causes:
+1. **Section titles get destroyed** — the range overlaps title elements
+2. **Images don't show** — corrupted document structure
+3. **Out-of-bounds errors** — indices exceed actual child count
+
+## Solution: Dynamic Range Detection
+
+After tip removal, **recompute** section content ranges by scanning the section root's children for structural markers (section title elements). This produces correct post-removal indices.
+
+### Algorithm
+
+```python
+def find_section_content_ranges(root, hp_ns):
+    """Find content ranges for each section_content field by locating title markers.
+
+    Must run AFTER tip box removal so indices are stable.
+
+    Returns dict mapping field IDs to (start, end) inclusive child index ranges.
+    """
+    hp_tag = lambda name: f'{{{hp_ns}}}{name}'
+    children = list(root)
+    markers = {}  # label -> child index
+
+    for i, child in enumerate(children):
+        text = ''.join(t.text or '' for t in child.iter(hp_tag('t'))).strip()
+
+        # --- Section title markers ---
+        # These are hp:p elements containing 1x2 hp:tbl with numbered headings.
+        # Match by section number + characteristic keywords.
+        # Use flexible matching: number prefix + key Korean terms.
+
+        if '1.' in text and '문제' in text and ('Problem' in text or '필요성' in text):
+            markers['sec1_title'] = i
+        elif '2.' in text and '실현' in text and ('Solution' in text or '개발' in text):
+            markers['sec2_title'] = i
+        elif '3.' in text and '성장' in text and ('Scale' in text or '사업화' in text):
+            markers['sec3_title'] = i
+        elif '4.' in text and '팀' in text and ('Team' in text or '대표자' in text):
+            markers['sec4_title'] = i
+
+        # --- End markers (tables/sections that follow the content) ---
+        elif '사업추진' in text and '일정' in text and '협약기간' in text:
+            markers['schedule1'] = i
+        elif '사업추진' in text and '일정' in text and '전체' in text:
+            markers['schedule2'] = i
+        elif '팀 구성' in text and '구분' in text and '직위' in text:
+            markers['team_table'] = i
+
+    # Build ranges: content starts after title, ends before next structural element
+    ranges = {}
+    if 'sec1_title' in markers and 'sec2_title' in markers:
+        ranges['field_028'] = (markers['sec1_title'] + 1, markers['sec2_title'] - 1)
+    if 'sec2_title' in markers and 'schedule1' in markers:
+        ranges['field_029'] = (markers['sec2_title'] + 1, markers['schedule1'] - 1)
+    if 'sec3_title' in markers and 'schedule2' in markers:
+        ranges['field_046'] = (markers['sec3_title'] + 1, markers['schedule2'] - 1)
+    if 'sec4_title' in markers and 'team_table' in markers:
+        ranges['field_051'] = (markers['sec4_title'] + 1, markers['team_table'] - 1)
+
+    return ranges
+```
+
+### Integration into fill_template.py
+
+The filler agent MUST include this logic when generating `fill_template.py` for HWPX templates that have `section_content` fields:
+
+```python
+# Phase 2b: After tip removal, before filling
+# Override stale analysis.json ranges with dynamically-detected correct ranges
+dynamic_ranges = find_section_content_ranges(root)
+for fid, dyn_range in dynamic_ranges.items():
+    if fid in field_refs:
+        field_refs[fid] = dyn_range
+```
+
+### Adapting for Different Templates
+
+The marker detection patterns above are specific to the 예비창업패키지 사업계획서 template. For other templates:
+
+1. **Identify structural markers** — section title elements that bound each `section_content` field
+2. **Match by text content** — use keywords from the section titles that appear in the template
+3. **Map field IDs** — connect each `section_content` field's ID from analysis.json to the correct marker pair
+
+The general pattern is always:
+- `content_start = title_marker_index + 1`
+- `content_end = next_structural_element_index - 1`
+
+### Why Not Fix analysis.json Instead?
+
+The analyzer runs BEFORE tip removal, so it can only record pre-removal indices. The correct approach is:
+1. Analyzer records approximate ranges (useful for documentation)
+2. Filler dynamically recomputes exact ranges after cleanup
+
+### imgDim: Use Actual Image Dimensions
+
+When inserting images via `hp:pic`, the `hp:imgDim` element should use the **actual pixel dimensions** of the image file, not the display size. Use PIL/Pillow:
+
+```python
+from PIL import Image
+
+# Display size (for hp:sz, hp:picRect, hp:imgRect)
+img_w = SECTION_IMG_WIDTH   # e.g. 29400
+img_h = SECTION_IMG_HEIGHT  # e.g. 16538
+
+# Actual pixel dimensions (for hp:imgDim only)
+dim_w, dim_h = img_w, img_h
+try:
+    with Image.open(image_path) as pil_img:
+        dim_w, dim_h = pil_img.size
+except Exception:
+    pass  # Fall back to display dimensions
+```

package/optional-skills/dokkit/references/state-schema.md

@@ -0,0 +1,143 @@
+# Dokkit State Schema
+
+## state.json
+
+```json
+{
+  "version": "1.0",
+  "created": "2026-02-07T12:00:00Z",
+  "updated": "2026-02-07T12:30:00Z",
+
+  "sources": [
+    {
+      "id": "src_001",
+      "file_path": "docs/sample_source/resume.pdf",
+      "file_type": "pdf",
+      "display_name": "resume.pdf",
+      "content_path": ".dokkit/sources/resume.md",
+      "metadata_path": ".dokkit/sources/resume.json",
+      "summary": "Personal resume with education, work history, and skills",
+      "status": "ready",
+      "ingested_at": "2026-02-07T12:05:00Z"
+    }
+  ],
+
+  "template": {
+    "file_path": "docs/sample_template/template.docx",
+    "file_type": "docx",
+    "display_name": "template.docx",
+    "work_dir": ".dokkit/template_work/",
+    "set_at": "2026-02-07T12:15:00Z"
+  },
+
+  "analysis": {
+    "path": ".dokkit/analysis.json",
+    "total_fields": 22,
+    "mapped": 18,
+    "unmapped": 4,
+    "analyzed_at": "2026-02-07T12:16:00Z",
+    "image_fields": 2,
+    "image_fields_sourced": 1,
+    "image_fields_pending": 1
+  },
+
+  "filled_document": {
+    "status": "review",
+    "filled_at": "2026-02-07T12:20:00Z",
+    "modifications": [
+      {
+        "instruction": "Change phone to 010-1234-5678",
+        "fields_affected": ["field_005"],
+        "modified_at": "2026-02-07T12:25:00Z"
+      }
+    ]
+  },
+
+  "exports": [
+    {
+      "format": "docx",
+      "output_path": ".dokkit/output/filled_template.docx",
+      "exported_at": "2026-02-07T12:30:00Z",
+      "file_size": 45678
+    }
+  ]
+}
+```
+
+## Field Definitions
+
+### Root
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| version | string | yes | Schema version ("1.0") |
+| created | string | yes | ISO 8601 timestamp of workspace creation |
+| updated | string | no | ISO 8601 timestamp of last update |
+| sources | array | yes | List of ingested source documents |
+| template | object\|null | yes | Current template being filled |
+| analysis | object\|null | yes | Template analysis metadata |
+| filled_document | object\|null | yes | Filled document status |
+| exports | array | yes | List of exports performed |
+
+### Source Entry
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | string | yes | Unique identifier (src_NNN) |
+| file_path | string | yes | Original file location |
+| file_type | string | yes | Detected format |
+| display_name | string | yes | Human-readable name |
+| content_path | string | yes | Path to .md content file |
+| metadata_path | string | yes | Path to .json sidecar |
+| summary | string | yes | Brief content summary |
+| status | string | yes | "processing" \| "ready" \| "error" |
+| ingested_at | string | yes | ISO 8601 timestamp |
+| error_message | string | no | Error details (when status=error) |
+
+### Template
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| file_path | string | yes | Original template location |
+| file_type | string | yes | "docx" \| "hwpx" |
+| display_name | string | yes | Human-readable name |
+| work_dir | string | yes | Path to unpacked working copy |
+| set_at | string | yes | ISO 8601 timestamp |
+
+### Analysis
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| path | string | yes | Path to analysis.json |
+| total_fields | integer | yes | Total fields detected |
+| mapped | integer | yes | Fields with source mappings |
+| unmapped | integer | yes | Fields without mappings |
+| image_fields | integer | no | Total image fields detected |
+| image_fields_sourced | integer | no | Image fields with source images |
+| image_fields_pending | integer | no | Image fields awaiting images |
+| analyzed_at | string | yes | ISO 8601 timestamp |
+
+### Filled Document
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| status | string | yes | "filling" \| "review" \| "modified" \| "finalized" |
+| filled_at | string | yes | ISO 8601 timestamp |
+| modifications | array | no | List of modification records |
+
+### Export Entry
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| format | string | yes | "docx" \| "hwpx" \| "pdf" |
+| output_path | string | yes | Path to exported file |
+| exported_at | string | yes | ISO 8601 timestamp |
+| file_size | integer | no | File size in bytes |
+| warnings | array | no | Conversion warnings |
+
+## Valid Status Values
+
+### Source Status
+- `processing` — currently being parsed
+- `ready` — successfully ingested
+- `error` — parsing failed
+
+### Filled Document Status
+- `filling` — fields being mapped and filled
+- `review` — filling complete, awaiting review
+- `modified` — user requested changes
+- `finalized` — user approved, ready for export

package/optional-skills/dokkit/references/supported-formats.md

@@ -0,0 +1,67 @@
+# Supported Source Formats
+
+## Docling-Supported Formats
+
+### PDF
+- Text PDFs: direct text extraction
+- Scanned PDFs: OCR via Docling's built-in OCR
+- Mixed PDFs: handles both text and image regions
+- Tables: extracted as markdown tables
+
+### DOCX (Microsoft Word)
+- Paragraphs, headings, lists
+- Tables with merged cells
+- Embedded images (extracted as descriptions)
+- Headers/footers
+
+### PPTX (PowerPoint)
+- Slide content as sections
+- Speaker notes included
+- Tables and charts (text content)
+
+### HTML
+- Semantic structure preserved
+- Tables converted to markdown
+- Links and formatting extracted
+
+### CSV
+- Converted to markdown table
+- Headers auto-detected
+
+### MD (Markdown)
+- Passed through with minimal processing
+- Metadata extracted from frontmatter if present
+
+## Custom-Parsed Formats
+
+### XLSX (Excel)
+- Multiple sheets → separate sections
+- Tables preserved with formatting
+- Formulas shown as computed values
+- Named ranges and cell references
+
+### HWPX (Hancom Office)
+- Korean document format (XML-based, ZIP archive)
+- Structure: Contents/section*.xml
+- Tables with complex merging patterns
+- Korean text preserved with UTF-8 encoding
+
+### JSON
+- Formatted as structured markdown
+- Nested objects → indented sections
+- Arrays → lists or tables
+
+### TXT
+- Wrapped as markdown
+- Auto-detect structure (lists, paragraphs)
+
+## Image Formats (PNG, JPG, JPEG)
+- OCR via Google Gemini Vision API
+- Text extraction with layout preservation
+- Table detection in scanned documents
+- Handwriting recognition (best effort)
+
+## Unsupported Formats
+- HWP (legacy Hancom binary format — convert to HWPX first)
+- Password-protected files
+- DRM-protected documents