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.
• 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. 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 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.
• 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.
• 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.

Skill registration ownership and migration

The plugin manifest (.codex-plugin/plugin.json with "skills": "./skills/") is the normal and only active owner of this skill. MCP worker startup reports manifest and legacy-path status but never creates, replaces, or removes anything under the global Codex skills directory.

For an existing installation, migrate in this order:

1. Confirm the installed plugin exposes automate-hancom-documents from its manifest. A missing global Junction is the expected state.
2. Inspect the old path without changing it: Get-Item -LiteralPath (Join-Path $codexHome "skills\automate-hancom-documents") -Force | Select-Object LinkType, Target, where $codexHome is the configured CODEX_HOME or the user .codex directory.
3. Remove that path only when it is a Junction and its resolved target is exactly this plugin's skills\automate-hancom-documents directory. Leave a real directory, an unreadable path, or a Junction to another installation untouched.
4. Reconnect the plugin and confirm the host exposes one skill entry.

From the installed plugin root, this PowerShell guard removes only the current plugin's own Junction and stops on every other path:

$codexHome = if ($env:CODEX_HOME) { [IO.Path]::GetFullPath($env:CODEX_HOME) } else { Join-Path $env:USERPROFILE ".codex" }
$legacySkill = Join-Path $codexHome "skills\automate-hancom-documents"
$currentSkill = (Resolve-Path ".\skills\automate-hancom-documents").Path
$item = Get-Item -LiteralPath $legacySkill -Force
$junctionTarget = [IO.Path]::GetFullPath([string]$item.Target)
if ($item.LinkType -ne "Junction" -or $junctionTarget -ne $currentSkill) { throw "Refusing to remove a path not owned by this plugin" }
Remove-Item -LiteralPath $legacySkill

Only a legacy host that cannot discover manifest skills should install or repair the compatibility Junction explicitly with uv run python .\skills\automate-hancom-documents\scripts\hwp_codex_skill_install.py. The command accepts an absent path or the already-current Junction and refuses every other existing path. It is never called by MCP worker startup.

Production action path

Match the user's request directly to one public action tool:

Live speed

Natural-language edits must finish as one or two public writes, not a search-and-retry loop.

• Call the matching write immediately. Do not list documents, walk the disk, or inspect unrelated pages first.
• 예비조망점 → 가시권 개수·내용·사진: one hwp_sync_visibility_analysis_tables. If a photo folder is missing, still run it; report the photo gap from input_guidance. Do not copy the template nine times by hand.
• Excel 건축개요/층별/용도별: one hwp_append_excel_table without inventing cell_range. The tool splits empty-row/column gutters and wide merged header groups. Only pass a range after that call names one.
• Do not parallelize writes against one Hangul process.
• hwp_render_page is last-look verification or an explicit “화면 확인해” request. Use dpi 72 unless the user asked for a closer look.

1. For a write, choose its operation_id, then call the selected tool immediately. Do not precede it with capability, catalog, document-list, connect, or inspect calls. The one convention-matching exception is a single hwp_list_styles call when the write tool does not already resolve the document's own convention. Read tools (hwp_inspect, hwp_inspect_page_fast, hwp_inspect_structure, hwp_render_page, hwp_list_styles) also auto-connect and require no session ID. Use hwp_inspect_page_fast only when an exact existing object ID or structural readback is required. Its instance_id goes directly in target_id for hwp_add_caption, hwp_replace_image, and hwp_fill_table; tools whose schema has a target parameter, including hwp_format_table, hwp_merge_table_cells, and hwp_split_table_cell, receive target: {"target_id": instance_id}. hwp_delete_control receives it in control_instance_ids. The six graph tools are audit/full-document extract only; ordinary inspect uses hwp_inspect_page_fast / hwp_inspect_structure. If that exact tool is documented here but absent from the current client's tool list, call hwp_execute once with the exact tool_name and the same argument object. This is only a stale-catalog forwarder; it does not search or reinterpret the request. If hwp_execute is also absent, reconnect the gsg-hwp-beta-live MCP connection in the current task and call hwp_runtime_info; do not create a new task.
2. The tool connects the active editable document, resolves the target, performs the certified action, and verifies the result in the same call. When HWP loses foreground focus, its caret stops blinking but the current-or-last HWP position remains the active target. Do not replace it with the Codex input caret. hwp_inspect.active_target distinguishes a caret, current table cell, selected text, selected cell block, selected table, and other selected controls. After succeeded, continue without a blanket re-inspection when the response already supplies affected_pages, state_token, selected_target_id, and affected_target_ids. Use those fields to carry the verified page and target scope into the next logical operation. retry_operation_id is only for recovering the same payload after a lost response; a new operation still needs a new operation_id.
3. A public table tool automatically selects exactly one candidate only when the caller's page, caption, headers, or table_index actually narrowed the match to that candidate. A lone global fallback that does not satisfy those filters is not auto-selected, and genuinely multiple candidates return needs_target. Call the same tool again with one returned opaque ID in the exact field reported by required_inputs: direct target_id or nested target.target_id. Preserve the original data format. If it returns needs_input, use required_inputs and input_guidance; when format_candidates is empty and cells is requested, provide the final display strings directly instead of waiting for another candidate list.
4. If the response is lost or the caller disconnects after dispatch, call hwp_get_operation_status with the original operation_id and document selector. Retry the write only with that exact ID and unchanged payload. Ask the user only when the target candidates are genuinely multiple or a required user value is missing. Do not automatically retry any other failure.
5. Do not call generic hwp_operate in production. It remains a QA-only diagnostic surface documented in references/qa-operation-internals.md.