@nomadamas/k-skill 0.1.0

package/skills/hwp/instruction.md

@@ -0,0 +1,206 @@
+# HWP
+
+## What this skill does
+
+`kordoc`으로 `.hwp` / `.hwpx` / `.hwpml` 문서를 AI가 읽기 좋은 Markdown 또는 JSON으로 바꾸고,
+필요하면 문서 비교, 양식 필드 추출, Markdown→HWPX 역변환까지 수행한다.
+
+이 스킬의 기본 엔진은 **항상 `kordoc`** 이다. 문서 변환, 비교, 필드 추출, 역변환까지 같은 도구로 일관되게 처리한다.
+
+> **스킬 라우팅** — 이 `hwp` 스킬은 **조회/변환(read-only)** 전용이다.
+> HWP 바이너리 **편집**(본문 텍스트 삽입/삭제, 표 생성, 셀 수정, replace-all)은 [`rhwp-edit`](../rhwp-edit/SKILL.md) 스킬이,
+> 레이아웃 디버깅·IR 덤프·썸네일·배포용 문서 잠금 해제 같은 **고급 검사**는 [`rhwp-advanced`](../rhwp-advanced/SKILL.md) 스킬이 맡는다.
+
+## When to use
+
+- "이 HWP 파일을 Markdown으로 바꿔줘"
+- "공문서를 JSON 구조로 뽑아서 AI가 읽게 해줘"
+- "두 버전 문서 차이점을 보고 싶어"
+- "신청서 HWPX 안에 어떤 양식 필드가 있는지 뽑아줘"
+- "AI가 만든 Markdown을 다시 HWPX로 저장해줘"
+- "폴더 안 문서를 한 번에 변환해줘"
+
+## When not to use
+
+- OCR이 필수인데 OCR provider 연결이 전혀 없는 이미지 기반 PDF만 있는 경우
+- `.docx`, `.xlsx`, `.pdf` 만 다루더라도 문서 파싱 자체가 아니라 편집기 GUI 자동화가 필요한 경우
+- 원본 프로그램의 실시간 UI 제어가 반드시 필요한 경우
+- **본문 텍스트 직접 삽입·삭제·치환 또는 표 구조 변경** — `rhwp-edit` 스킬의 `k-skill-rhwp` CLI 를 사용한다.
+- **페이지 SVG 렌더 디버깅·IR 덤프·ir-diff·썸네일 추출** — `rhwp-advanced` 스킬의 업스트림 `rhwp` CLI 를 사용한다.
+
+## Prerequisites
+
+- Node.js 18+
+- 출력 경로 쓰기 권한
+- `kordoc`과 `pdfjs-dist`를 같은 전역/로컬 환경에 설치했거나, 둘 다 포함된 `npx --yes --package kordoc --package pdfjs-dist kordoc ...` 실행 환경
+- 현재 배포된 `kordoc` CLI는 시작 시 `pdfjs-dist`를 바로 로드하므로 PDF를 안 써도 함께 설치해야 한다
+
+## Inputs
+
+- 원본 `.hwp`, `.hwpx`, `.hwpml` 파일 경로 또는 폴더/글롭 경로
+- 원하는 결과 형태: `markdown`, `json`, `hwpx`
+- 출력 파일/디렉터리 경로
+- 페이지 범위 지정 여부
+- 비교 / 양식 필드 추출 / 역변환 여부
+
+## Routing policy
+
+### Default: `kordoc`
+
+다음 작업은 모두 기본적으로 `kordoc`으로 처리한다.
+
+- HWP/HWPX/HWPML → Markdown
+- HWP/HWPX/HWPML → JSON (`blocks`, `metadata`)
+- 배치 변환
+- 페이지 범위 파싱
+- 이미지/표/양식이 포함된 공문서 구조 추출
+- 디렉터리 감시 변환 (`watch`)
+- Markdown→HWPX 역변환
+- HWPX 양식 필드 추출
+
+### Optional library path
+
+CLI만으로 부족하면 Node API를 사용한다.
+
+- `parse()` — Markdown + 구조화 블록
+- `compare()` — 신구 문서 비교
+- `extractFormFields()` — 파싱된 블록에서 양식 필드 추출
+- `markdownToHwpx()` — Markdown→HWPX 역변환
+
+## Workflow
+
+### 1. Prepare the CLI runtime
+
+일회성 변환이면 둘 다 포함한 `npx` 형태를 바로 쓴다.
+
+```bash
+npx --yes --package kordoc --package pdfjs-dist kordoc --help
+```
+
+반복 실행용 전역 설치가 필요하면:
+
+```bash
+npm install -g kordoc pdfjs-dist
+```
+
+현재 배포된 `kordoc` CLI는 `pdfjs-dist`가 없으면 `kordoc --help` 단계부터 실패하므로
+깨끗한 환경에서는 두 패키지를 같이 설치한 뒤 실행한다.
+
+### 2. Prepare a local project for Node API examples
+
+`parse()`, `compare()`, `extractFormFields()`, `markdownToHwpx()` 같은 ESM 예시는
+전역 `NODE_PATH`가 아니라 **로컬 프로젝트 설치** 기준으로 실행한다.
+
+```bash
+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 --yes --package kordoc --package pdfjs-dist kordoc ./문서함/* -d ./변환결과
+```
+
+특정 페이지 범위만 읽고 싶으면:
+
+```bash
+npx --yes --package kordoc --package pdfjs-dist kordoc 보고서.hwp --pages 1-3
+```
+
+### 4. Extract structured JSON for AI/automation
+
+```bash
+npx --yes --package kordoc --package pdfjs-dist kordoc 검토서.hwpx --format json > 검토서.json
+```
+
+JSON 결과에서는 `success`, `markdown`, `blocks`, `metadata`를 우선 확인한다.
+표나 이미지가 중요하면 `blocks` 안의 `table`, `image` 타입을 확인한다.
+
+### 5. Inspect HWPX form fields from parsed blocks
+
+```bash
+node --input-type=module - <<'EOF'
+import { parse, extractFormFields } from "kordoc";
+
+const result = await parse("신청서.hwpx");
+if (!result.success) {
+  console.error(result.error);
+  process.exit(1);
+}
+
+const fields = extractFormFields(result.blocks);
+console.log(JSON.stringify(fields, null, 2));
+EOF
+```
+
+자동 변환이 계속 들어오는 폴더면 CLI의 `watch` 명령을 쓴다.
+
+```bash
+npx --yes --package kordoc --package pdfjs-dist kordoc watch ./문서함
+```
+
+### 6. Reverse-convert Markdown back to HWPX
+
+```bash
+node --input-type=module - <<'EOF'
+import { markdownToHwpx } from "kordoc";
+import { writeFileSync } from "node:fs";
+
+const hwpx = await markdownToHwpx("# 제목\n\n본문\n\n| 항목 | 값 |\n| --- | --- |\n| 성명 | 홍길동 |");
+writeFileSync("출력.hwpx", Buffer.from(hwpx));
+EOF
+```
+
+### 7. Compare two document versions when diff matters
+
+```bash
+node --input-type=module - <<'EOF'
+import { compare } from "kordoc";
+import { readFileSync } from "node:fs";
+
+const before = readFileSync("이전버전.hwp");
+const after = readFileSync("최신버전.hwpx");
+const diff = await compare(before, after);
+console.log(diff.stats);
+EOF
+```
+
+## Verify outputs after every run
+
+- Markdown: 파일이 생성되었고 제목/본문/표 구조가 깨지지 않았는지 확인
+- JSON: `success: true` 와 `blocks` / `metadata` 존재 여부 확인
+- 배치 처리: 입력 수와 출력 수가 크게 어긋나지 않는지 확인
+- 양식 필드 추출: `extractFormFields(result.blocks)` 결과가 비어 있지 않은지 확인
+- 역변환: 생성된 `.hwpx` 파일이 열리고 기본 서식/테이블 구조가 유지되는지 확인
+- 비교: `diff.stats` 에 added / removed / modified 값이 합리적인지 확인
+
+## Done when
+
+- 요청한 Markdown / JSON / HWPX 결과물이 생성되어 있다
+- 공문서 표·이미지·메타데이터가 필요한 수준으로 확인되어 있다
+- 양식 필드 추출이나 역변환 요청이 있었다면 결과/출력 구조까지 검증되어 있다
+- 배치 요청이면 처리 범위와 실패 건수가 정리되어 있다
+
+## Failure modes
+
+- 손상된 HWP/HWPX/HWPML 파일
+- 암호화/배포 제한 문서에서 일부 파싱 한계 발생
+- 이미지 기반 PDF인데 OCR provider가 없음
+- 출력 디렉터리 권한 부족
+- 양식 라벨이 템플릿 안에서 예상과 다르게 배치되어 일부 필드가 인식되지 않음
+
+## Notes
+
+- `kordoc`은 HWP/HWPX뿐 아니라 HWPML, PDF, XLSX, DOCX도 함께 다룬다.
+- 기본 목적은 **AI가 읽을 수 있는 Markdown/JSON 변환** 이다.
+- 현재 배포본 기준으로 문서화된 CLI 명령은 기본 변환과 `watch` 이며, 양식 처리는 `extractFormFields()` 같은 Node API로 연결한다.

