Keep HWP docs runnable against the published kordoc package

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

docs/features/hwp.md

@@ -13,9 +13,11 @@
 ## 먼저 필요한 것
 
 - Node.js 18+
-- 기본 패키지: `npm install -g kordoc pdfjs-dist`
-- 실행 전: `export NODE_PATH="$(npm root -g)"`
+- CLI를 한 번만 쓸 때: `npx --yes --package kordoc --package pdfjs-dist kordoc --help`
+- 반복 실행용 전역 설치: `npm install -g kordoc pdfjs-dist`
+- Node API 예시를 따라갈 로컬 작업 디렉터리: `npm init -y && npm install kordoc pdfjs-dist`
 - 현재 배포된 `kordoc` CLI는 시작 시 `pdfjs-dist`를 바로 불러오므로 PDF를 안 다뤄도 함께 설치해야 한다
+- `import { markdownToHwpx } from "kordoc"` 같은 ESM 예시는 전역 `NODE_PATH`가 아니라 로컬 설치 기준으로 실행해야 한다
 
 ## 어떤 경로를 선택하나
 
@@ -43,35 +45,44 @@
 ### Markdown 변환
 
 ```bash
-npx kordoc 보고서.hwp -o 보고서.md
+npx --yes --package kordoc --package pdfjs-dist kordoc 보고서.hwp -o 보고서.md
 ```
 
 ### JSON 변환
 
 ```bash
-npx kordoc 검토서.hwpx --format json > 검토서.json
+npx --yes --package kordoc --package pdfjs-dist kordoc 검토서.hwpx --format json > 검토서.json
 ```
 
 ### 배치 처리
 
 ```bash
-npx kordoc ./문서함/* -d ./변환결과
+npx --yes --package kordoc --package pdfjs-dist kordoc ./문서함/* -d ./변환결과
 ```
 
 ### 페이지 범위 지정
 
 ```bash
-npx kordoc 보고서.hwp --pages 1-3
+npx --yes --package kordoc --package pdfjs-dist kordoc 보고서.hwp --pages 1-3
 ```
 
 ### 디렉터리 감시 변환
 
 ```bash
-npx kordoc watch ./문서함
+npx --yes --package kordoc --package pdfjs-dist kordoc watch ./문서함
 ```
 
 ### 양식 필드 추출
 
+아래 Node API 예시는 `package.json`이 있는 로컬 작업 디렉터리에서:
+
+```bash
+npm init -y
+npm install kordoc pdfjs-dist
+```
+
+이미 `package.json`이 있으면 `npm install kordoc pdfjs-dist`만 추가로 실행하면 된다.
+
 ```bash
 node --input-type=module - <<'EOF'
 import { parse, extractFormFields } from "kordoc";

docs/install.md

@@ -259,6 +259,9 @@ npm install -g kordoc pdfjs-dist kbo-game kleague-results lck-analytics toss-sec
 export NODE_PATH="$(npm root -g)"
 ```
 
+HWP Node API 예시는 전역 `NODE_PATH` 대신 로컬 프로젝트에 `npm install kordoc pdfjs-dist` 후 실행한다.
+`kordoc` CLI를 일회성으로만 쓸 때는 `npx --yes --package kordoc --package pdfjs-dist kordoc ...` 형태를 사용한다.
+
 ### macOS 바이너리
 
 카카오톡 Mac CLI는 npm 패키지가 아니라 Homebrew tap 설치를 사용한다.

hwp/SKILL.md

@@ -36,7 +36,7 @@ metadata:
 
 - Node.js 18+
 - 출력 경로 쓰기 권한
-- `kordoc`과 `pdfjs-dist`를 같은 전역/로컬 환경에 설치했거나, 둘 다 포함된 `npx` 실행 환경
+- `kordoc`과 `pdfjs-dist`를 같은 전역/로컬 환경에 설치했거나, 둘 다 포함된 `npx --yes --package kordoc --package pdfjs-dist kordoc ...` 실행 환경
 - 현재 배포된 `kordoc` CLI는 시작 시 `pdfjs-dist`를 바로 로드하므로 PDF를 안 써도 함께 설치해야 한다
 
 ## Inputs
@@ -73,46 +73,64 @@ CLI만으로 부족하면 Node API를 사용한다.
 
 ## Workflow
 
-### 1. Install `kordoc` with `pdfjs-dist`
+### 1. Prepare the CLI runtime
 
-전역 설치가 필요하면:
+일회성 변환이면 둘 다 포함한 `npx` 형태를 바로 쓴다.
+
+```bash
+npx --yes --package kordoc --package pdfjs-dist kordoc --help
+```
+
+반복 실행용 전역 설치가 필요하면:
 
 ```bash
 npm install -g kordoc pdfjs-dist
-export NODE_PATH="$(npm root -g)"
 ```
 
 현재 배포된 `kordoc` CLI는 `pdfjs-dist`가 없으면 `kordoc --help` 단계부터 실패하므로
 깨끗한 환경에서는 두 패키지를 같이 설치한 뒤 실행한다.
 
