Splits HWP handling into three focused skills per issue #155:
- hwp (kept): kordoc-based read/convert (Markdown, JSON, diffing, form
fields, Markdown->HWPX). Description narrowed to 'read-only' to make
the routing policy explicit.
- rhwp-edit (new): HWP binary editing via new k-skill-rhwp npm package
that wraps the @rhwp/core WASM bindings as CLI subcommands: info,
list-paragraphs, search, insert-text, delete-text, replace-all,
create-table, set-cell-text, create-blank, and render.
- rhwp-advanced (new): guidance for the upstream Rust rhwp CLI
(export-svg --debug-overlay, dump, dump-pages, ir-diff, thumbnail,
convert) for layout debugging, IR inspection, version comparison,
and read-only-document unlocking.
The new k-skill-rhwp package under packages/ ships a Node.js 18+ CLI
and library that round-trips HWP 5.x documents entirely in-process; no
Rust toolchain is required. It auto-installs the WASM-required
globalThis.measureTextWidth shim for headless Node, and all editing
subcommands always write to a distinct output path so the source file
is never mutated. HWPX save remains disabled per the upstream rhwp
#196 data-safety gate; HWPX input is accepted but output is written as
HWP 5.x.
Includes 24 node:test cases covering init, round-trip insertText,
replaceAll, createTable + setCellText, deleteText, searchText,
listParagraphs, renderPage (SVG/HTML), and full CLI arg-parse +
end-to-end round-trip through the CLI layer.
Wires README feature table (3 rows for hwp / rhwp-edit / rhwp-advanced),
docs/install.md optional-install list, docs/roadmap.md (marks HWP
advanced editing as shipped while keeping Windows/security-module
automation out of scope), docs/sources.md (adds rhwp upstream, CLI
source, @rhwp/core, @rhwp/editor, and rhwp #196 references), and the
root pack:dry-run script. Adds a Changesets entry for k-skill-rhwp
minor.
Closes#155.
The follow-up closes the last runnable-contract gaps from review by documenting the working one-shot npx form and separating Node API examples into a local project install path. The regression suite now locks both install notes so future edits do not drift back to broken command shapes.
Constraint: Published kordoc CLI still requires pdfjs-dist at startup
Constraint: Global NODE_PATH does not make ESM imports from kordoc resolvable in the documented examples
Rejected: Keep bare `npx kordoc` examples | fails in a clean environment
Rejected: Keep global-install Node API guidance | ESM import remains unresolved
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep HWP docs aligned to verified published kordoc surfaces until the package contract changes upstream
Tested: node --test scripts/skill-docs.test.js
Tested: npm run ci
Tested: temp-dir local npm install kordoc pdfjs-dist plus markdownToHwpx -> sample.hwpx -> one-shot kordoc roundtrip smoke
Not-tested: upstream unpublished kordoc features beyond the verified CLI and Node API surfaces
The issue #119 follow-up needs the repository contract to match what the
currently published kordoc package actually supports. This narrows the
HWP skill/docs/tests to the verified install requirement and supported
CLI/Node API surfaces, and removes unsupported fill/mcp claims.
Constraint: Published kordoc CLI fails at startup without pdfjs-dist
Constraint: Docs/tests must reflect the current npm package behavior, not intended future features
Rejected: Keep fill/mcp examples with caveats | still documents unsupported entrypoints
Confidence: high
Scope-risk: narrow
Directive: Reintroduce fill/mcp docs only after verifying the published package exposes them in both CLI and Node API
Tested: node --test scripts/skill-docs.test.js; npm run ci; temp-dir clean install smoke; temp-dir kordoc+pdfjs-dist watch/parse/extractFormFields/compare/markdownToHwpx/roundtrip smoke; Claude architect review
Not-tested: Real-world HWPX template that produces non-empty extractFormFields output
Issue #119 replaces the previous HWP guidance with kordoc so the skill matches the newer agent-native document flow. The docs and regression tests now center the HWP skill on kordoc parsing, JSON extraction, diffing, form filling, and Markdown-to-HWPX round-tripping, while the install/source references stay in sync.
Constraint: The repository treats skill behavior as documentation contracts backed by regression tests
Constraint: The requested branch/PR flow must target dev with TDD and verified execution evidence
Rejected: Keep @ohah/hwpjs or hwp-mcp as fallback guidance | issue #119 explicitly approves replacing the prior stack with kordoc
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep future hwp skill/docs/tests aligned to a single kordoc-first contract unless a new issue explicitly reintroduces multi-backend routing
Tested: node --test scripts/skill-docs.test.js; npm run ci; temp-dir kordoc roundtrip via markdownToHwpx -> sample.hwpx -> kordoc CLI markdown output; architect review APPROVED
Not-tested: Live parsing of user-provided proprietary HWP/HWPX samples outside the generated roundtrip fixture
The approved HWP doc fix was already present on feature/#1, but the
skill-level guidance still lacked the verified `--images-dir` fallback
that the feature guide documented for separate image files. Add a
regression first to lock that expectation, then mirror the CLI-backed
fallback in `hwp/SKILL.md` so future edits cannot drift.
Constraint: Follow-up had to stay on PR #5 / branch `feature/#1` and remain documentation-only
Constraint: `hwpjs to-markdown --help` is the source of truth for `--include-images` and `--images-dir`
Rejected: Leave the fallback only in `docs/features/hwp.md` | the skill doc would still diverge from the verified workflow
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep `hwp/SKILL.md`, `docs/features/hwp.md`, and `scripts/skill-docs.test.js` aligned with the live `hwpjs to-markdown --help` surface
Tested: node --test scripts/skill-docs.test.js
Tested: npx --yes @ohah/hwpjs to-markdown --help
Tested: npm test
Tested: npm run ci
Tested: npx --yes skills add . --list
Not-tested: End-to-end conversion against a real `.hwp` fixture in this repository
The follow-up review found that the HWP skill docs described
`hwpjs to-markdown --include-images` as if it generated image
paths/files, while the actual CLI help says the flag embeds images
as base64 data URIs. This update corrects the verification wording
in the skill docs, mirrors the same note in the feature guide, and
adds regression coverage so the docs stay aligned with the verified
CLI behavior.
Constraint: Follow-up must stay on PR #5 / branch `feature/#1` and keep the existing HWP feature wiring intact
Constraint: Root regression coverage should lock the reviewed documentation behavior before future edits
Rejected: Switch the docs to `--images-dir` examples instead | would change the documented workflow instead of fixing the reviewed mismatch
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: If `hwpjs` changes `--include-images` semantics, update both `hwp/SKILL.md` and `docs/features/hwp.md` and keep `scripts/skill-docs.test.js` in sync
Tested: `node --test scripts/skill-docs.test.js`
Tested: `npx --yes @ohah/hwpjs to-markdown --help`
Tested: `npm test`
Tested: `npm run ci`
Tested: `npx --yes skills add . --list`
Not-tested: End-to-end HWP conversion with a fixture document in this repository (no sample `.hwp` fixture was added)
Issue #1 adds a new hwp skill that routes routine conversion work to @ohah/hwpjs and reserves hwp-mcp for Windows environments with Hangul installed and direct-control needs. The repo docs and root verification now cover the new skill so it remains visible in listings and regressions catch missing documentation.
Constraint: The repository is documentation-first for skills, so the change needed tested docs rather than a new runtime package
Constraint: No new dependencies were allowed for the repo implementation
Rejected: Adding a bundled HWP runtime wrapper package | issue scope only required the installable skill and guidance
Rejected: Defaulting to hwp-mcp on Windows without explicit Hangul availability | too risky for unsupported environments
Confidence: high
Scope-risk: narrow
Directive: Keep conversion/extraction guidance biased toward @ohah/hwpjs unless direct Hangul automation is explicitly available
Tested: npm test
Tested: npm run ci
Tested: npx --yes skills add . --list
Not-tested: Live conversion against a sample .hwp file using @ohah/hwpjs
Not-tested: Windows-only hwp-mcp control against a locally installed Hangul application