package/skills/hwp/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "hwp",
+  "description": "Use kordoc for agent-native HWP/HWPX document parsing, JSON extraction, diffing, form-field extraction, and Markdown→HWPX reverse conversion (read/convert only — for binary editing use rhwp-edit).",
+  "profiles": [
+    "local"
+  ],
+  "frontmatter": "name: hwp\ndescription: Use kordoc for agent-native HWP/HWPX document parsing, JSON extraction, diffing, form-field extraction, and Markdown→HWPX reverse conversion (read/convert only — for binary editing use rhwp-edit).\nlicense: MIT\nmetadata:\n  category: documents\n  locale: ko-KR\n  phase: v1"
+}

package/skills/intercity-bus-booking/instruction.md

@@ -0,0 +1,189 @@
+# Intercity Bus Booking (Tmoney 시외버스)
+
+## Overview
+
+Use this skill for Korean 시외버스 timetable lookup and reservation assistance via the official Tmoney intercity bus site. Prefer HTTP/API-first flows for route lookup, timetable search, fare/seat-stage entry, and checkout-entry handoff.
+
+Keep 시외버스 separate from 고속버스. Tmoney terminal codes and POST flows are different from KOBUS 고속버스. Use `express-bus-booking` for KOBUS routes.
+
+## When to Use
+
+- The user asks for `시외버스 예매`, `시외버스 시간표`, `시외버스 예약`, or a known 시외버스 route.
+- The user names 티머니/Tmoney/시외버스 통합예매.
+- The task is to present timetable candidates, check remaining seats/fares, or assist up to the official card-information page.
+
+Do **not** use this for:
+
+- 고속버스/KOBUS routes — use `express-bus-booking`.
+- Final card submission or payment unless the user explicitly confirms the exact action.
+- Browser automation as the first option when HTTP endpoints are available.
+
+## Core Principles
+
+- Use official Tmoney 시외버스 surfaces: `https://intercitybus.tmoney.co.kr`.
+- Use cookies, referers, and a normal browser User-Agent.
+- Default scope is lookup and assisted manual checkout: timetable, fare/seat stage, selected-seat temporary hold, and official card-information page handoff.
+- Do not submit card fields, final payment, or irreversible reservation steps without explicit confirmation.
+- If a test or user-abandoned hold is created, use the official cancellation/back flow when available.
+
+## Known HTTP Flow
+
+See `references/tmoney-intercity-http-flow.md` for session-proven endpoint details and parameter examples.
+
+### 1. Start a Session
+
+Fetch a landing or booking-entry page with cookies enabled:
+
+```text
+GET https://intercitybus.tmoney.co.kr/
+GET https://intercitybus.tmoney.co.kr/otck/trmlInfEnty.do
+```
+
+### 2. Query Timetable
+
+```text
+POST /otck/readAlcnList.do
+```
+
+Typical fields include:
+
+```text
+depr_Trml_Cd=0511601
+arvl_Trml_Cd=2482701
+depr_Trml_Nm=동서울
+arvl_Trml_Nm=속초
+ig=1
+im=0
+ic=0
+iv=0
+depr_Dt=YYYYMMDD
+depr_Time=000000
+bef_Aft_Dvs=D
+req_Rec_Num=10
+```
+
+`bef_Aft_Dvs` and `req_Rec_Num` are required hidden fields from the browser JavaScript `readAlcnListEntry(...)`. If they are omitted, Tmoney can return a generic error page with no schedules.
+
+Parse schedule buttons/rows. The next-stage parameters are often embedded in `readSasFeeInf(...)` onclick arguments.
+
+### 3. Enter Fare / Seat-Count Stage
+
+```text
+POST /otck/readSatsFee.do
+```
+
+Send selected values from `readSasFeeInf(...)` plus passenger counts and original search fields. The response should include `form#readPcpySats` and hidden values such as:
+
+```text
+rot_Id
+alcn_Sqno
+depr_Trml_Cd
+arvl_Trml_Cd
+depr_Time
+igFee
+imFee
+icFee
+total
+```
+
+### 4. Temporary Hold and Card-Information Entry
+
+```text
+POST /otck/readPcpySats.do
+```
+
+Submit the `readPcpySats` hidden fields plus selected seat/count fields, commonly including:
+
+```text
+pcpy_Num
+sats_No
+bus_Tck_Knd_Cd
+cty_Bus_Dc_Knd_Cd
+dcrt_Dvs_Cd
+rtrp_Depr_Dt
+```
+
+A successful response lands on the official `카드정보 입력` page and includes a temporary seat hold identifier such as `sats_Pcpy_Id`.
+
+## Timetable Helper
+
+For read-only timetable lookup, use the bundled helper before attempting browser automation:
+
+```bash
+python3 intercity-bus-booking/scripts/intercity_bus_search.py \
+  --depart-code 0511601 \
+  --arrive-code 2482701 \
+  --depart-name 동서울 \
+  --arrive-name 속초 \
+  --date 20260520
+```
+
+The helper starts a cookie-backed session, posts the browser-required timetable fields, parses `readSasFeeInf(...)`, and prints JSON with departure time, company, class, fares, and remaining/total seats. By default it is read-only. With `--hold-seat <seatNo>` or `--hold-first-seat`, it enters `readSatsFee.do`, posts `readPcpySats.do`, and saves the official Tmoney card-information HTML page plus cancel/back fields. It still never submits card data or final payment.
+
+### Temporary Hold Helper
+
+To create a temporary hold and save the official card-information page:
+
+```bash
+python3 intercity-bus-booking/scripts/intercity_bus_search.py \
+  --depart-code 0511601 \
+  --arrive-code 2482701 \
+  --depart-name 동서울 \
+  --arrive-name 속초 \
+  --date 20260520 \
+  --select-index 1 \
+  --hold-first-seat \
+  --output-dir /tmp/tmoney-hold
+```
+
+Success requires `hold.success=true`, a `sats_Pcpy_Id`, and the saved page containing `카드정보 입력`. The saved cancel fields can be posted back to `/otck/readSatsFee.do` with `pcpyCanc=C` to abandon the hold. Live probes did not expose an exact countdown on the card-information page; treat the hold as short-lived and have the user complete payment immediately.
+
+## Checkout-Entry Link Helper
+
+A helper-served HTML page can auto-submit a POST form directly to:
+
+```text
+https://intercitybus.tmoney.co.kr/otck/readPcpySats.do
+```
+
+This creates the hold in the user's browser/session and opens the official Tmoney card-information page. The user should manually finish payment on the official page.
+
+For Discord/mobile, provide helper links as normal text links rather than fenced code blocks so the user can tap them.
+
+## Mobile and In-App Browser Notes
+
+Tmoney 시외버스 is more mobile-tolerant than KOBUS in the tested flow: an iPhone Safari-style mobile User-Agent returned the official `카드정보 입력` page with `sats_Pcpy_Id` present.
+
+However, in-app browser User-Agents can behave differently or fail if the same seat/hold payload is replayed. If a Discord/Android in-app test returns a generic error such as `발행을 실패하였습니다`, do not assume route lookup is broken. Recreate a fresh hold payload, retry once in an external browser, and cancel stale holds.
+
+## Suggested Output Format
+
+Keep candidate lists concise:
+
+```text
+시외버스 동서울 → 속초 / 2026-05-09
+1. 06:05 우등 / 금강고속 / 잔여 8석 / 성인 21,300원
+2. ...
+```
+
+When a checkout-entry helper is created, say that it opens the official Tmoney card-information page and that payment remains manual.
+
+## Common Pitfalls
+
+1. **Mixing terminal code systems.** Tmoney 시외버스 codes are not KOBUS codes.
+2. **Assuming checkout-entry equals final payment.** `readPcpySats.do` can open the card-information page, but final payment remains a separate manual step.
+3. **Omitting hidden timetable fields.** `readAlcnList.do` needs `bef_Aft_Dvs=D` and `req_Rec_Num=10`; without them it may return a generic `errorCont` page of about 13 KB instead of schedule rows.
+4. **Replaying stale hold payloads.** A repeated POST for the same route/seat can fail or create confusing results. Generate a fresh seat-stage payload for real use.
+5. **Skipping cancellation/back flow.** Use the official cancellation/back form (`pcpyCanc=C` via `readSatsFee.do` when available) for abandoned holds.
+6. **Overusing browser automation.** Use browser only for endpoint discovery or visual verification after HTTP probing.
+
+## Verification Checklist
+
+- [ ] Route/terminal codes were resolved from Tmoney 시외버스, not guessed or copied from KOBUS.
+- [ ] Timetable POST included `bef_Aft_Dvs=D` and `req_Rec_Num=10`.
+- [ ] Timetable response was parsed for schedule rows/buttons and next-stage parameters.
+- [ ] Fare/seat-stage response contains `form#readPcpySats` and expected hidden fields.
+- [ ] Checkout-entry response contains `카드정보 입력` and a hold identifier such as `sats_Pcpy_Id` before reporting success.
+- [ ] Stale/test holds were released through the official cancellation/back flow where possible.
+- [ ] Payment/card submission was left to the user unless explicitly confirmed.
+- [ ] Mobile links are provided as tappable text links on Discord/mobile platforms.