-### 2. Convert a document to Markdown
+### 2. Prepare a local project for Node API examples
+
+`parse()`, `compare()`, `extractFormFields()`, `markdownToHwpx()` 같은 ESM 예시는
+전역 `NODE_PATH`가 아니라 **로컬 프로젝트 설치** 기준으로 실행한다.
 
 ```bash
-npx kordoc 보고서.hwp -o 보고서.md
+mkdir -p ./kordoc-local && cd ./kordoc-local
+npm init -y
+npm install kordoc pdfjs-dist
+```
+
+이미 `package.json`이 있는 작업 디렉터리라면 `npm install kordoc pdfjs-dist`만 추가로 실행하면 된다.
+
+### 3. Convert a document to Markdown
+
+```bash
+npx --yes --package kordoc --package pdfjs-dist kordoc 보고서.hwp -o 보고서.md
 ```
 
 여러 문서를 한 번에 처리하려면:
 
 ```bash
-npx kordoc ./문서함/* -d ./변환결과
+npx --yes --package kordoc --package pdfjs-dist kordoc ./문서함/* -d ./변환결과
 ```
 
 특정 페이지 범위만 읽고 싶으면:
 
 ```bash
-npx kordoc 보고서.hwp --pages 1-3
+npx --yes --package kordoc --package pdfjs-dist kordoc 보고서.hwp --pages 1-3
 ```
 
-### 3. Extract structured JSON for AI/automation
+### 4. Extract structured JSON for AI/automation
 
 ```bash
-npx kordoc 검토서.hwpx --format json > 검토서.json
+npx --yes --package kordoc --package pdfjs-dist kordoc 검토서.hwpx --format json > 검토서.json
 ```
 
 JSON 결과에서는 `success`, `markdown`, `blocks`, `metadata`를 우선 확인한다.
 표나 이미지가 중요하면 `blocks` 안의 `table`, `image` 타입을 확인한다.
 
-### 4. Inspect HWPX form fields from parsed blocks
+### 5. Inspect HWPX form fields from parsed blocks
 
 ```bash
 node --input-type=module - <<'EOF'
@@ -132,10 +150,10 @@ EOF
 자동 변환이 계속 들어오는 폴더면 CLI의 `watch` 명령을 쓴다.
 
 ```bash
-npx kordoc watch ./문서함
+npx --yes --package kordoc --package pdfjs-dist kordoc watch ./문서함
 ```
 
-### 5. Reverse-convert Markdown back to HWPX
+### 6. Reverse-convert Markdown back to HWPX
 
 ```bash
 node --input-type=module - <<'EOF'
@@ -147,7 +165,7 @@ writeFileSync("출력.hwpx", Buffer.from(hwpx));
 EOF
 ```
 
-### 6. Compare two document versions when diff matters
+### 7. Compare two document versions when diff matters
 
 ```bash
 node --input-type=module - <<'EOF'

scripts/skill-docs.test.js

@@ -184,19 +184,29 @@ test("hwp docs match the published kordoc install and runtime contract", () => {
   const readme = read("README.md");
   const sources = read(path.join("docs", "sources.md"));
 
-  assert.match(skill, /npx kordoc .* -o .*\.md/);
+  assert.match(skill, /npx --yes --package kordoc --package pdfjs-dist kordoc .* -o .*\.md/);
   assert.match(skill, /markdownToHwpx/);
   assert.match(skill, /extractFormFields/);
-  assert.match(featureDoc, /npx kordoc .* --format json/);
+  assert.match(skill, /npm init -y/);
+  assert.match(skill, /npm install kordoc pdfjs-dist/);
+  assert.doesNotMatch(skill, /^\s*npx kordoc\b/m);
+  assert.doesNotMatch(skill, /export NODE_PATH/);
+  assert.match(featureDoc, /npx --yes --package kordoc --package pdfjs-dist kordoc .* --format json/);
   assert.match(featureDoc, /markdownToHwpx/);
   assert.match(featureDoc, /(extractFormFields|양식 필드)/);
-  assert.match(featureDoc, /kordoc watch/);
+  assert.match(featureDoc, /npx --yes --package kordoc --package pdfjs-dist kordoc watch/);
+  assert.match(featureDoc, /npm init -y/);
+  assert.match(featureDoc, /npm install kordoc pdfjs-dist/);
+  assert.doesNotMatch(featureDoc, /^\s*npx kordoc\b/m);
+  assert.doesNotMatch(featureDoc, /export NODE_PATH/);
   assert.match(featureDoc, /npm install -g kordoc pdfjs-dist/);
   assert.doesNotMatch(featureDoc, /선택적으로 `pdfjs-dist`/);
   assert.doesNotMatch(featureDoc, /kordoc fill/);
   assert.doesNotMatch(featureDoc, /kordoc mcp/);
   assert.doesNotMatch(featureDoc, /fillForm/);
   assert.match(install, /npm install -g kordoc pdfjs-dist /);
+  assert.match(install, /HWP Node API 예시는 전역 `NODE_PATH` 대신 로컬 프로젝트에 `npm install kordoc pdfjs-dist` 후 실행/);
+  assert.match(install, /`kordoc` CLI를 일회성으로만 쓸 때는 `npx --yes --package kordoc --package pdfjs-dist kordoc \.\.\.` 형태를 사용한다\./);
   assert.match(readme, /\| HWP 문서 처리 \| .*양식 필드 추출.*Markdown→HWPX 역변환/);
   assert.doesNotMatch(readme, /\| HWP 문서 처리 \| .*양식 채우기/);
   assert.match(sources, /kordoc/);