@nomadamas/k-skill 0.1.0

package/skills/intercity-bus-booking/scripts/intercity_bus_search.py

@@ -0,0 +1,381 @@
+#!/usr/bin/env python3
+"""Search and optionally hold Tmoney intercity-bus seats through official flows.
+
+Default mode is read-only timetable parsing. With --hold-seat, the helper performs
+Tmoney's temporary seat-hold POST and saves the official card-information page.
+It never submits card fields or final payment.
+"""
+from __future__ import annotations
+
+import argparse
+import html
+import http.cookiejar
+import json
+import re
+import ssl
+import sys
+import tempfile
+import urllib.parse
+import urllib.request
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Iterable
+
+BASE_URL = "https://intercitybus.tmoney.co.kr"
+ENTRY_PATH = "/otck/trmlInfEnty.do"
+TIMETABLE_PATH = "/otck/readAlcnList.do"
+SEAT_STAGE_PATH = "/otck/readSatsFee.do"
+HOLD_PATH = "/otck/readPcpySats.do"
+DEFAULT_UA = (
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+    "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125 Safari/537.36"
+)
+
+ROW_RE = re.compile(r"<tr>\s*(.*?)readSasFeeInf\((.*?)\).*?</tr>", re.DOTALL | re.IGNORECASE)
+TD_WRAP_RE = re.compile(r'<div class="td_wrap1">(.*?)</div>', re.DOTALL | re.IGNORECASE)
+TAG_RE = re.compile(r"<[^>]+>")
+ARG_RE = re.compile(r"'((?:\\'|[^'])*)'")
+FORM_RE = re.compile(r"<form\b([^>]*)>(.*?)</form>", re.DOTALL | re.IGNORECASE)
+INPUT_RE = re.compile(r"<input\b([^>]+)>", re.DOTALL | re.IGNORECASE)
+ATTR_RE = re.compile(r"([\w:-]+)=[\"']([^\"']*)[\"']")
+SEAT_RE = re.compile(r"<li([^>]*)>\s*<a[^>]*>.*?<span>(\d+)</span>", re.DOTALL | re.IGNORECASE)
+
+
+@dataclass
+class Schedule:
+    departure_time: str | None
+    company: str | None
+    duration: str | None
+    bus_class: str | None
+    adult_fare: str | None
+    child_fare: str | None
+    student_fare: str | None
+    remaining_seats: int | None
+    total_seats: int | None
+    raw_args: list[str]
+
+
+@dataclass
+class HoldResult:
+    success: bool
+    hold_id: str | None
+    seat: str
+    card_page_path: str | None
+    cancel_fields_path: str | None
+    markers: dict[str, int]
+    failure_message: str | None = None
+
+
+def _ssl_context() -> ssl.SSLContext:
+    # Tmoney has historically required curl -k in probes on some machines.
+    # Keep this helper resilient while limiting it to the official host.
+    return ssl._create_unverified_context()  # noqa: SLF001
+
+
+def _strip(value: str) -> str:
+    value = re.sub(r"<!--.*?-->", "", value, flags=re.DOTALL)
+    value = TAG_RE.sub("", value)
+    return html.unescape(value).replace("\xa0", " ").strip()
+
+
+def _attrs(fragment: str) -> dict[str, str]:
+    return {k.lower(): html.unescape(v) for k, v in ATTR_RE.findall(fragment)}
+
+
+def _open(opener: urllib.request.OpenerDirector, request: urllib.request.Request, timeout: int) -> str:
+    with opener.open(request, timeout=timeout) as response:
+        charset = response.headers.get_content_charset() or "utf-8"
+        return response.read().decode(charset, errors="replace")
+
+
+def build_opener() -> urllib.request.OpenerDirector:
+    jar = http.cookiejar.CookieJar()
+    return urllib.request.build_opener(
+        urllib.request.HTTPCookieProcessor(jar),
+        urllib.request.HTTPSHandler(context=_ssl_context()),
+    )
+
+
+def _request(url: str, data: list[tuple[str, str]] | dict[str, str] | None = None, referer: str | None = None) -> urllib.request.Request:
+    headers = {"User-Agent": DEFAULT_UA}
+    if referer:
+        headers["Referer"] = referer
+    if data is None:
+        return urllib.request.Request(url, headers=headers, method="GET")
+    headers["Content-Type"] = "application/x-www-form-urlencoded"
+    encoded = urllib.parse.urlencode(data).encode("utf-8")
+    return urllib.request.Request(url, data=encoded, headers=headers, method="POST")
+
+
+def search_timetable(
+    depart_code: str,
+    arrive_code: str,
+    depart_name: str,
+    arrive_name: str,
+    date: str,
+    time: str = "000000",
+    adults: int = 1,
+    students: int = 0,
+    children: int = 0,
+    veterans: int = 0,
+    timeout: int = 20,
+    opener: urllib.request.OpenerDirector | None = None,
+) -> tuple[urllib.request.OpenerDirector, str, list[Schedule]]:
+    opener = opener or build_opener()
+    _open(opener, _request(f"{BASE_URL}{ENTRY_PATH}"), timeout)
+
+    fields = {
+        "depr_Trml_Cd": depart_code,
+        "arvl_Trml_Cd": arrive_code,
+        "depr_Trml_Nm": depart_name,
+        "arvl_Trml_Nm": arrive_name,
+        "ig": str(adults),
+        "im": str(students),
+        "ic": str(children),
+        "iv": str(veterans),
+        "depr_Dt": date,
+        "depr_Time": time,
+        # Required by the browser JS readAlcnListEntry(). Missing either field
+        # returns a generic error page with no schedule rows.
+        "bef_Aft_Dvs": "D",
+        "req_Rec_Num": "10",
+    }
+    body = _open(opener, _request(f"{BASE_URL}{TIMETABLE_PATH}", fields, f"{BASE_URL}{ENTRY_PATH}"), timeout)
+    return opener, body, parse_schedules(body)
+
+
+def parse_schedules(body: str) -> list[Schedule]:
+    schedules: list[Schedule] = []
+    for row_html, arg_text in ROW_RE.findall(body):
+        args = [a.replace("\\'", "'") for a in ARG_RE.findall(arg_text)]
+        cells = [_strip(x) for x in TD_WRAP_RE.findall(row_html)]
+        departure = cells[0] if len(cells) > 0 else (args[8][:2] + ":" + args[8][2:4] if len(args) > 8 else None)
+        company_cell = cells[1] if len(cells) > 1 else None
+        company = args[11] if len(args) > 11 else None
+        duration = None
+        if company_cell and company and company_cell.startswith(company):
+            duration = company_cell[len(company):].strip() or None
+        elif company_cell:
+            duration = company_cell
+        bus_class = args[12] if len(args) > 12 else (cells[2] if len(cells) > 2 else None)
+        remaining = int(args[16]) if len(args) > 16 and args[16].isdigit() else None
+        total = int(args[17]) if len(args) > 17 and args[17].isdigit() else None
+        schedules.append(
+            Schedule(
+                departure_time=departure,
+                company=company,
+                duration=duration,
+                bus_class=bus_class,
+                adult_fare=cells[3] if len(cells) > 3 else None,
+                child_fare=cells[4] if len(cells) > 4 else None,
+                student_fare=cells[5] if len(cells) > 5 else None,
+                remaining_seats=remaining,
+                total_seats=total,
+                raw_args=args,
+            )
+        )
+    return schedules
+
+
+def _seat_stage_fields(schedule: Schedule, search_time: str) -> dict[str, str]:
+    a = schedule.raw_args
+    if len(a) < 21:
+        raise ValueError("schedule raw_args does not contain the expected readSasFeeInf payload")
+    return {
+        "atl_Depr_Dt_S1": a[2],
+        "atl_Depr_Time_S1": search_time,
+        "rot_Id": a[0],
+        "rot_Sqno": a[1],
+        "alcn_Dt": a[2],
+        "alcn_Sqno": a[3],
+        "depr_Trml_Cd": a[4],
+        "arvl_Trml_Cd": a[5],
+        "depr_Trml_Nm": a[6],
+        "arvl_Trml_Nm": a[7],
+        "depr_Time": a[8],
+        "bus_Cacm_Cd": a[9],
+        "bus_Cls_Cd": a[10],
+        "bus_Cacm_Nm": a[11],
+        "bus_Cls_Nm": a[12],
+        "ig": a[13],
+        "im": a[14],
+        "ic": a[15],
+        "rmn_Scnt": a[16],
+        "sats_Num": a[17],
+        "atl_Depr_Dt": a[18],
+        "atl_Depr_Time": a[19],
+        "dc_Psb_Yn": a[20],
+    }
+
+
+def _form_fields(body: str, form_id: str) -> list[tuple[str, str]]:
+    for attrs_text, form_body in FORM_RE.findall(body):
+        attrs = _attrs(attrs_text)
+        if attrs.get("id") == form_id or attrs.get("name") == form_id:
+            fields: list[tuple[str, str]] = []
+            for input_text in INPUT_RE.findall(form_body):
+                input_attrs = _attrs(input_text)
+                name = input_attrs.get("name")
+                if name:
+                    fields.append((name, input_attrs.get("value", "")))
+            return fields
+    return []
+
+
+def _available_seats(seat_stage_body: str) -> list[str]:
+    seats: list[str] = []
+    for li_attrs, seat_no in SEAT_RE.findall(seat_stage_body):
+        classes = _attrs(li_attrs).get("class", "")
+        if "disabled" not in classes.split():
+            seats.append(seat_no)
+    return seats
+
+
+def hold_seat(
+    opener: urllib.request.OpenerDirector,
+    schedule: Schedule,
+    search_time: str,
+    seat: str | None,
+    output_dir: Path,
+    timeout: int = 20,
+) -> tuple[str, list[str], HoldResult]:
+    seat_stage_body = _open(
+        opener,
+        _request(f"{BASE_URL}{SEAT_STAGE_PATH}", _seat_stage_fields(schedule, search_time), f"{BASE_URL}{TIMETABLE_PATH}"),
+        timeout,
+    )
+    available = _available_seats(seat_stage_body)
+    selected = seat or (available[0] if available else "")
+    if not selected:
+        return seat_stage_body, available, HoldResult(False, None, "", None, None, {}, "No selectable seat was found")
+    if selected not in available:
+        return seat_stage_body, available, HoldResult(False, None, selected, None, None, {}, f"Seat {selected} is not selectable")
+
+    fields = _form_fields(seat_stage_body, "readPcpySats")
+    if not fields:
+        return seat_stage_body, available, HoldResult(False, None, selected, None, None, {}, "No readPcpySats form found")
+
+    # Mirror pcpySats() in /js/tckmrs/readSatsInfo.js for a normal adult-only hold.
+    field_map = dict(fields)
+    fields.extend(
+        [
+            ("pcpy_Num", "1"),
+            ("sats_No", selected),
+            ("rtrp_Depr_Dt", ""),
+            ("bus_Tck_Knd_Cd", field_map.get("ig_Knd_Cd", "IG00")),
+            ("cty_Bus_Dc_Knd_Cd", "Z"),
+            ("dcrt_Dvs_Cd", "0"),
+        ]
+    )
+    hold_body = _open(opener, _request(f"{BASE_URL}{HOLD_PATH}", fields, f"{BASE_URL}{SEAT_STAGE_PATH}"), timeout)
+    markers = {k: hold_body.count(k) for k in ["카드정보 입력", "sats_Pcpy_Id", "이미 발매된 좌석", "발행을 실패", "errorCont"]}
+    hold_ids = re.findall(r'name=["\']sats_Pcpy_Id["\'][^>]*value=["\']([^"\']+)', hold_body)
+    success = bool(hold_ids and markers["카드정보 입력"] and not markers["errorCont"])
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+    card_path = output_dir / "tmoney-intercity-card-info.html"
+    card_path.write_text(hold_body)
+    cancel_fields = _form_fields(hold_body, "alcnInfo") or _form_fields(hold_body, "onwayInfo")
+    cancel_path = output_dir / "tmoney-intercity-cancel-fields.txt"
+    if cancel_fields:
+        cancel_path.write_text("\n".join(f"{k}={v}" for k, v in cancel_fields))
+    else:
+        cancel_path = None  # type: ignore[assignment]
+
+    failure = None if success else _strip(hold_body[hold_body.find("[처리결과]") : hold_body.find("[처리결과]") + 500]) or "Hold did not reach card-information page"
+    return seat_stage_body, available, HoldResult(
+        success=success,
+        hold_id=hold_ids[0] if hold_ids else None,
+        seat=selected,
+        card_page_path=str(card_path),
+        cancel_fields_path=str(cancel_path) if cancel_path else None,
+        markers=markers,
+        failure_message=failure,
+    )
+
+
+def main(argv: Iterable[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Search Tmoney intercity-bus timetable and optionally create a temporary seat hold")
+    parser.add_argument("--depart-code", required=True)
+    parser.add_argument("--arrive-code", required=True)
+    parser.add_argument("--depart-name", required=True)
+    parser.add_argument("--arrive-name", required=True)
+    parser.add_argument("--date", required=True, help="YYYYMMDD")
+    parser.add_argument("--time", default="000000", help="HHMMSS, default 000000")
+    parser.add_argument("--adults", type=int, default=1)
+    parser.add_argument("--students", type=int, default=0)
+    parser.add_argument("--children", type=int, default=0)
+    parser.add_argument("--veterans", type=int, default=0)
+    parser.add_argument("--timeout", type=int, default=20)
+    parser.add_argument("--limit", type=int, default=20)
+    parser.add_argument("--select-index", type=int, default=1, help="1-based schedule index for --hold-seat")
+    parser.add_argument("--hold-seat", help="Temporarily hold this seat number and save the official card-info page")
+    parser.add_argument("--hold-first-seat", action="store_true", help="Hold the first selectable seat for the selected schedule")
+    parser.add_argument("--output-dir", help="Directory for saved hold/card page files; defaults to a temp directory")
+    args = parser.parse_args(argv)
+
+    if not re.fullmatch(r"\d{8}", args.date):
+        parser.error("--date must be YYYYMMDD")
+    if not re.fullmatch(r"\d{6}", args.time):
+        parser.error("--time must be HHMMSS")
+    if args.students or args.children or args.veterans:
+        parser.error("seat holding currently supports adult-only payloads; use search mode for mixed passenger counts")
+    if args.select_index < 1:
+        parser.error("--select-index must be 1 or greater")
+
+    opener, body, schedules = search_timetable(
+        depart_code=args.depart_code,
+        arrive_code=args.arrive_code,
+        depart_name=args.depart_name,
+        arrive_name=args.arrive_name,
+        date=args.date,
+        time=args.time,
+        adults=args.adults,
+        students=args.students,
+        children=args.children,
+        veterans=args.veterans,
+        timeout=args.timeout,
+    )
+    result: dict[str, object] = {
+        "route": {
+            "depart_code": args.depart_code,
+            "arrive_code": args.arrive_code,
+            "depart_name": args.depart_name,
+            "arrive_name": args.arrive_name,
+            "date": args.date,
+            "time": args.time,
+        },
+        "count": len(schedules),
+        "items": [asdict(s) for s in schedules[: args.limit]],
+        "failure_mode": None,
+    }
+    if not schedules:
+        result["failure_mode"] = (
+            "No readSasFeeInf schedule rows found. Check terminal codes/date, sold-out/no-service state, "
+            "or whether Tmoney returned its generic error page."
+        )
+        result["error_page_marker_count"] = body.count("errorCont")
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 2
+
+    if args.hold_seat or args.hold_first_seat:
+        if args.select_index > len(schedules):
+            parser.error(f"--select-index {args.select_index} exceeds schedule count {len(schedules)}")
+        output_dir = Path(args.output_dir) if args.output_dir else Path(tempfile.mkdtemp(prefix="tmoney-intercity-hold-"))
+        _, available, hold = hold_seat(opener, schedules[args.select_index - 1], args.time, args.hold_seat, output_dir, args.timeout)
+        result["selected_schedule"] = asdict(schedules[args.select_index - 1])
+        result["available_seats"] = available
+        result["hold"] = asdict(hold)
+        result["payment_window_note"] = (
+            "The live card-information page did not expose an exact countdown/expiry text in probes. "
+            "Treat the hold as short-lived and complete payment immediately; use the saved cancel fields to release abandoned holds."
+        )
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0 if hold.success else 3
+
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/intercity-bus-booking/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "intercity-bus-booking",
+  "description": "Search and assist Korean 시외버스/Tmoney bookings using official HTTP/API-first flows; use for 시외버스 예매, 시간표, 좌석/요금 조회, and official checkout-entry handoff. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "action:booking"
+  ],
+  "frontmatter": "name: intercity-bus-booking\ndescription: Search and assist Korean 시외버스/Tmoney bookings using official HTTP/API-first flows; use for 시외버스 예매, 시간표, 좌석/요금 조회, and official checkout-entry handoff. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: travel\n  locale: ko-KR\n  phase: v1"
+}