package/skills/intercity-bus-booking/references/tmoney-intercity-http-flow.md

@@ -0,0 +1,126 @@
+# Tmoney 시외버스 HTTP/API Probe Notes
+
+Session-proven on 2026-05-08 and re-verified on 2026-05-13. Goal: avoid browser automation where possible.
+
+## Base
+
+```text
+https://intercitybus.tmoney.co.kr
+```
+
+Use a normal browser User-Agent, cookie jar, and referers.
+
+## Tested Flow
+
+### Timetable
+
+```text
+POST /otck/readAlcnList.do
+```
+
+Example tested route/date:
+
+```text
+동서울(0511601) -> 속초(2482701), 2026-05-09
+```
+
+Observed results:
+
+```text
+2026-05-09: 14 reservation buttons/schedules
+2026-05-20: 20 readSasFeeInf schedule buttons, first departure 06:05 금강고속 우등, 24/28 seats
+```
+
+Typical POST fields:
+
+```text
+depr_Trml_Cd=0511601
+arvl_Trml_Cd=2482701
+depr_Trml_Nm=동서울
+arvl_Trml_Nm=속초
+ig=1
+im=0
+ic=0
+iv=0
+depr_Dt=YYYYMMDD
+depr_Time=000000
+bef_Aft_Dvs=D
+req_Rec_Num=10
+```
+
+`bef_Aft_Dvs=D` and `req_Rec_Num=10` are not optional. They are appended by the site JavaScript (`readAlcnListEntry(bef_Aft_Dvs, req_Rec_Num)`) before the browser submits `#onewayInfo`. Omitting them returned a generic error page (`errorCont`, about 13,770 bytes) with no `readSasFeeInf(...)` schedules in live probing.
+
+The next-stage values are embedded in `readSasFeeInf(...)` onclick calls. Example prefix:
+
+```text
+readSasFeeInf('RT201603150047276','1','20260509','1','0511601','2482701','동서울','속초','060500','C004','IDP','금강고속','우등','1','0','0','8','28', ...)
+```
+
+### Fare / Seat-Count Stage
+
+```text
+POST /otck/readSatsFee.do
+```
+
+Send selected values from `readSasFeeInf(...)` plus passenger counts and original search fields.
+
+Observed response contained `form#readPcpySats` and hidden values:
+
+```json
+{
+  "rot_Id": "RT201603150047276",
+  "alcn_Sqno": "1",
+  "depr_Trml_Cd": "0511601",
+  "arvl_Trml_Cd": "2482701",
+  "depr_Time": "060500",
+  "igFee": "21300",
+  "imFee": "17000",
+  "icFee": "10700",
+  "total": "21300"
+}
+```
+
+### Temporary Hold / Card-Information Entry
+
+```text
+POST /otck/readPcpySats.do
+```
+
+Send `readPcpySats` hidden fields plus selected seat fields:
+
+```text
+pcpy_Num
+sats_No
+bus_Tck_Knd_Cd
+cty_Bus_Dc_Knd_Cd
+dcrt_Dvs_Cd
+rtrp_Depr_Dt
+```
+
+Observed success markers:
+
+```text
+카드정보 입력
+sats_Pcpy_Id
+```
+
+Re-verified on 2026-05-13 with 동서울 -> 속초, 2026-05-20, 06:05 금강고속 우등, seat 1. `readPcpySats.do` returned `카드정보 입력` and `sats_Pcpy_Id=SP...`. Posting the resulting cancel/back fields with `pcpyCanc=C` to `/otck/readSatsFee.do` returned to the seat-selection page and subsequent timetable lookup still showed 24/28 seats.
+
+### Cancellation / Back Flow
+
+A POST back to `/otck/readSatsFee.do` with `pcpyCanc=C` and the hold fields returned to seat selection and appeared to release the temporary hold in testing.
+
+## Mobile Notes
+
+- iPhone Safari-style mobile User-Agent returned HTTP 200 with `카드정보 입력` and `sats_Pcpy_Id` present.
+- A replayed Discord/Android in-app User-Agent test returned a generic `발행을 실패하였습니다` page. Because the same seat/hold payload had already been used, treat this as a stale/replayed hold caveat rather than proof that mobile is unsupported.
+- For real use, generate a fresh hold payload, send a helper link, and ask the user to open it in an external browser if an in-app browser fails.
+
+## Interpretation
+
+- Login was not required for timetable lookup, fare/seat-stage entry, or card-information page entry in the tested flow.
+- CAPTCHA was not observed in the tested flow.
+- A generic `errorCont` response usually means the posted form contract is incomplete, not necessarily that the route is unavailable; first verify `bef_Aft_Dvs` and `req_Rec_Num`.
+- Payment/card-info submission is separate and should not be automated without explicit confirmation.
+- The live card-information page did not expose an exact countdown/expiry text in probes. Treat temporary holds as short-lived: hand off immediately, and post the cancel/back fields for abandoned holds.
+- Terminal codes are Tmoney-specific and must not be mixed with KOBUS codes.