@nomadamas/k-skill 0.1.0

package/skills/public-restroom-nearby/instruction.md

@@ -0,0 +1,89 @@
+# Public Restroom Nearby
+
+## What this skill does
+
+유저가 알려준 현재 위치를 기준으로 **근처 공중화장실 / 개방화장실** 을 찾는다.
+
+- 위치는 자동으로 추정하지 않는다.
+- **반드시 먼저 현재 위치를 질문**한다.
+- 화장실 데이터는 공식 `공중화장실정보` 표준데이터를 기본으로 사용한다.
+- `KAKAO_REST_API_KEY` 또는 `kakaoRestApiKey` 옵션이 있으면 Kakao Local REST API로 `공중화장실`, `개방화장실`, `OL7` 주유소를 추가 조회해 병합한다.
+- 위치 문자열은 Kakao Map anchor 검색으로 좌표를 잡고, 가능한 경우 해당 시도 데이터만 좁혀서 조회한다.
+- 좌표를 직접 받으면 바로 nearby 계산으로 들어간다.
+
+## When to use
+
+- "근처 화장실 찾아줘"
+- "서울역 근처 공중화장실 있어?"
+- "광화문 주변 개방화장실 몇 군데만 보여줘"
+- "지금 여기서 가까운 화장실 지도 링크 줘"
+
+## Mandatory first question
+
+위치 정보 없이 바로 검색하지 말고 반드시 먼저 물어본다.
+
+- 권장 질문: `현재 위치를 알려주세요. 동네/역명/랜드마크/위도·경도 중 편한 형식으로 보내주시면 근처 공중화장실을 찾아볼게요.`
+- 위치가 애매하면: `가까운 역명이나 동 이름으로 한 번만 더 알려주세요.`
+
+## Official surfaces
+
+- 공공데이터포털 공중화장실 표준데이터 안내: `https://www.data.go.kr/data/15012892/standard.do`
+- 전국 CSV: `https://file.localdata.go.kr/file/download/public_restroom_info/info`
+- 지역별 CSV: `https://file.localdata.go.kr/file/download/public_restroom_info/info?orgCode=<시도코드>`
+- 파일 소개 페이지: `https://file.localdata.go.kr/file/public_restroom_info/info`
+- Kakao Map 모바일 검색: `https://m.map.kakao.com/actions/searchView?q=<query>`
+- Kakao Map 장소 패널 JSON: `https://place-api.map.kakao.com/places/panel3/<confirmId>`
+
+## Workflow
+
+1. 유저에게 반드시 현재 위치를 묻는다.
+2. 위치 문자열을 받으면 Kakao Map으로 anchor 후보를 고르고 좌표를 확보한다.
+3. anchor 주소에서 시도(서울/경기/부산 등)를 추론할 수 있으면 해당 지역 CSV로 좁힌다.
+4. 공식 `공중화장실정보` CSV를 내려받고, Kakao REST API 키가 있으면 `keyword.json?query=공중화장실`, `keyword.json?query=개방화장실`, `category.json?category_group_code=OL7` 결과를 추가한다.
+5. Kakao `distance` 필드는 버리고 모든 결과를 위·경도 haversine 거리로 직접 재계산한다.
+6. 좌표 50m 이내 중복은 동일 시설로 보고 CSV 결과를 우선 보존한다.
+7. 보통 3~5개만 짧게 정리하고, 필요하면 URL 인코딩된 지도 링크(`map.kakao.com/link/map/...`)를 같이 준다.
+
+## Responding
+
+결과는 보통 아래 필드를 포함해 짧게 정리한다.
+
+- 화장실명
+- 구분명(공중화장실 / 개방화장실)
+- 거리
+- 주소
+- 개방시간/상세
+- 지도 링크
+
+## Node.js example
+
+```js
+const { searchNearbyPublicRestroomsByLocationQuery } = require("public-restroom-nearby");
+
+async function main() {
+  const result = await searchNearbyPublicRestroomsByLocationQuery("광화문", {
+    limit: 3
+  });
+
+  console.log(result.anchor);
+  console.log(result.items);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});
+```
+
+## Done when
+
+- 유저의 현재 위치를 먼저 확인했다.
+- 공식 데이터 기반으로 최소 1개 이상 nearby restroom 을 찾았거나, 못 찾은 이유와 다음 질문을 제시했다.
+- 가장 가까운 결과를 3~5개 이내로 정리했다.
+
+## Failure modes
+
+- Kakao REST API 키가 없으면 CSV 단일 소스로 동작하므로 누락 POI가 있을 수 있다.
+- Kakao Map anchor 가 애매하면 위치 기준점이 흔들릴 수 있다.
+- 공개 표준데이터는 실시간 점유/잠금 상태를 주지 않으므로 개방시간 중심으로만 안내해야 한다.
+- CSV 인코딩/컬럼 구조가 바뀌면 정규화 로직을 다시 확인해야 한다.

