hwp

name: hwp description: "HWP/HWPX create, read, edit, review, template-fill, QA. Triggers: 한글, .hwp, .hwpx, HWP, HWPX, Korean documents, 한컴오피스, OWPML."

HWP/HWPX Document Skill

Scope: HWP/HWPX only. Do NOT reference or load skills for other formats (DOCX, PPTX, XLSX, PDF). If the task involves a non-HWP format, stop and tell the user.

OfficeCLI routing and consent rule:

• First check whether officecli is available with command -v officecli.
• If installed, recommend OfficeCLI first for HWPX work and experimental rhwp-backed binary HWP read/edit.
• If missing, do not auto-install. Present choices before proceeding:
  1. Install forked OfficeCLI from https://github.com/lidge-jun/OfficeCLI via bash "$(npm root -g)/cli-jaw/scripts/install-officecli.sh".
  2. Continue only with lightweight HWP/HWPX fallback scripts for the current task, with limitations stated.
  3. Stop or cancel.
• Before taking a lightweight fallback path, ask the user again and state what HWP/HWPX features may be lost.
• If the user chooses lightweight mode, save that preference to memory for future Office work.
• Use upstream/vanilla iOfficeAI/OfficeCLI only when the user explicitly asks for upstream behavior.

OfficeCLI is the recommended advanced backend for HWPX work and experimental rhwp-backed binary HWP read/edit. Lightweight fallback: Python OOXML/OWPML scripts (scripts/*.py) for what OfficeCLI cannot cover, or when the user chooses lightweight mode: HWP→HWPX conversion, template assembly, pattern-match editing, direct XML edits. See §3. Triggers: "한글", ".hwpx", ".hwp", "HWP", "HWPX", Korean documents, 한컴오피스, OWPML.

OfficeCLI install contract inside cli-jaw: after user approval only, install or refresh OfficeCLI through bash "$(npm root -g)/cli-jaw/scripts/install-officecli.sh". This installs the supported fork from https://github.com/lidge-jun/OfficeCLI used for CJK/rhwp workflows. Do not use direct upstream install snippets unless the task explicitly asks for vanilla upstream OfficeCLI behavior.

OfficeCLI discovery rule: run officecli hwp doctor --json and officecli capabilities --json before claiming binary .hwp support. Use officecli hwp --json for current rhwp recipes/policies and officecli help <format> ... --json for DOCX/XLSX/PPTX-style schema help.

Same-file execution rule: run OfficeCLI commands against the same .hwpx or .hwp sequentially. Do not run officecli view, officecli validate, officecli query, or officecli get in parallel against one package. If a file lock occurs, stop and report the exact command and path before making a copy or retrying.

1. Quick Decision

2. Reference-Based Editing (Edit > Create from Scratch)

When the user says "format like X.hwpx", "공문 양식처럼", "기존 보고서 스타일", or provides a source file — start from the source. Don't rebuild from scratch.

Workflow

1. Copy the source: cp source.hwpx target.hwpx — inherits header.xml (styles), section0.xml (structure), META-INF
2. Open with officecli open target.hwpx — daemon returns immediately (do NOT run as run_in_background)
3. Remove body paragraphs only — keep header.xml (charPr/paraPr/borderFill), META-INF, settings
4. Add new content using existing styleidref values — they auto-apply

Why This Matters

HWPX header.xml holds all style definitions (charPr, paraPr, borderFill, listItems). Rebuilding these from scratch:

• Breaks styleidref cross-references in section0.xml
• Loses consistent 공문/보고서 visual conventions
• Breaks validation (officecli validate fails)
• Takes 10× longer than modifying the copy

Template Sources (priority order)

1. User-provided source file — first-class template
2. tests/fixtures/agentic/*.hwpx — realistic samples (gonmun with headings, report, minutes with tables)
3. templates/{base,gonmun,minutes,proposal,report}/ — Template Assembly system (see §4)
4. officecli create blank — only when nothing else applies

Example — Official Letter (공문) Reuse

# Method A: direct copy
cp SampleGonmun.hwpx MyGonmun.hwpx
officecli open MyGonmun.hwpx
# Use /table/fill to replace label-value cells
officecli set MyGonmun.hwpx /table/fill --prop '문서번호=2026-123'
officecli set MyGonmun.hwpx /table/fill --prop '수신=관계 부서장'
officecli close MyGonmun.hwpx

# Method B: template assembly (see §4)
python3 scripts/build_hwpx.py --template gonmun --output MyGonmun.hwpx
# Then edit with officecli as above

3. Reference Materials & Script Map

officecli covers most HWPX operations. For template assembly, direct XML editing, HWP conversion, and pattern matching, use these references + Python scripts.

References (reference/ — singular)

Scripts (scripts/) — Python OWPML Toolkit

Fixed-Layout Exam Visual QA

KICE-style exam sheets (국어 영역, 수학 영역, two-column <hp:colPr type="NEWSPAPER" colCount="2">, dense question numbering) are fixed-layout documents. Treat visual fidelity as stricter than generic text mutation:

1. Do not insert QA/proof markers into the visible body. Strings such as [CU TEMPLATE EDIT ...], VISUAL QA, or edited via Hancom Office HWP UI inside the question body are visual hard failures.
2. Capture before/after screenshots from Hancom Office HWP at the same zoom and page position. Store proof in screenshot paths, logs, or sidecar evidence, not in the document's first column, answer choices, header tables, or floating title/page-number objects.
3. If the requested edit changes exam content, replace only the intended anchor text/run. Preserve column breaks, question numbering, answer-choice tab layout, equations, and floating objects.
4. For direct XML edits, strip all <hp:linesegarray> layout cache entries before repacking so Hancom recalculates layout on open.
5. Pass criteria: same page count, same two-column structure, no unexpected body marker, no visible drift except the requested content change.

Editing Escalation Ladder

When officecli can't do the job, escalate in this order:

Escalation signals:

• officecli cannot add custom style → L2 (raw-set header.xml) + read reference/header-xml-guide.md
• Custom template overlay → L3 (scripts/build_hwpx.py) + read reference/style_id_maps.md
• HWP binary input → check officecli hwp doctor --json first; use native rhwp-backed officecli operations when ready, otherwise L3 (scripts/hwp_convert.py, then edit HWPX)
• Multi-file pattern match (exam questions, regulations) → L4 (see §16)
• Style ID lookup → Read reference/style_id_maps.md FIRST

4. Template Assembly (HWP 전용)

HWP has a unique base + overlay template system. Most HWPX creation for 공문/보고서/회의록/제안서 should use this instead of officecli create blank.

Available Templates

Method 1: build_hwpx.py (recommended)

python3 scripts/build_hwpx.py --template report --output Q4Report.hwpx
# Then edit content with officecli
officecli open Q4Report.hwpx
officecli set Q4Report.hwpx /table/fill --prop '제목=2026 Q4 보고'
# ... continue editing ...

Method 2: Manual Overlay (for customization)

# 1. Copy base skeleton
cp -r templates/base/ work/

# 2. Overlay domain-specific styles
cp -r templates/gonmun/* work/Contents/

# 3. Edit header.xml and section0.xml as needed
#    Reference: reference/header-xml-guide.md, reference/section0-xml-guide.md
#    Style IDs: reference/style_id_maps.md

# 4. Repack as HWPX (ZIP with strip + minify)
python3 scripts/ooxml/pack.py work/ out.hwpx

# 5. Validate
officecli validate out.hwpx

Style ID Reference

Every template defines charPr/paraPr/borderFill style IDs. To customize without breaking cross-references:

1. Read reference/style_id_maps.md for the template's complete ID index
2. Use scripts/analyze_template.py work/ to inspect current structure
3. Add new styles via reference/header-xml-guide.md patterns — preserve existing IDs

5. Subskill & Resource Map

HWP does not have bonus subskill folders (unlike docx's officecli-academic-paper/ or pptx's morph-ppt/). All auxiliary resources live directly inside this skill:

If future bonus subskills are added (e.g., ./creating.md, ./editing.md, ./officecli-kice-exam/), read them only for the specific task at hand.

6. Design Principles for Korean Documents

Korean Government Form Aesthetics (한국 공공양식 미감)

Korean official documents follow strict visual conventions. Respect them:

• Tables are the backbone: Korean forms are table-driven. Every label-value pair lives in a precisely merged cell grid. Preserve the grid structure exactly.
• Heading hierarchy: 제1조 (Articles) > 제1항 (Clauses) > 제1호 (Items). Use styleidref for outline levels. Never flatten the hierarchy.
• Fixed margins: Government forms use standard A4 margins (top/bottom ~15mm, left/right ~20mm). Do not alter margins on existing documents.
• Alignment: Body text is JUSTIFY (양쪽 정렬) by default in Korean documents. Headings may be CENTER. Never use LEFT for body text in formal documents.

Uniform Spacing Detection (균등분할)

Korean forms often use uniform character spacing for names in cells: "홍 길 동" (spaces between each character). This is a display convention, not data.

• When reading: strip uniform spaces to get the actual value ("홍길동").
• When writing: if the template cell uses uniform spacing, insert spaces to match (e.g., 2-char name "이 준", 3-char "홍 길 동", 4-char "남궁민수").
• Detection regex: ^(\S)\s(\S)\s(\S)$ etc. (single-char groups separated by 1 space).

Document Type Classification

7. Mandatory Verification (NEVER SKIP)

Treat verification as a gate, not a confirmation. Any failure = REJECT, do not deliver. Fix → re-run the checks → repeat until a pass finds zero new issues (one fix often surfaces another). After 3 rounds without convergence, STOP and report the likely root cause (template / engine-limit / ambiguous) for the user to decide.

After ANY HWPX edit operation, ALWAYS execute these in order:

# 1. Structural validation (MUST pass)
officecli validate output.hwpx

# 2. PDF visual verification (MUST check)
soffice --headless --convert-to pdf --outdir /tmp output.hwpx
# Verify: table positions, guide text removed, checkboxes correct,
#         merged cell text in correct row, numbers not corrupted

# 3. Visual QA via subagent (use reference/visual_qa_prompt.md)
#    python3 scripts/contact_sheet.py /tmp/output.pdf sheet.png
#    Then: dispatch subagent with reference/visual_qa_prompt.md

# 4. If Hancom Office available, also open .hwpx directly

Skip PDF verification = unverified output. Always inform user if soffice is unavailable.

8. Prerequisite Check

# OfficeCLI + rhwp: check only; do not auto-install from a skill.
if ! command -v officecli >/dev/null 2>&1; then
  echo "ASK USER: install forked OfficeCLI from https://github.com/lidge-jun/OfficeCLI, continue lightweight with HWP/HWPX limits, or stop."
  echo "Install command after approval: bash \"\$(npm root -g)/cli-jaw/scripts/install-officecli.sh\""
fi

# LibreOffice: check only; ask before installing when PDF conversion is needed.
which soffice >/dev/null 2>&1 || echo "ASK USER: LibreOffice is not installed; install it for PDF conversion or skip PDF output."

python3 -c "import lxml; import pyhwp" 2>/dev/null || echo "OPTIONAL: pip install lxml pyhwp (for Python fallbacks)"
echo "JAVA_HOME=$JAVA_HOME (required for H2Orestart HWP→HWPX conversion)"

9. Tool Discovery

Always confirm syntax from help before guessing:

officecli --help
officecli hwp --json
officecli hwp doctor --json
officecli capabilities --json
officecli view --help
officecli set --help
python3 scripts/hwpx_cli.py --help
python3 scripts/build_hwpx.py --help

10. Core Workflows

Create & Import & Merge

officecli create doc.hwpx                                    # empty doc
officecli create doc.hwpx --from-markdown input.md           # MD->HWPX (JUSTIFY default)
officecli create doc.hwpx --from-markdown input.md --align left  # left-aligned
officecli create doc.hwp --json                              # binary HWP via rhwp-field-bridge
officecli merge template.hwpx out.hwpx --data '{"이름":"홍길동"}'  # template {{key}} replace
officecli merge template.hwpx out.hwpx --data data.json           # JSON file data

# Template assembly (see §4)
python3 scripts/build_hwpx.py --template gonmun --output gonmun.hwpx

View Modes

officecli view doc.hwpx text                    # line-numbered text
officecli view doc.hwpx annotated               # path + style detail
officecli view doc.hwpx outline                 # headings only
officecli view doc.hwpx stats                   # document statistics
officecli view doc.hwpx html --browser          # A4 HTML preview
officecli view doc.hwpx markdown                # GFM markdown export
officecli view doc.hwpx tables                  # table 2D grid + label map
officecli view doc.hwpx forms --auto            # CLICK_HERE + label-value auto-detect
officecli view doc.hwpx forms --auto --json     # JSON for AI pipeline
officecli view doc.hwpx objects                 # picture/field/bookmark/equation list
officecli view doc.hwpx objects --object-type field  # filter by type
officecli view doc.hwpx styles                  # charPr/paraPr styles
officecli view doc.hwpx issues                  # 9-level validation issues

Edit

officecli add doc.hwpx /section[1] --type paragraph --prop text="content" --prop fontsize=11
officecli add doc.hwpx /section[1] --type table --prop rows=3 --prop cols=4
officecli set doc.hwpx '/section[1]/p[1]' --prop bold=true --prop align=CENTER
officecli set doc.hwpx / --prop find="old" --prop replace="new"
officecli remove doc.hwpx /section[1]/p[3]
officecli swap doc.hwpx '/p[1]' '/p[2]'

Label Fill (table auto-fill)

officecli set doc.hwpx / --prop 'fill:대표자=홍길동' --prop 'fill:연락처=010-1234'
officecli set doc.hwpx / --prop 'fill:주소>down=서울시'   # direction: right(default), down, left, up
officecli set doc.hwpx /table/fill --prop '이름=김서준'    # fill: prefix optional

Query (extended syntax)

officecli query doc.hwpx 'p'                          # all paragraphs
officecli query doc.hwpx 'tc[text~=홍길동]'           # cell text search
officecli query doc.hwpx 'run[bold=true]'              # bold runs
officecli query doc.hwpx 'p:has(tbl)'                  # paragraphs containing tables
officecli query doc.hwpx 'tbl > tr > tc[colSpan!=1]'   # merged cells
officecli query doc.hwpx 'run[fontsize>=20]'           # 20pt+ font
officecli query doc.hwpx 'p[heading=1]'                # heading 1

Operators: =, !=, ~= (contains), >=, <= Pseudo: :empty, :contains(text), :has(child), :first, :last Virtual attrs: text, bold, italic, fontsize, colSpan, rowSpan, heading

Resident Mode (live connection)

officecli open doc.hwpx          # returns IMMEDIATELY; daemon in bg
officecli view text               # view without re-opening
officecli set '/p[1]' --prop bold=true
officecli close                   # close session

Do NOT run officecli open as a background shell job. It returns immediately and the daemon lives in the background automatically. Running it as a monitored shell creates zombies and file locks.

Batch Mode (multiple commands)

officecli batch doc.hwpx <<'EOF'
view text
view stats
view forms --auto
EOF

Error decoding: 'X' is an invalid start of a value = shell syntax leaked into JSON-style batch. Use heredoc with single-quoted delimiter <<'EOF'.

Compare

officecli compare a.hwpx b.hwpx                    # text diff (default)
officecli compare a.hwpx b.hwpx --mode outline      # heading diff
officecli compare a.hwpx b.hwpx --mode table --json  # table diff JSON

LCS DP alignment (fallback greedy for >10M cells). Table similarity: dimension weight 0.3 + content weight 0.7. Page range filtering: --pages "1-3,5".

Validate

officecli validate doc.hwpx

9-level: ZIP integrity, package (mimetype/rootfile/version), XML, IDRef, table structure, namespace, BinData orphan, field pairs, section count.

Image & Watermark

# Inline image
officecli add doc.hwpx /section[1] --type picture --prop path=/path/to/image.png

# Page-centered floating image
officecli add doc.hwpx /section[1] --type picture \
  --prop path=/path/to/image.png \
  --prop anchor=page --prop halign=center --prop valign=middle

# Watermark (opaque RGB PNG recommended; avoid transparent PNGs)
officecli add doc.hwpx /section[1] --type watermark \
  --prop src=/path/to/watermark.png --prop bright=0 --prop contrast=0

# Adjust position after creation
officecli set doc.hwpx '/section[1]/p[2]/run[1]/pic[1]' \
  --prop x=1111 --prop y=2222 --prop lock=1 --prop wrap=topbottom

Watch & HTML Preview

officecli watch doc.hwpx           # auto-refresh HTML on file change
officecli unwatch doc.hwpx         # stop
officecli view doc.hwpx html --browser  # one-shot A4 preview

Pre-Delivery Checklist

• officecli validate passes (0 errors)
• soffice --headless --convert-to pdf → visual check
• Table cells in correct positions (cellAddr mapping)
• Guide text (※, 예시) fully removed
• Checkboxes □/■ in intended cells only
• Merged cell text in correct row
• If Hancom available, open .hwpx directly

11. Common Pitfalls

Essential Rules

• Auto-normalization: PUA removal and uniform spacing collapse are applied automatically.
• Transport parity: CLI, Resident, and MCP all support the same view modes (tables, markdown, objects, forms).

12. Form Recognition & Fill

4-Strategy Recognition

1. Adjacent cell label-value -- table label->value detection (default)
2. Header+data rows -- column-header recognition
3. In-cell patterns -- □ checkbox, keyword( ) paren-blank, (label: ) annotation
4. KV table detection -- 16 Korean keywords trigger auto-detection

3-Phase Fill Pipeline

1. In-cell patterns -- checkbox □->☑, paren-blank fill, annotation fill
2. Table label-value -- exact + prefix 60% matching, 4-directional (right/down/left/up)
3. Inline paragraph -- regex lookbehind for "label: value" outside tables

AI Form Fill Workflow

officecli view form.hwpx forms --auto --json > fields.json  # Step 1: recognize
# Step 2: AI maps label->value
officecli set form.hwpx /table/fill --prop '성 명=홍길동'   # Step 3: fill

Confidence & Feedback

• Fill returns unmatched labels (labels without matching cells reported)
• Font-size heading detection: H1 >= 1.5x, H2 >= 1.3x, H3 >= 1.15x base
• Multi-<hp:t> in-cell replacement handles fragmented text nodes
• Form confidence score included in recognition output

Regulation-Specific Patterns

• Checkbox hierarchy: □ (section) -> ○ (item) -> - (detail) -> * (footnote)
• Appendix references: [별첨 제N호], [별지 N] -- linked to form templates
• Digit-concatenated headings: "3지원금 집행기준" (no space between number and title)
• Uniform footer: repeated identical footers -> org extraction

Exam XML Structure Patterns (condensed)

13. Security

14. HWP->HWPX Conversion

Format Detection

file doc.hwpx   # "Zip archive" -> HWPX (ZIP + OWPML XML)
file doc.hwp    # "HWP Document" -> HWP 5.0 binary

Native HWP via rhwp Bridge (experimental)

Before operating on binary .hwp, check runtime readiness:

officecli hwp doctor --json
officecli capabilities --json
officecli hwp --json

Supported claims are capability-gated. Current safe recipes include:

officecli create file.hwp --json
officecli get file.hwp /provider/rhwp --json
officecli view file.hwp text --json
officecli view file.hwp svg --page 1 --json
officecli view file.hwp png --page 1 --out /tmp/hwp-png --json
officecli view file.hwp pdf --page 1 --out out.pdf --json
officecli view file.hwp markdown --json
officecli view file.hwp thumbnail --out thumb.png --json
officecli view file.hwp info --json
officecli view file.hwp diagnostics --json
officecli view file.hwp dump --json
officecli view file.hwp pages --page 1 --json
officecli view file.hwp fields --json
officecli view file.hwp field --field-name 회사명 --json
officecli view file.hwp table-cell --section 0 --parent-para 3 --control 0 --cell 0 --cell-para 0 --json
officecli view file.hwp tables --section 0 --json
officecli view file.hwp native --op get-style-list --json
officecli set file.hwp /field --prop name=회사명 --prop value=리지 --prop output=out.hwp --json
officecli add file.hwp /text --type paragraph --prop value=새본문 --prop output=out.hwp --json
officecli set file.hwp /text --find 마케팅 --replace 브릿지 --prop output=out.hwp --json
officecli set file.hwp /text --find 마케팅 --replace 브릿지 --in-place --backup --verify --json
officecli set file.hwp /table/cell --prop section=0 --prop parent-para=3 --prop control=0 --prop cell=0 --prop value=오피스셀 --prop output=out.hwp --json
officecli set file.hwp /convert-to-editable --prop output=editable.hwp --json
officecli set file.hwp /native-op --prop op=split-paragraph --prop paragraph=0 --prop offset=5 --prop output=out.hwp --json
officecli set input.hwpx /save-as-hwp --prop output=out.hwp --json

Policy:

• Blank .hwp creation is native when capabilities.formats.hwp.operations.create_blank.ready=true.
• get /provider/rhwp is metadata-only for binary .hwp; use it to inspect the packaged sidecar and provider capabilities, not as a generic DOM query surface.
• Body text insertion is native when capabilities.formats.hwp.operations.insert_text.ready=true; use a separate output path and inspect the returned safe-save transaction.
• PDF/PNG/markdown/thumbnail/info/diagnostics/dump/page exports are native when the matching export_pdf, render_png, export_markdown, thumbnail, document_info, diagnostics, dump_controls, or dump_pages capability is ready.
• view file.hwp native --op <name> is the read-only rhwp escape hatch for pinned native primitives such as styles and full-text search (--op search-all-text --native-arg text=...). Mutating native primitives still use set /native-op with explicit operation props and output-first mutation. (rhwp engine pinned at v0.7.12; the last five were wired 2026-06-20.)
• HWPX → HWP export is native when capabilities.formats.hwp.operations.save_as_hwp.ready=true; always verify with readback/Hancom before production use.
• Prefer output mode for binary .hwp mutation: --prop output=out.hwp.
• Use in-place mode only for /text replacement, only when explicitly requested, and only after capabilities.formats.hwp.operations.replace_text.safeInPlace.ready=true.
• In-place mode must include --in-place --backup --verify and must not include --prop output=....
• Treat table-cell mutation as coordinate-based and experimental.
• If pinned/latest rhwp exposes a native HWP primitive that OfficeCLI has not wired yet, report it as an OfficeCLI capability/wiring gap, not as proof that native HWP cannot do it.
• Verify edited output with view text, view svg, and Hancom open/render evidence before relying on it.

v0.7.12 native recipes (wired 2026-06-20; gate on officecli hwp doctor --json first). Read-only native operations exposed through view file.hwp native --op <name> do not require an output path; use that route for search-all-text. Native operations that are still only exposed through set /native-op require --prop op=<name> + --prop output=<path> because OfficeCLI writes a working copy. Verified against officecli 1.0.115+.

# full-text search (read)
officecli view file.hwp native --op search-all-text --native-arg text="검색어" --native-arg case-sensitive=false --native-arg include-cells=true --json
# page overlay images (read)
officecli set file.hwp /native-op --prop op=get-page-overlay-images --prop page-num=0 --prop output=out.hwp --json
# header/footer picture properties (read)
officecli set file.hwp /native-op --prop op=get-hf-picture-properties --prop section=0 --prop outer-para=0 --prop outer-control=0 --prop inner-para=0 --prop inner-control=0 --prop output=out.hwp --json
# insert a numbered-list start (mutate)
officecli set file.hwp /native-op --prop op=insert-new-number --prop section=0 --prop paragraph=0 --prop offset=0 --prop start-num=1 --prop output=out.hwp --json
# set header/footer picture properties (mutate)
officecli set file.hwp /native-op --prop op=set-hf-picture-properties --prop section=0 --prop outer-para=0 --prop outer-control=0 --prop inner-para=0 --prop inner-control=0 --prop props-json='{...}' --prop output=out.hwp --json

Binary .hwp Structured Creation Pattern

Use this pattern when the user asks for a complex native .hwp from scratch. Do not build the body by repeatedly inserting long text into the same paragraph/offset. Long Korean text can be reflowed by the rhwp readback provider, which can make safe-save semantic-delta checks fail even when a temp output was written. Repeated same-position insertion also produces one crowded run instead of a structured document.

Create structure first, then fill it:

1. Run officecli hwp doctor --json and officecli capabilities --json; continue only when the required native .hwp operations are ready.
2. Create the blank .hwp.
3. Add enough paragraphs with native-op insert-paragraph.
4. Insert short text chunks into explicit paragraph indexes with add /text --type paragraph.
5. Create tables at known paragraph positions with native-op create-table.
6. Discover table coordinates with view tables --include-empty.
7. Fill cells with /table/cell using the discovered section, parent-para, control, cell, and cell-para.
8. Apply formatting with native-op apply-char-format / apply-para-format.
9. Verify with view text, view tables, and a PDF/app-open render.

Example:

officecli create complex.hwp --json

officecli set complex.hwp /native-op \
  --prop op=insert-paragraph \
  --prop paragraph=0 \
  --prop output=01_para.hwp \
  --json

officecli add 01_para.hwp /text \
  --type paragraph \
  --prop paragraph=0 \
  --prop offset=0 \
  --prop value="복합 HWP 생성 보고서" \
  --prop output=02_title.hwp \
  --json

officecli set 02_title.hwp /native-op \
  --prop op=create-table \
  --prop paragraph=11 \
  --prop offset=0 \
  --prop rows=5 \
  --prop cols=4 \
  --prop output=03_table.hwp \
  --json

officecli view 03_table.hwp tables \
  --max-parent-para 20 \
  --max-control 4 \
  --max-cell 20 \
  --include-empty \
  --json

officecli set 03_table.hwp /table/cell \
  --prop section=0 \
  --prop parent-para=12 \
  --prop control=0 \
  --prop cell=0 \
  --prop cell-para=0 \
  --prop value="항목" \
  --prop output=04_cell.hwp \
  --json

officecli set 04_cell.hwp /native-op \
  --prop op=apply-char-format \
  --prop paragraph=0 \
  --prop start=0 \
  --prop end=12 \
  --prop props-json='{"bold":true,"fontSize":2200}' \
  --prop output=05_style.hwp \
  --json

officecli view 05_style.hwp text --json
officecli view 05_style.hwp tables --include-empty --json
officecli view 05_style.hwp pdf --out preview.pdf --json

Debug rule: if an insert fails with semantic-delta after a long single string, do not loosen safe-save and do not switch to HWPX. Split the body into shorter visible chunks, write each chunk to an explicit paragraph, then verify anchors and table cells from the output copy.

Conversion

# Python fallback (H2Orestart-based)
python3 scripts/hwp_convert.py input.hwp output.hwpx

# Legacy read-only HWP inspection (no conversion)
python3 scripts/hwp_reader.py input.hwp

Structural Differences

Editing Strategies for Converted Files

1. Title: run-aware replacement -- set_run_text(p0, 'old', 'new') (skip page-number runs)
2. Body: raw string replace on serialized XML -- sec0.replace(old, new)
3. Multi-<t> cells: use ReplaceTextInCell() -- concatenate all <t> -> match -> redistribute

15. Equation Handling (수식)

HWPX equations use Hancom's proprietary script language. NOT MathML, NOT LaTeX, NOT OMML.

# Create equation
officecli add doc.hwpx /section --type equation --prop 'script=x^2 + y^2 = r^2'
# View all equations
officecli view doc.hwpx objects --object-type equation
# Edit: modify <hp:script> text nodes via Python XML editing

Equation scripts are opaque -- edit only <hp:script> text, not the binary payload. Math exam docs (KICE) require <hp:equation> for every expression. Never use plain text.

Verified: KICE 수능 수학 template (/private/tmp/kice-full-edit-v2.hwpx, 836 equations) -- text/equation edit + lineseg strip -> Hancom OK.

16. Pattern-Match Editing (Python L4 Fallback)

For complex form editing beyond officecli set/find-replace (KICE exams, multi-section regulations, fragmented text nodes):

Core flow: unpack HWPX → strip lineseg → pattern-match edit XML → repack ZIP. Hancom recalculates layout on open.

Tools: scripts/hwpx_cli.py (unpack/search/replace/batch-replace/fill-table — strips lineseg automatically), scripts/ooxml/pack.py.

Key Patterns (non-exhaustive)

For repository-internal pattern catalog references (Plan 99.8 / 99.9) see the devlog; the scripts above implement the concrete operations.

Lineseg Strip (critical for direct XML editing)

When editing HWPX XML directly (NOT via officecli or scripts/hwpx_cli.py), you MUST strip ALL <hp:linesegarray> elements. Stale layout cache causes characters to overlap into a single line.

import re
xml = re.sub(r'<(?:hp:)?linesegarray[^>]*>.*?</(?:hp:)?linesegarray>', '', xml, flags=re.DOTALL)
xml = re.sub(r'<(?:hp:)?linesegarray[^/]*/>', '', xml)  # self-closing

officecli and scripts/hwpx_cli.py handle this automatically. This rule applies only to raw Python XML editing.

17. Anti-Patterns (MUST AVOID)

1. No equations in math exams = broken output -- KICE docs require <hp:equation> elements
2. No unguarded HWP binary overwrite -- binary .hwp editing is experimental via rhwp; prefer --prop output=...; only use safe in-place /text replacement when safeInPlace.ready=true and the command includes --in-place --backup --verify
3. No fake HWPX fallback when rhwp has a native HWP primitive -- if OfficeCLI lacks the route, say the route is not wired/capability-gated yet and stop for approval.
4. No XML editing without lineseg strip -- stale cache causes overlapping text. Use scripts/hwpx_cli.py (auto-strips) or apply the regex in §16
5. No visible QA markers in fixed-layout exams -- KICE-style documents fail visual QA if proof text is inserted into the question body; use screenshots or sidecar evidence.
6. No cross-format skill loading -- this skill is .hwp/.hwpx only
7. Rebuilding styles that exist in template — when user provides a source .hwpx, cp first and read reference/style_id_maps.md. See §2
8. Ignoring reference materials — reference/header-xml-guide.md, reference/section0-xml-guide.md, and reference/style_id_maps.md are mandatory reading for custom XML work. See §3

18. Dependencies