package/skills/iros-registry-automation/instruction.md

@@ -0,0 +1,229 @@
+# 인터넷등기소 등기부등본 자동화
+
+## What this skill does
+
+대법원 인터넷등기소(IROS, `https://www.iros.go.kr`)에서 **법인/부동산 등기부등본(등기사항증명서)** 을 여러 건 발급해야 할 때, 원 저작자 `challengekim`의 참고 구현 [`challengekim/iros-registry-automation`](https://github.com/challengekim/iros-registry-automation) (MIT)을 기준으로 안전한 작업 순서와 로컬 실행 방식을 안내한다.
+
+- 법인등기부등본: 법인등록번호 또는 상호명으로 장바구니에 담고, 사용자가 직접 결제한 뒤 열람·저장한다.
+- 부동산등기부등본: 주소/동호수 목록으로 장바구니에 담되, 결제·열람·다운로드는 인터넷등기소 웹 UI에서 수동으로 처리하는 것을 기본 권장한다.
+- TouchEn nxKey, 공동인증서/간편인증, 카드 결제처럼 사용자 PC·인증수단이 필요한 준비사항을 체크한다.
+- 발급 파일과 입력 목록에 들어가는 개인정보/민감정보를 저장소 밖에서 다루도록 안내한다.
+
+## Hard limits
+
+- **로그인은 사용자가 브라우저에서 직접 한다.** ID/PW, 공동인증서 비밀번호, 간편인증, OTP, 보안카드, 카드번호를 에이전트가 입력·저장하지 않는다.
+- **결제는 사용자가 직접 한다.** 카드 승인, 결제 확인, 결제 실패 대응은 사람이 브라우저에서 처리한다.
+- 법률 자문, 권리관계 해석, 제출/발급 결과의 법적 유효성 보장은 하지 않는다. 이 스킬은 참고용 자동화 가이드다.
+- IROS 보안 프로그램(TouchEn nxKey 등)이 요구되면 먼저 설치하고 브라우저/PC를 재시작한 뒤 다시 시작한다.
+- 법인 결제는 upstream 문서 기준 **페이지당 10건** 단위 제약을 전제로 안내한다. 그 이상은 사용자가 10건 단위로 반복 결제한다.
+- 부동산은 인터넷등기소가 로그인 상태에서 10만원 미만 일괄 결제와 일괄열람출력/일괄저장 UI를 제공하므로, v1에서는 장바구니 반복 작업만 자동화 가치가 큰 영역으로 본다.
+
+## Prerequisites
+
+- Chrome/Chromium 실행 가능한 환경
+- Python 3.10+
+- Playwright / Chromium 설치 가능 환경
+- IROS 로그인 수단(아이디, 공동인증서, 간편인증 등)
+- 결제 카드
+- TouchEn nxKey 사전 설치
+- upstream 참고 구현 clone 또는 사용자가 관리하는 로컬 사본. 실행 전 반드시 이 스킬 저장소의 `iros-registry-automation/scripts/upstream.pin`에 적힌 reviewed SHA로 고정한다.
+
+```bash
+git clone https://github.com/challengekim/iros-registry-automation.git
+cd iros-registry-automation
+git checkout 7c6924b2ff88d693a12556659188cb91041e5097
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+playwright install chromium
+cp config.json.example config.json
+```
+
+업스트림 핀 업데이트는 로그인·인증·결제 인접 브라우저 자동화의 신뢰 경계를 바꾸는 작업이다. `scripts/upstream.pin` 값을 바꾸기 전에는 새 upstream diff를 검토하고, 설치 예시의 `git checkout` SHA와 함께 같은 PR에서 갱신한다.
+
+## Workflow
+
+### 1. 입력 파일을 저장소 밖 안전한 폴더에 준비한다
+
+발급 대상에는 법인등록번호, 상호명, 주소, 동호수 등 민감할 수 있는 정보가 들어간다. 공개 저장소, PR, 테스트 로그에 넣지 않는다.
+
+```bash
+workdir="$(mktemp -d "${TMPDIR:-/tmp}/iros-registry.XXXXXX")"
+chmod 700 "$workdir"
+mkdir -p "$workdir/downloads" "$workdir/logs" "$workdir/output" "$workdir/tmp-downloads"
+```
+
+법인등록번호 기반 입력은 upstream repo `data/`가 아니라 `$workdir/corp-input.json` 같은 저장소 밖 파일에 둔다. 실제 법인등록번호/주소 원문을 upstream `data/` 디렉터리, git 저장소, PR 첨부, 테스트 로그에 넣지 않는다.
+
+`iros_download.py`는 결제 후 열람·저장 단계에서 `companies_list`를 열어 저장 파일명을 맞춘다. 법인등록번호 흐름을 쓰더라도 결제 전 `$workdir/companies-input.json`을 함께 만들어 둔다.
+
+```bash
+cat > "$workdir/corp-input.json" <<'JSON'
+{
+  "1101111234567": "예시 주식회사",
+  "1101117654321": "샘플 주식회사"
+}
+JSON
+
+python3 - "$workdir" <<'PY'
+import json
+import pathlib
+import sys
+
+workdir = pathlib.Path(sys.argv[1])
+corp_input = json.loads((workdir / "corp-input.json").read_text())
+companies = list(corp_input.values())
+(workdir / "companies-input.json").write_text(
+    json.dumps(companies, ensure_ascii=False, indent=2) + "\n"
+)
+PY
+```
+
+부동산 주소 기반 입력 예시는 동/호수까지 필요한 경우가 있으므로 `data/iros_realties.json` 형식을 upstream README에서 확인하되, 실제 주소 원문은 `$workdir/realty-input.json` 같은 로컬 파일에만 둔다.
+
+사업자번호 조회나 종합 리포트 마법사 흐름에서 쓰는 고객 Excel도 upstream repo `data/`가 아니라 `$workdir/customer-list.xlsx` 같은 저장소 밖 파일에 둔다. 실제 고객 목록을 upstream `data/고객리스트.xlsx`에 복사하지 않는다.
+
+`config.json`도 저장소에 커밋하지 않는 로컬 파일로 두고, 민감 입력·로그·산출물 경로를 모두 `$workdir` 아래로 돌린다.
+
+```bash
+python3 - "$workdir" <<'PY'
+import json
+import pathlib
+import sys
+
+workdir = pathlib.Path(sys.argv[1])
+config = json.loads(pathlib.Path("config.json").read_text())
+config.update({
+    "corpnum_list": str(workdir / "corp-input.json"),
+    "companies_list": str(workdir / "companies-input.json"),
+    "realty_list": str(workdir / "realty-input.json"),
+    "excel_path": str(workdir / "customer-list.xlsx"),
+    "save_dir": str(workdir / "downloads"),
+    "realty_save_dir": str(workdir / "downloads" / "realty"),
+    "pdf_dir": str(workdir / "downloads"),
+    "report_output": str(workdir / "output" / "corp-report.xlsx"),
+    "extract_output": str(workdir / "output" / "corp-extract.json"),
+    "bizno_cache": str(workdir / "logs" / "bizno-cache.json"),
+    "bizno_results": str(workdir / "logs" / "bizno-results.json"),
+    "realty_cart_log": str(workdir / "logs" / "cart-realty-log.json"),
+    "realty_download_log": str(workdir / "logs" / "download-realty-log.json"),
+    "cart_log": str(workdir / "logs" / "cart-log.json"),
+    "cart_corpnum_log": str(workdir / "logs" / "cart-corpnum-log.json"),
+    "download_log": str(workdir / "logs" / "download-log.json"),
+    "download_temp": str(workdir / "tmp-downloads"),
+})
+pathlib.Path("config.json").write_text(json.dumps(config, ensure_ascii=False, indent=2) + "\n")
+PY
+```
+
+### 2. TouchEn nxKey와 로그인 수단을 먼저 확인한다
+
+1. 인터넷등기소 로그인 페이지를 브라우저로 직접 연다.
+2. TouchEn nxKey 설치 안내가 나오면 설치 후 브라우저 또는 PC를 재시작한다.
+3. 공동인증서/간편인증/아이디 로그인 중 사용자가 선택한 방식으로 직접 로그인한다.
+4. 카드 결제가 가능한지 확인한다.
+
+### 3. 법인등기부등본 장바구니 담기
+
+법인등록번호를 알고 있으면 정확도가 높은 upstream `iros_cart_by_corpnum.py` 흐름을 우선한다. 상호명만 있으면 `iros_cart.py`를 사용하되 사명변경·특수문자 때문에 실패할 수 있어 실패분은 법인등록번호로 재시도한다.
+
+```bash
+python iros_cart_by_corpnum.py
+# 또는
+python iros_cart.py
+```
+
+완료되면 브라우저의 결제대상목록으로 이동한다. 사용자는 브라우저에서 페이지당 10건 단위로 직접 카드 결제를 완료하고, 터미널에는 결제가 끝난 뒤 Enter를 입력한다.
+
+### 4. 법인 결제 후 열람·저장
+
+결제가 끝난 법인 등기부등본은 upstream `iros_download.py` 또는 마법사 메뉴의 법인 열람·저장 흐름으로 저장한다.
+
+```bash
+python iros_download.py
+```
+
+저장 경로는 `config.json`의 `save_dir`로 관리하되, 위 예시처럼 `$workdir/downloads`를 사용하고 공개 저장소 하위 경로를 사용하지 않는다. `companies_list`가 `$workdir/companies-input.json`을 가리키는지 결제 전에 확인하면 결제 후 `iros_download.py`가 `FileNotFoundError`로 중단되는 일을 피할 수 있다.
+
+### 5. 부동산등기부등본 장바구니 담기
+
+부동산은 주소 목록 반복 입력과 장바구니 담기까지만 자동화를 우선 권장한다.
+
+```bash
+python iros_cart_realty.py
+```
+
+결제, 열람, 다운로드는 인터넷등기소 웹 UI에서 사용자가 직접 일괄 결제·일괄열람출력·일괄저장을 수행하는 것이 보통 더 빠르고 안전하다. 필요할 때만 `iros_download_realty.py`를 검토한다.
+
+### 6. 마법사 경로
+
+처음 쓰는 사용자는 upstream `iros_wizard.py` 메뉴가 가장 안전하다.
+
+```bash
+python iros_wizard.py
+```
+
+메뉴 요약:
+
+- 법인등기부등본 — 장바구니 담기
+- 법인등기부등본 — 결제 후 열람·저장
+- 부동산등기부등본 — 장바구니 담기
+- 부동산등기부등본 — 결제 후 열람·저장
+- 사업자번호 → 법인정보 조회 (`excel_path`는 `$workdir/customer-list.xlsx`)
+- 다운로드된 법인 PDF → 종합 리포트 엑셀 생성 (`excel_path`와 `pdf_dir`는 저장소 밖 경로)
+
+### 7. 발급 후 — 등기부등본 PDF 요약 (선택)
+
+발급·저장이 끝난 등기부등본 PDF(`$workdir/downloads/*.pdf`)에서 **근저당·가압류·소유권 변동 등 핵심 항목만 사실로 뽑아** 사람이 읽기 쉬운 요약을 만든다. 로그인·결제를 다시 하지 않는 **발급 후 단계 전용**이다.
+
+- **판단하지 않는다.** "PDF에 이렇게 적혀 있다"는 사실(종류·발급일·소유권이전 건수·근저당 채권최고액/설정일/말소여부·가압류·가처분)까지만. "안전/위험/추천" 같은 결론을 내지 않는다.
+- **원격 전송 없음.** 이 스크립트는 PDF를 어디에도 보내지 않고 로컬에서만 텍스트를 추출한다. 요약 결과에도 개인정보가 있을 수 있으므로 `$workdir/output/`에만 두고 저장소·PR·로그에 남기지 않는다. 주민등록번호는 마스킹한다.
+
+```bash
+# 텍스트 레이어가 있는 일반 등기 PDF (기본) — pypdf 또는 pdfplumber 필요
+pip install pypdf   # 또는 pip install pdfplumber (표 추출에 유리)
+python iros-registry-automation/scripts/iros_pdf_summary.py \
+  "$workdir/downloads/등기.pdf" --out "$workdir/output"
+
+# 스캔(이미지) PDF인 경우: 사용자가 로컬에 self-host한 변환기(예: marker)로 먼저
+# 텍스트/마크다운으로 바꾼 뒤 그 결과를 요약한다 (원격 전송 없이 로컬 파일만).
+python iros-registry-automation/scripts/iros_pdf_summary.py 변환결과.md --from-text --out "$workdir/output"
+```
+
+출력(모두 사실 나열, 판단 없음): 등기 종류(부동산/법인), 열람·발급 일시, 소유권 변동 건수, 근저당권 목록(채권최고액·설정일·말소여부), 가압류/가처분/압류 건수. 추출 텍스트 구조에 따라 부정확할 수 있으니 **원문 대조를 권한다.**
+
+스캔 PDF 변환 참고 구현(로컬 self-host, 사용자가 직접 실행): `NomaDamas/marker-api-server` — https://github.com/NomaDamas/marker-api-server (PDF→Markdown). 이 스킬은 marker에 PDF를 원격으로 보내지 않으며, 사용자가 로컬 변환 결과를 `--from-text`로 넘기는 경우에만 이용한다.
+
+## Response policy
+
+- 먼저 “로그인과 결제는 사용자가 직접”이라고 말한다.
+- 법인과 부동산을 구분해 권장 자동화 범위를 설명한다.
+- TouchEn nxKey 사전 설치와 브라우저 재시작 가능성을 안내한다.
+- 발급 대상 목록, PDF, Excel, 보고서에는 개인정보/민감정보가 있을 수 있으므로 저장소 밖 비공개 폴더를 사용하게 한다.
+- 법률 자문이나 권리관계 해석으로 보일 수 있는 표현을 피하고, 등기부등본 발급 보조와 파일 정리까지만 돕는다.
+- PDF 요약(섹션 7)은 "PDF에 이렇게 적혀 있다"는 **사실 추출까지만** 한다. 요약이나 답변에서 "안전/위험/추천/괜찮다" 같은 판단형 결론을 내지 않는다. 요약 결과는 개인정보를 포함할 수 있으므로 저장소·PR·로그에 남기지 않는다.
+- 원 저작자/참고 구현 링크를 문서나 답변에 남긴다: `challengekim/iros-registry-automation` — https://github.com/challengekim/iros-registry-automation. PDF→Markdown 변환 참고: `NomaDamas/marker-api-server` — https://github.com/NomaDamas/marker-api-server.
+
+## Verification
+
+로그인 없이 가능한 검증:
+
+- upstream 저장소 clone
+- `pip install -r requirements.txt`
+- `playwright install chromium`
+- `python iros_wizard.py` 실행 후 메뉴/입력 파일 안내가 정상 표시되는지 확인
+
+로그인 세션이 필요한 최종 smoke:
+
+1. 사용자가 직접 IROS에 로그인한다.
+2. 테스트용 1건을 장바구니에 담는다.
+3. 사용자가 직접 결제한다.
+4. 열람·저장 경로가 PDF를 저장하는지 확인한다.
+5. 산출물 경로와 개인정보를 PR/로그에 남기지 않는다.
+
+## Done when
+
+- 법인/부동산 대상 유형과 입력 형식이 구분됐다.
+- 로그인, 인증, 결제를 사람이 직접 처리한다는 안내가 명확하다.
+- TouchEn nxKey와 페이지당 10건 결제 제약이 안내됐다.
+- 원 저작자 `challengekim`과 참고 구현 링크가 포함됐다.