package/skills/public-restroom-nearby/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "public-restroom-nearby",
+  "description": "Use when the user asks for nearby public/open restrooms or 근처 화장실. Always ask the user's current location first, then use the official nationwide public-restroom standard dataset plus Kakao anchor resolution.",
+  "profiles": [
+    "vault",
+    "lookup"
+  ],
+  "frontmatter": "name: public-restroom-nearby\ndescription: Use when the user asks for nearby public/open restrooms or 근처 화장실. Always ask the user's current location first, then use the official nationwide public-restroom standard dataset plus Kakao anchor resolution.\nlicense: MIT\nmetadata:\n  category: convenience\n  locale: ko-KR\n  phase: v1"
+}

package/skills/real-estate-search/instruction.md

@@ -0,0 +1,172 @@
+# Korean Real Estate Search
+
+## What this skill does
+
+기본적으로 `https://k-skill-proxy.nomadamas.org/v1/real-estate/...` 로 요청해서 한국 부동산 실거래가/전월세 데이터를 조회한다. 국토교통부(MOLIT) 실거래가 신고 데이터를 기반으로 한다.
+
+## When to use
+
+- "잠실 리센츠 2024년 매매 실거래가 찾아줘"
+- "마포구 아파트 전세 실거래가 보여줘"
+- "성수동 오피스텔 월세 실거래 데이터 볼래"
+- "강남구 연립다세대 매매 실거래가"
+- "용산구 상업업무용 건물 거래 내역"
+
+## When not to use
+
+- 해외 부동산 시세/거래 조회
+- 실거래가가 아닌 민간 호가/매물 비교만 필요한 경우
+- 세금/등기/중개 법률자문처럼 판단이 필요한 경우
+- 청약홈 분양/당첨 조회 (아직 미지원)
+
+## Inputs
+
+- `q`: 지역명 (region-code endpoint, 예: `"서울 강남구"`, `"마포구"`)
+- `lawd_cd`: 5자리 법정동 코드 (transaction endpoint, 예: `"11680"`)
+- `deal_ymd`: 6자리 거래년월 YYYYMM (예: `"202403"`)
+- `num_of_rows`: 조회 건수 (기본 100, 최대 1000)
+
+## Prerequisites
+
+없음. 사용자는 별도 API key를 준비할 필요가 없다. upstream key는 proxy 서버에서만 주입한다.
+
+## Default path
+
+추가 client API 레이어는 불필요하다. 그냥 프록시 서버에 HTTP 요청만 넣으면 된다.
+
+`KSKILL_PROXY_BASE_URL` 환경변수가 있으면 그 값을 사용하고, 없으면 기본 경로 `https://k-skill-proxy.nomadamas.org` 를 사용한다.
+
+## Supported endpoints
+
+### 지역코드 조회
+
+```
+GET /v1/real-estate/region-code?q={지역명}
+```
+
+### 실거래가/전월세 조회
+
+```
+GET /v1/real-estate/:assetType/:dealType?lawd_cd={코드}&deal_ymd={년월}
+```
+
+| assetType | dealType | 설명 |
+|---|---|---|
+| `apartment` | `trade` | 아파트 매매 |
+| `apartment` | `rent` | 아파트 전월세 |
+| `officetel` | `trade` | 오피스텔 매매 |
+| `officetel` | `rent` | 오피스텔 전월세 |
+| `villa` | `trade` | 연립다세대 매매 |
+| `villa` | `rent` | 연립다세대 전월세 |
+| `single-house` | `trade` | 단독/다가구 매매 |
+| `single-house` | `rent` | 단독/다가구 전월세 |
+| `commercial` | `trade` | 상업업무용 매매 |
+
+`commercial/rent`는 지원하지 않는다.
+
+## Example requests
+
+지역코드 조회:
+
+```bash
+curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/real-estate/region-code' \
+  --data-urlencode 'q=강남구'
+```
+
+아파트 매매 실거래가 조회:
+
+```bash
+curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/real-estate/apartment/trade' \
+  --data-urlencode 'lawd_cd=11680' \
+  --data-urlencode 'deal_ymd=202403'
+```
+
+오피스텔 전월세 조회:
+
+```bash
+curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/real-estate/officetel/rent' \
+  --data-urlencode 'lawd_cd=11680' \
+  --data-urlencode 'deal_ymd=202403'
+```
+
+## Response shape
+
+### 지역코드 응답
+
+```json
+{
+  "results": [
+    { "lawd_cd": "11680", "name": "서울특별시 강남구" }
+  ],
+  "query": "강남구",
+  "proxy": { "name": "k-skill-proxy", "cache": { "hit": false, "ttl_ms": 300000 } }
+}
+```
+
+### 매매 실거래가 응답
+
+```json
+{
+  "items": [
+    {
+      "name": "래미안 퍼스티지",
+      "district": "반포동",
+      "area_m2": 84.99,
+      "floor": 12,
+      "price_10k": 245000,
+      "deal_date": "2024-03-15",
+      "build_year": 2009,
+      "deal_type": "중개거래"
+    }
+  ],
+  "summary": {
+    "median_price_10k": 230000,
+    "min_price_10k": 180000,
+    "max_price_10k": 310000,
+    "sample_count": 42
+  },
+  "query": { "asset_type": "apartment", "deal_type": "trade", "lawd_cd": "11680", "deal_ymd": "202403" },
+  "proxy": { "name": "k-skill-proxy", "cache": { "hit": false, "ttl_ms": 300000 } }
+}
+```
+
+### 전월세 응답
+
+매매와 동일 구조이나 아이템에 `deposit_10k`, `monthly_rent_10k`, `contract_type` 이 포함되고, summary에 `median_deposit_10k`, `monthly_rent_avg_10k` 등이 들어간다.
+
+## Response policy
+
+- 실거래가/전월세 요청이면 `region-code` endpoint로 행정구역 코드를 먼저 확인한 뒤 자산 타입별 endpoint로 조회한다.
+- 아파트 매매는 `apartment/trade`, 아파트 전월세는 `apartment/rent` 를 우선 사용한다.
+- 오피스텔/빌라/단독주택/상업업무용은 자산 타입에 맞는 endpoint로 라우팅한다.
+- 사용자가 동/건물명/연월을 덜 줬으면 지역, 단지명, 기준 월을 먼저 보강한다.
+- 실거래가와 호가를 섞어 말하지 않는다. 이 스킬은 국토교통부 기반 실거래/전월세 신고 데이터를 다룬다.
+
+## Keep the answer compact
+
+- 지역명 + 자산 타입 + 거래년월
+- 거래 건수 (summary.sample_count)
+- 가격 요약: 중위값, 최소, 최대
+- 상위 3-5건 대표 거래 (이름, 면적, 층, 가격, 날짜)
+- 전월세면 보증금 + 월세 요약도 포함
+
+## Failure modes
+
+- `lawd_cd` 또는 `deal_ymd` 형식이 잘못되면 400 응답
+- 프록시 서버에 `DATA_GO_KR_API_KEY` 가 없으면 503 응답
+- upstream MOLIT API 오류면 502 + `molit_api_XXX` 에러 코드
+- 해당 지역/기간에 데이터가 없으면 빈 `items` 배열 반환
+
+## Done when
+
+- 요청 자산 타입에 맞는 endpoint를 선택했다.
+- 필요한 경우 `region-code` 로 지역코드를 먼저 확인했다.
+- 실거래가/전월세 결과를 조회하고 요약했다.
+- 원본 데이터 출처(국토교통부 실거래가 신고)를 함께 남겼다.
+
+## Notes
+
+- 원본 참고: `https://github.com/tae0y/real-estate-mcp/tree/main`
+- 공식 데이터 출처: 공공데이터포털 (`https://www.data.go.kr`)
+- 가격 단위: `price_10k`, `deposit_10k` = 만원 단위 (예: 245000 = 24억 5천만원)
+- 취소된 거래는 서버에서 자동 필터링된다.

