automate-hancom-documents

Hancom Document Automation

Start with the production action path: match the request to one public tool and call it. Read a reference only when the work in front of you needs what that reference holds.

Images in a request

Read a visible value directly and call its matching write. For image or PPT structure reconstruction, read references/native-layout.md (identical MCP resource: gsg-hwp-beta://reference/native-layout). That reference is the sole reconstruction workflow; this entrypoint only routes to it.

Non-negotiable rules

• Route every Hancom/HWP edit, analysis, and verification request through the gsg-hwp-beta-live MCP and this skill.
• Treat a change as successful only after the selected public tool reaches a terminal success result and its operation-specific readback confirms the requested state. A dispatched call or mutation attempt without that readback is not success.
• Choose the most specific public action tool for the user's request. Never invent an API name, cell address, control ID, or hidden execution field.
• Before every public write, choose a caller-owned operation_id (for example, a UUID) and keep it unchanged until that logical operation reaches a terminal result. Reuse the same ID only when retrying the same payload or recovering a lost response; use a new ID for an intentional second execution, even when its payload is identical. Never derive the ID from the payload. The same ID with different inputs is a conflict. Completed results remain replayable for up to 30 days by default; when the terminal journal exceeds 10,000 records or 64 MiB, the oldest terminal results are evicted first. Never recycle an ID after journal expiry or a not_found response.
• Live mode attaches only to the exact active, saved, editable HWP already registered in ROT. It does not open, save, clear, quit, or change history by default. Use hwp_undo or hwp_redo only for an explicit history request, and hwp_save_reopen_verify only for an explicit save-and-reopen verification request.
• Never use computer-use, Windows UI automation, keyboard/mouse control, or a Python COM document call as a fallback for an HWP operation. If the gsg-hwp-beta-live MCP is unavailable, disconnected, or returns a closed transport, report that exact state and stop. If a certified native operation is unavailable, return the structured result from the selected HWP tool and stop.
• Do not hard-code a document title, page number, table size, or cell map in reusable code.
• Reuse an already inspected paragraph range or table/cell target for edits, together with its document guards. Do not replace known coordinates with a document-wide find, and never invoke a Find/Replace dialog or a search action to locate an edit. If the target is unknown, read only the relevant pages once with hwp_inspect_patch_plan; find is a literal native text scan for requests that only identify text. Duplicate matches require structural scope or a user-specified occurrence, never an arbitrary first match. Re-inspect after a stale revision instead of reusing another document's offsets or IDs.
• When the user asks to analyze or verify how an open HWP page looks, call hwp_render_page; it preserves document state and uses HWP CreatePageImage. A successful render or generated PNG alone is not visual verification: open and inspect the returned PNG before claiming how the page looks, and pair it with structural inspection when exact text, IDs, merges, or sizes matter. Do not render in the middle of a fill, repeat, sync, or Excel append. For cell text, IDs, merges, or sizes use hwp_inspect_page_fast with include_cells=true. hwp_inspect_structure is not the cell-text readback.
• hwp_render_page publishes each completed PNG at a unique path only after CreatePageImage finishes. Active session directories are protected by a worker ownership lock. Released results have a 24-hour TTL and at least a 15-minute client-read grace; cleanup runs at worker startup and every 15 minutes, removes abandoned partial files, and evicts the oldest eligible results when the preview store exceeds 64 MiB.
• Document-local styles are read with hwp_list_styles; never use web search to infer a style ID or local title convention.
• For table/figure titles, prefer a normal text paragraph with the actual character and paragraph shapes copied from an inspected, correctly numbered title of the same kind (hwp_apply_style with source/target positions and style_copy_type=2). A registered style may contain an obsolete numbering definition. Write only the title wording; never manufacture the displayed table/figure number as literal text. Confirm automatic numbering in structural inspection and read the preceding/current/following titles. Use hwp_add_caption only when an object-attached caption is explicitly wanted, not as a substitute for the document's title paragraphs. Before adding another title, inspect the table/picture's existing caption: an attached or hidden caption can consume an extra number. Do not hide a numbering gap with manually typed digits; resolve the duplicate caption and verify the sequence. See references/native-editing.md for the exact workflow.
• For broken words or one/two-character spillovers, render the page and apply hwp_format_text(letter_spacing_percent=...) only to the necessary text range, including inside a table cell. Read the existing spacing where available; this field is absolute, not a delta. Start with a small 1–2 percentage-point change and re-render the affected line and its neighbours. Do not format every line in a multi-line paragraph/cell together, change font size, or insert manual line breaks merely to force a fit. Null spacing is unknown/mixed evidence, not zero.
• For an explicit convention-matching write, read observed_usage.convention_profile once and reuse only values the target document actually reports. Check each axis's sample_count, consistency, complete, variants, scope, and write_fields; never turn a conflicting or partial sample into a universal template.
• An unobserved convention axis is missing evidence, not a reason to refuse the edit. Leave that write field unchanged unless the user supplied it explicitly, and continue with the observed axes the write tool supports.
• Table-series tools copy the first table, regenerate each copied automatic-number control, and update only the literal title suffix while preserving the source caption style. Do not follow a successful series call with manual hwp_add_caption calls. If caption verification fails, report that failure instead of retrying captions or Undo in a loop.
• After a plugin update, stay in the current Codex task and call hwp_runtime_info. The stable MCP proxy reloads the worker automatically when its source hash changes and emits a tool-list change notification; call hwp_reload only to force a reload. Compare mcp, worker_process_id, source_path, and tool_schema_hash before continuing. native_bridge is only the version this build expects; loaded_native_bridge is the bridge DLL the running Hangul editor actually has mapped, read from its module list, and it is only ever asked of Hwp.exe — Hancom's HwpApi.exe automation host never loads the bridge and is not evidence about it. The bridge verdict is reported, never enforced: it does not gate any operation and never by itself makes you stop, refuse, or restart Hangul. Continue the requested work and pass native_bridge_notice through to the user when native_bridge_state is anything other than matched. Only native_bridge_state="mismatched" (hangul_restart_required=true) proves a stale DLL is executing right now; not_loaded means that Hangul started before this bridge was registered and the next Hangul start picks it up on its own. Never restart Hangul on your own initiative — the user may have unsaved work open; state the notice and let the user decide. If the refreshed direct tool is not yet visible, call it through hwp_execute with the exact tool name and arguments.
• The host may expose this skill directly from the plugin manifest, from a host cache, or through a legacy global Junction. Read the exact displayed SKILL.md path directly without assuming its storage form; do not locate, search, or compare other cache or installation paths.
• For table data keyed by visible header labels, use records. Use cells only with verified cell addresses and rows only when the user supplied an explicit start_cell. A returned target_id changes only the target, never the chosen data format.
• For titles in already divided table cells, keep the inspected table target and use hwp_fill_table; selecting an embedded picture changes the target. hwp_restructure_table is for photo-and-label layouts, not a general fallback for inserting titles or failed merges. hwp_patch_text replaces existing text; an empty range does not insert a paragraph or table row.
• Explicit 1 mm table rows and columns are supported. To make the physical cell reach that size, set every affected cell to font_size_pt=1, line_spacing_percent=50, and zero padding; larger inherited text or padding can make HWP expand the cell. HWP stores 1 mm as 283 HWPUNIT, so inspection reports about 0.998 mm per row or column.
• For an irregular or partially merged table, use the inspected CellTopology: actual cell address, row_span, column_span, and physical right/down neighbours. Never synthesize F1, A11, or an address-distance move sequence. Column and row formatting starts at the requested real cell; merging proceeds only through the recorded neighbour path after the covered owners form a gap-free rectangle.
• hwp_split_table_cell has two deliberately different modes. Use split_mode="equal" only to subdivide one unmerged physical cell. Use split_mode="existing_grid" only to restore the exact row_span × column_span grid hidden by a merged cell. Do not split a merged header merely to reach a column for formatting; format the real intersecting cell instead. A requested existing-grid split that does not match the inspected spans must be rejected before mutation.
• hwp_apply_page_plan keeps each block's absolute box.top_mm. It does that by writing the planned gap into the paragraph spacing of the block below it, which is the only vertical control a flow layout has; that channel is filled by the compiler and is deliberately absent from the published layout schema, so a layout tool cannot send it and a plan cannot ask for placement by hand. Blocks are emitted top-first regardless of declaration order. A block whose plan box overlaps the one above it, or whose content is taller than its box, is pushed down rather than moved up, and everything after it is measured from where it really ends. Positions land within about 0.2 mm; a plan whose content genuinely exceeds the body is rejected with the millimetres it is short.
• Use hwp_insert_layout for live insertion away from the document end. layout.target=current inserts at the user's collapsed cursor. layout.target=after_page with page=N inserts at the start of the existing next page and adds one trailing page break, so it creates exactly one isolated page without a blank page; after the last page it appends with one leading page break. Do not add another page_break block. Continue to use hwp_append_layout only for the document end.
• For screenshot or reference-layout reconstruction, restore the evidence-first sequence: call hwp_analyze_reference_image once with full_scan=true, inspect its overlay/contact sheets, let the model choose semantic elements and loose raster boxes, then call hwp_prepare_image_crops once. Mark rectangular photos as tight_raster and annotated maps/drawings/logos as annotated_group; crop preparation resolves the final boundaries and returns a boundary overlay while the model still owns meaning. In native tables, apply visible-surface ownership recursively: group title bands, repeated-item subheading pills, and their body boxes are separate cells or rows, never line-broken text inside one cell.
• Never delete and rebuild a page for a local correction. Use hwp_patch_text for a sentence or line break, table formatting tools for an existing ordinary table, image replace/size paths for one picture, and reference_layout_patch for existing reference-grid rows, columns, styles, or edges. Rebuild only when structural inspection proves that no local target can represent the requested correction.
• For table object “크기 고정”, call hwp_set_table_size_fixed(fixed=true) with the verified table target. false clears the setting. The tool reads the selected table's HWPML SIZE.Protect before and after, preserves its other properties and page count, and does not toggle an already-matching setting.
• headers filters target tables; it is not a copy of the records keys. Use only labels known to be visibly present in the target table. If a page already narrows the request sufficiently, pass page without speculative headers.