package/skills/real-estate-search/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "real-estate-search",
+  "description": "Korean apartment/officetel/villa/single-house real transaction price and rent lookups via k-skill-proxy. Based on tae0y's real-estate-mcp and MOLIT public data APIs.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "lookup"
+  ],
+  "frontmatter": "name: real-estate-search\ndescription: Korean apartment/officetel/villa/single-house real transaction price and rent lookups via k-skill-proxy. Based on tae0y's real-estate-mcp and MOLIT public data APIs.\nlicense: MIT\nmetadata:\n  category: real-estate\n  locale: ko-KR\n  phase: v1"
+}

package/skills/rhwp-advanced/instruction.md

@@ -0,0 +1,145 @@
+# rhwp-advanced
+
+## What this skill does
+
+**업스트림 `rhwp` CLI**(Rust 네이티브 바이너리)를 써서 HWP 파일의 **레이아웃 디버깅·IR 구조 검사·버전 비교·썸네일 추출·배포용 문서 잠금 해제** 를 수행한다.
+`k-skill-rhwp`(Node 편집 CLI)가 다루지 못하는 구조 분석·렌더 문제 진단용이다.
+
+이 스킬은 **편집을 하지 않는다**. 편집은 [`rhwp-edit`](../rhwp-edit/SKILL.md) 스킬, 문서 → Markdown/JSON 변환은 [`hwp`](../hwp/SKILL.md) 스킬(kordoc) 을 쓴다.
+
+## When to use
+
+- "표/셀이 이상하게 잘려. 어디서 깨지는지 IR 덤프를 보고 싶어"
+- "두 HWP 파일 구조 차이를 줄 단위로 보고 싶어"
+- "SVG 렌더가 이상해. 문단/표 경계선을 시각적으로 확인하고 싶어"
+- "페이지가 몇 개이고 어느 문단이 몇 페이지에 걸쳐 있는지 보고 싶어"
+- "배포용(읽기전용) HWP 파일 잠금을 풀고 싶어"
+- "HWP 파일에서 PrvImage 썸네일을 꺼내고 싶어"
+
+## When not to use
+
+- **텍스트/표 편집** → `rhwp-edit` 스킬 (`k-skill-rhwp` CLI)
+- **HWP → Markdown/JSON/양식필드 변환** → `hwp` 스킬 (`kordoc`)
+- **GUI 자동화, 한컴 보안모듈 우회, Windows 레지스트리 제어** → 범위 밖이다.
+- **Node 코드에서 라이브러리 API 로 편집** → `k-skill-rhwp` 를 Node API 로 쓴다.
+
+## Prerequisites
+
+- **rhwp CLI 바이너리**. 다음 중 하나:
+  - `cargo install rhwp` (Rust toolchain 필요. Rust 1.75+. 네이티브 빌드이므로 PDF export 포함 전체 서브커맨드 가능)
+  - 또는 업스트림 릴리스 페이지 https://github.com/edwardkim/rhwp/releases 에서 플랫폼별 사전 빌드 바이너리 다운로드(있는 플랫폼 한정)
+- PATH 에 `rhwp` 실행 파일이 있는지 `rhwp --help` 로 먼저 확인한다.
+- 출력 파일 쓰기 권한.
+- 선택: PDF export 를 쓸 거면 업스트림 문서에서 해당 서브커맨드의 추가 요구사항 확인.
+
+## Inputs
+
+- 입력 HWP/HWPX 파일 경로
+- 서브커맨드별 좌표(구역/문단 index) 또는 페이지 번호
+- 출력 경로(일부 서브커맨드)
+
+## Routing policy
+
+| 목적 | 서브커맨드 | 대표 예시 |
+| --- | --- | --- |
+| 기본 메타(페이지/폰트/섹션 통계) | `rhwp info` | `rhwp info sample.hwp` |
+| 페이지를 SVG 로 렌더 | `rhwp export-svg` | `rhwp export-svg sample.hwp -o out/ -p 0 --debug-overlay` |
+| 페이지를 PDF 로 렌더(네이티브 빌드 한정) | `rhwp export-pdf` | `rhwp export-pdf sample.hwp -o out.pdf` |
+| 문서 IR 구조 덤프 | `rhwp dump` | `rhwp dump sample.hwp -s 0 -p 3` |
+| 페이지네이션 결과 덤프 | `rhwp dump-pages` | `rhwp dump-pages sample.hwp -p 2` |
+| 원시 레코드 덤프 | `rhwp dump-records` | `rhwp dump-records sample.hwp` |
+| 번호/글머리표/개요 진단 | `rhwp diag` | `rhwp diag sample.hwp` |
+| 두 파일 IR 비교 | `rhwp ir-diff` | `rhwp ir-diff a.hwpx b.hwp` |
+| PrvImage 썸네일 추출 | `rhwp thumbnail` | `rhwp thumbnail sample.hwp -o thumb.png` |
+| 배포용(읽기전용) → 편집 가능 변환 | `rhwp convert` | `rhwp convert locked.hwp unlocked.hwp` |
+| 빈 표 포함 문서 템플릿 생성 | `rhwp gen-table` | `rhwp gen-table out.hwp` |
+
+> `rhwp` v0.7.3 CLI 에는 **편집(edit/insert-text/save) 서브커맨드가 없다.** 편집은 `rhwp-edit` 스킬 (`k-skill-rhwp` CLI) 을 쓴다.
+
+## Workflow
+
+1. **설치 확인**: `rhwp --help` 실행. 서브커맨드 리스트가 나오지 않으면 설치부터.
+
+   ```bash
+   command -v rhwp || cargo install rhwp
+   rhwp --help | head
+   ```
+
+2. **메타 조회로 좌표 범위 확인**: 먼저 `rhwp info` 로 페이지 수, 섹션 수, 사용 폰트, 표/이미지 통계를 얻는다.
+
+   ```bash
+   rhwp info sample.hwp
+   ```
+
+3. **목적별 플로우**:
+
+   - **SVG 렌더가 이상할 때** — 디버그 오버레이 포함 SVG 를 뽑는다.
+
+     ```bash
+     mkdir -p out
+     rhwp export-svg sample.hwp -o out/ -p 0 --debug-overlay
+     open out/page-0.svg    # 문단/표 경계선과 `s{sec}:pi={idx} y={y}` 라벨이 시각화됨
+     ```
+
+   - **특정 페이지 레이아웃을 더 자세히 보고 싶을 때** — 페이지네이션 덤프.
+
+     ```bash
+     rhwp dump-pages sample.hwp -p 2
+     ```
+
+   - **표가 깨져 보일 때** — IR 덤프에서 셀 구조·ParaShape·LINE_SEG 를 본다.
+
+     ```bash
+     rhwp dump sample.hwp -s 0 -p 3
+     ```
+
+   - **두 버전 비교** — IR diff 로 구조 변경만 추린다.
+
+     ```bash
+     rhwp ir-diff draft-v1.hwp draft-v2.hwp > ir-diff.txt
+     ```
+
+   - **썸네일 추출**:
+
+     ```bash
+     rhwp thumbnail sample.hwp -o cover.png
+     # 또는 data URI 가 필요하면: --data-uri
+     ```
+
+   - **배포용(읽기전용) 문서 잠금 해제**:
+
+     ```bash
+     rhwp convert locked.hwp unlocked.hwp
+     # 이후 편집은 rhwp-edit 스킬의 k-skill-rhwp CLI 로 수행
+     ```
+
+4. **결과를 PR/보고서에 붙일 때**: SVG/PDF/썸네일은 파일 자체를 첨부하고, 덤프 출력은 너무 길면 상위 200~500 줄만 인용하고 전체는 파일로 첨부한다. 개인정보가 포함된 문서의 본문 텍스트는 마스킹한다.
+
+## Verify outputs
+
+- `export-svg`: 지정한 `-o` 경로에 `page-N.svg` 파일이 생겼고, 열었을 때 텍스트/도형이 보이며 `--debug-overlay` 사용 시 빨강/파랑 가이드선이 나타난다.
+- `dump` / `dump-pages` / `dump-records`: stdout 에 JSON/텍스트 구조가 최소 수십 줄 이상 나온다.
+- `ir-diff`: 두 파일이 구조적으로 같으면 거의 비어 있고, 다르면 줄 단위 delta 가 보인다.
+- `thumbnail`: 지정한 출력 경로의 PNG 가 실제 이미지 뷰어에서 열린다.
+- `convert`: 출력 파일을 다시 `rhwp info` 로 열었을 때 read-only 플래그가 내려가 있다.
+
+## Done when
+
+- 디버깅/검사 목적이라면: 사용자가 원한 구조/렌더 정보가 찍혀 있고 어느 서브커맨드 어떤 플래그로 뽑았는지 명시돼 있다.
+- `convert` 같은 one-shot 변환이라면: 산출 파일이 생성되었고 `rhwp info` 로 재확인 가능.
+
+## Failure modes
+
+- **`rhwp: command not found`** → `cargo install rhwp` 혹은 릴리스 바이너리 설치부터.
+- **`export-pdf` 실패** → PDF 는 네이티브 빌드에서만 보장. `@rhwp/core` WASM 경로에서는 불가. 네이티브 `cargo install` 바이너리로 실행 중인지 확인.
+- **HWPX 저장 경로 비활성화(rhwp #196)** → `rhwp` CLI 자체가 HWPX 를 다시 HWPX 로 내보내지 않도록 막아둔 상태. 저장이 필요한 작업은 HWP 5.x 로만 수행한다.
+- **편집 서브커맨드 부재** → v0.7.3 기준 `rhwp` CLI 는 편집 명령을 제공하지 않는다. 편집은 `rhwp-edit` 스킬.
+- **Windows 보안모듈/한컴 GUI 자동화** → 본 스킬 범위 밖. `rhwp` 는 파일 포맷 엔진이다.
+- **버전 드리프트** → rhwp 는 활발히 개발 중이다. 서브커맨드 플래그가 바뀌거나 추가될 수 있으니 `rhwp <subcommand> --help` 를 먼저 확인한다.
+
+## Notes
+
+- 업스트림: https://github.com/edwardkim/rhwp
+- 편집 경로(이 repo): [`rhwp-edit`](../rhwp-edit/SKILL.md)
+- 조회/변환 경로(이 repo): [`hwp`](../hwp/SKILL.md)
+- 이 스킬은 **설치 안내 + 실행 레시피**에 가까운 안내형 스킬이다. 프로그램적 제어가 필요하면 `rhwp-edit` 의 Node API(`k-skill-rhwp`)를 쓰고, 여기서는 빠른 디버깅용으로만 사용한다.

package/skills/rhwp-advanced/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "rhwp-advanced",
+  "description": "Debug HWP layout, dump document IR, compare versions, extract thumbnails, and unlock read-only HWPs with the upstream rhwp Rust CLI (export-svg/dump/dump-pages/ir-diff/thumbnail/convert).",
+  "profiles": [
+    "local"
+  ],
+  "frontmatter": "name: rhwp-advanced\ndescription: Debug HWP layout, dump document IR, compare versions, extract thumbnails, and unlock read-only HWPs with the upstream rhwp Rust CLI (export-svg/dump/dump-pages/ir-diff/thumbnail/convert).\nlicense: MIT\nmetadata:\n  category: documents\n  locale: ko-KR\n  phase: v1.5"
+}

package/skills/rhwp-edit/instruction.md

@@ -0,0 +1,153 @@
+# rhwp-edit
+
+## What this skill does
+
+`k-skill-rhwp` CLI로 `.hwp` 문서의 **본문 텍스트**, **표 구조**, **셀 내용**을 round-trip 안전하게 수정한다.
+CLI는 `@rhwp/core`(Rust + WebAssembly) 위에 얇은 Node 래퍼를 씌워 `insertText`, `deleteText`, `replaceAll`,
+`createTable`, `setCellText` 같은 편집 동작을 서브커맨드로 노출한다. 결과는 항상 새 파일로 저장한다.
+
+이 스킬은 **편집 전용**이다. 문서를 Markdown/JSON으로 변환하거나 필드만 추출하려면 [`hwp`](../hwp/SKILL.md) 스킬을 사용한다.
+페이지 렌더링 디버깅이나 IR 비교가 필요하면 [`rhwp-advanced`](../rhwp-advanced/SKILL.md) 스킬을 사용한다.
+
+## When to use
+
+- "HWP 본문에 한 줄 추가해줘"
+- "서식은 유지한 채로 2025를 2026으로 일괄 치환해줘"
+- "3행 4열짜리 표를 HWP에 넣어줘"
+- "표의 특정 셀 내용을 바꿔줘"
+- "빈 HWP 새 파일을 만들어줘"
+
+## When not to use
+
+- **HWP → Markdown / JSON 변환** → `hwp` 스킬(kordoc)을 쓴다. rhwp-edit은 바이너리 편집 전용이다.
+- **HWPX 원본을 다시 HWPX로 저장** → rhwp v0.7.3 기준 업스트림이 `#196`으로 HWPX 저장 경로를 막아둔 상태다.
+  HWPX를 입력으로 주면 내부적으로 HWP IR로 올라온 뒤 **HWP 5.x 바이너리로만** 저장된다. HWPX 출력이 꼭 필요하면 kordoc `markdownToHwpx`를 쓴다.
+- **레이아웃(페이지네이션·SVG 렌더) 디버깅** → `rhwp-advanced` 스킬로 업스트림 `rhwp` CLI(`export-svg --debug-overlay`, `dump-pages`, `ir-diff`)를 사용한다.
+- **배포용(읽기전용) 잠금 해제 · IR 구조 덤프 · 썸네일 추출 등 고급 검사 명령** → `rhwp-advanced` 스킬 참조.
+- **한컴 오피스 GUI 자동화, 보안모듈 통과, Windows 전용 서식** → 범위 밖이다. `rhwp`는 파일 포맷 엔진이지 GUI 제어가 아니다.
+
+## Prerequisites
+
+- Node.js 18+
+- 쓰기 권한이 있는 출력 경로
+- `k-skill-rhwp` 설치(셋 중 하나):
+  - 일회성: `npx --yes k-skill-rhwp --help`
+  - 전역: `npm install -g k-skill-rhwp`
+  - 로컬: `npm install k-skill-rhwp`
+- `k-skill-rhwp`는 `@rhwp/core@^0.7.3`을 peer 없이 dependency로 끌어온다. 별도 설치 불필요.
+- Rust/Cargo toolchain 불필요. 업스트림 `rhwp` CLI를 같이 쓰고 싶으면 `rhwp-advanced` 스킬로.
+
+## Inputs
+
+- 입력 HWP / HWPX 경로 (절대 또는 상대)
+- 출력 HWP 경로 (항상 별도 파일. 원본을 덮어쓰지 않는다.)
+- 편집 좌표: `--section N --paragraph N --offset N`
+- 표 좌표: `--section N --parent-paragraph N --control N --cell N [--cell-paragraph N]`
+- 텍스트/쿼리: `--text "..."`, `--query "..."`, `--replacement "..."`
+- `create-table`: `--rows N --cols N`
+- 선택 플래그: `--case-sensitive`, `--no-replace` (`set-cell-text` 에서 기존 셀 내용 보존), `--format svg|html` (`render`)
+
+## Routing policy
+
+| 작업 | 기본 경로 |
+| --- | --- |
+| 본문 문단에 텍스트 삽입 | `k-skill-rhwp insert-text` |
+| 본문 문단에서 텍스트 삭제 | `k-skill-rhwp delete-text` |
+| 단순 전체 치환(같은 서식 유지, **본문 문단만**) | `k-skill-rhwp replace-all --query ... --replacement ...` |
+| 치환 대상 위치 사전 조회(**본문 문단만**) | `k-skill-rhwp search --query ... --from-section N --from-paragraph N` |
+| 표 셀 안의 텍스트 확인 | `k-skill-rhwp list-paragraphs` + 셀 좌표 확인 후 `k-skill-rhwp set-cell-text` 로 직접 쓰기 |
+| 빈 표 삽입 | `k-skill-rhwp create-table --rows N --cols N` |
+| 표 셀 내용 교체/채우기 | `k-skill-rhwp set-cell-text --control N --cell N --text "..."` |
+| 빈 HWP 생성 | `k-skill-rhwp create-blank <output.hwp>` |
+| 구조 파악(섹션/문단 수·길이) | `k-skill-rhwp info <file>` / `list-paragraphs` |
+| 페이지 SVG/HTML 미리보기 | `k-skill-rhwp render <file> --page N --format svg` |
+
+모든 편집 서브커맨드는 결과를 JSON 한 줄(CLI에서는 pretty-print)로 돌려준다. `ok: true`, 새 커서 위치(`charOffset`, `paraIdx`, `controlIdx`),
+저장된 바이트 수(`bytesWritten`), 출력 경로(`outputPath`) 를 포함한다.
+
+## Workflow
+
+1. **입력 점검**: `k-skill-rhwp info <input>` 로 `sourceFormat`(hwp/hwpx), `sectionCount`, 섹션별 `paragraphCount`, 문단별 `length` 를 먼저 확인한다. 편집 좌표는 이 결과에서 뽑는다.
+2. **검색이 필요한 경우**: `k-skill-rhwp search <input> --query "2025"` 로 섹션/문단/문자 오프셋을 먼저 얻고, 편집 명령에 그대로 넣는다.
+3. **편집**: 아래 예시 중 해당하는 서브커맨드 하나로 실행한다. `--output` 은 항상 원본과 다른 경로를 지정한다.
+
+   ```bash
+   # 빈 문서 만들기
+   npx k-skill-rhwp create-blank ./out/blank.hwp
+
+   # 본문 첫 문단 앞에 제목 삽입
+   npx k-skill-rhwp insert-text ./in.hwp ./out/with-title.hwp \
+     --section 0 --paragraph 0 --offset 0 \
+     --text "2026년 오픈소스 AI·SW 지원사업 신청서"
+
+   # 2025 → 2026 일괄 치환
+   npx k-skill-rhwp replace-all ./in.hwp ./out/2026.hwp \
+     --query 2025 --replacement 2026
+
+   # 3행 4열 표 삽입(본문 2번째 문단 끝)
+   npx k-skill-rhwp create-table ./in.hwp ./out/with-table.hwp \
+     --section 0 --paragraph 1 --offset 0 --rows 3 --cols 4
+
+   # 방금 만든 표의 (0,0) 셀에 "합계" 삽입
+   #  - create-table 결과의 paraIdx / controlIdx 를 그대로 재사용
+   npx k-skill-rhwp set-cell-text ./out/with-table.hwp ./out/with-cell.hwp \
+     --section 0 --parent-paragraph <paraIdx> --control <controlIdx> \
+     --cell 0 --text "합계"
+   ```
+
+4. **round-trip 검증**: 편집 직후 `k-skill-rhwp info <output>` 를 다시 호출하고, 기대한 `paragraphs[].length` 또는 `paragraphCount` 변화를 직접 눈으로 확인한다.
+   필요하면 `k-skill-rhwp render <output> --page 0 --format html` 로 첫 페이지 렌더 문자열이 생성되는지 sanity check 한다.
+5. **민감 원본 보호**: 편집 대상이 개인정보/사업 신청서 등 비공개 문서라면 생성 파일을 레포에 커밋하지 않고, 로그에 남길 때도 본문을 요약·마스킹한다.
+
+## Node API (선택)
+
+CLI가 아니라 Node 코드에서 직접 편집하고 싶으면 같은 패키지를 라이브러리로 쓴다.
+
+```js
+const { insertText, getDocumentInfo } = require("k-skill-rhwp");
+
+await insertText({
+  input: "./in.hwp",
+  output: "./out.hwp",
+  section: 0,
+  paragraph: 0,
+  offset: 0,
+  text: "안녕하세요"
+});
+console.log(await getDocumentInfo("./out.hwp"));
+```
+
+Node 18+, `@rhwp/core` WASM 은 첫 호출 시 한 번만 초기화된다. WASM 이 요구하는 `globalThis.measureTextWidth` 콜백은 자동 shim 되므로 별도 설정 없이 돌아간다(정밀 레이아웃이 필요하면 `node-canvas` 기반 shim을 먼저 주입한다).
+
+## Verify outputs after every run
+
+- `ok === true`, `bytesWritten` 가 수 KB 이상.
+- `info` 재호출 결과에서 섹션/문단 수·길이 변화가 의도와 일치.
+- 표 삽입의 경우 `paraIdx`/`controlIdx` 가 다음 `set-cell-text` 호출에 그대로 들어간다.
+- 출력 파일이 원본과 다른 경로이며 원본은 그대로다.
+
+## Done when
+
+- 사용자가 요청한 편집이 HWP 바이너리에 반영되어 새 파일로 저장됐다.
+- `k-skill-rhwp info <output>` 가 같은 혹은 늘어난 `sectionCount`/`paragraphCount` 와 기대 `length` 를 돌려준다.
+- 원본 파일은 건드리지 않았다.
+
+## Failure modes
+
+- **HWPX 원본 저장 불가(rhwp #196)**: HWPX → HWPX round-trip 은 upstream에서 비활성화 상태다. HWPX 입력이라도 출력은 HWP로만 저장된다. 원본 확장자에 의존하지 말고 항상 `.hwp` 로 저장한다.
+- **좌표 범위 초과**: `section/paragraph/offset` 이 실제 문서 범위를 벗어나면 WASM에서 `렌더링 오류: 구역 인덱스 0 범위 초과` 같은 에러를 던지고 CLI는 exit code 1 + stderr 에 메시지를 찍는다. 편집 전에 `info` 로 좌표를 확인한다.
+- **복잡한 표·이미지·양식 필드 round-trip**: 현재 업스트림 rhwp v0.7.x 는 베타다. 복잡한 표·이미지·차트·양식필드가 많은 실제 사업 신청서를 HWP round-trip 할 경우 드물게 형식 손실이 발생할 수 있다. round-trip 이 끝나면 `k-skill-rhwp render <output>` + 육안 확인을 권장한다.
+- **배포용(읽기전용) 문서**: rhwp 자체는 `convertToEditable` 로 잠금 해제를 지원하지만 `k-skill-rhwp` CLI 서브커맨드는 아직 노출하지 않는다. 필요하면 `rhwp-advanced` 스킬의 업스트림 `rhwp convert` 경로를 쓴다.
+- **WASM 초기화**: `@rhwp/core` 번들 WASM(~4 MB) 은 최초 호출 시 한 번 파싱한다. 첫 호출은 수십 ms~수백 ms 지연될 수 있다.
+- **파일 인코딩**: 한국어 텍스트는 UTF-8 로 그대로 CLI 에 넘기면 된다. 셸에서 인용부호가 깨질 경우 `--text=$'...'` 같은 형식을 쓴다.
+- **`search` / `replace-all` 은 본문 문단만 스캔한다**: 업스트림 `searchText` 가 본문(body) 범위로 제한되어 있고, `k-skill-rhwp replace-all` 도 같은 스코프를 그대로 따른다. **표(cell) 안의 텍스트, 머리말/꼬리말, 각주 본문**에서는 `search` 가 `found:false` 를 돌려주고 `replace-all` 도 해당 위치를 건드리지 않는다. 셀 내용이 대상이라면 `list-paragraphs` 또는 `info` 로 표 좌표를 잡고 `set-cell-text` 로 직접 쓴다.
+- **문단 경계 / 개행 치환 금지**: `replace-all` 은 한 문단 안에서의 치환만 보장한다. `--replacement` 에 개행(`\n`, `\r`, U+2028, U+2029) 이 들어오면 CLI 는 exit code 1 과 "replacement must not contain newline or paragraph-break characters" 메시지를 돌려준다. 여러 문단을 만들고 싶으면 `insert-text` 를 여러 번 호출한다.
+- **치환은 원본 매칭 기준 non-overlapping**: 예를 들어 query `a` / replacement `aa` / 원본 `aaa` 는 원본의 각 `a` 를 한 번씩 교체해 `aaaaaa` 가 된다. 치환으로 새로 들어온 문자열은 다시 매칭하지 않는다.
+- **대소문자 무시 매칭은 UTF-16 길이가 보존되는 문자에만 안전하다**: 기본값인 대소문자 무시(`--case-sensitive` 없이) 모드는 `String.prototype.toLowerCase()` 가 UTF-16 길이를 그대로 유지한다는 전제 위에서 오프셋을 계산한다. 터키어 `İ`(U+0130) 처럼 소문자화 시 `i` + 결합 점(U+0307) 로 길이가 늘어나는 문자가 본문 또는 쿼리에 포함되면, 조용한 문서 손상을 방지하기 위해 `replace-all` 이 exit code 1 과 함께 `case-insensitive matching is unsafe because case folding changes the UTF-16 length` 메시지를 돌려준다. 이런 문서에는 `--case-sensitive` 로 다시 실행하거나, 입력을 미리 정규화한다. 한글·ASCII 본문에는 해당하지 않으며, `2025 → 2026` 같은 실제 사업 신청서 워크플로우는 아무 영향을 받지 않는다.
+
+## Notes
+
+- 업스트림 rhwp: https://github.com/edwardkim/rhwp
+- 업스트림 `@rhwp/core` npm: https://www.npmjs.com/package/@rhwp/core
+- 업스트림은 활발히 개발 중이다(v0.7.3 2026-04-19 기준). breaking change 가능성을 고려해 `k-skill-rhwp` dependency 는 semver caret 으로 고정한다.
+- 이 스킬은 **편집 전용** 스킬이다. 조회/변환은 `hwp`, 고급 디버깅은 `rhwp-advanced` 가 담당한다.

package/skills/rhwp-edit/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "rhwp-edit",
+  "description": "Edit HWP documents — insert/delete text, replace-all, create tables, set cell text — with the k-skill-rhwp CLI that wraps the @rhwp/core WASM engine (rhwp by Edward Kim).",
+  "profiles": [
+    "local"
+  ],
+  "frontmatter": "name: rhwp-edit\ndescription: Edit HWP documents — insert/delete text, replace-all, create tables, set cell text — with the k-skill-rhwp CLI that wraps the @rhwp/core WASM engine (rhwp by Edward Kim).\nlicense: MIT\nmetadata:\n  category: documents\n  locale: ko-KR\n  phase: v1.5"
+}