solmate-skills 1.0.0 → 1.0.2

package/k-skill/docs/features/korean-law-search.md

@@ -0,0 +1,127 @@
+# 한국 법령 검색 가이드
+
+## 이 기능으로 할 수 있는 일
+
+- `korean-law-mcp` 로 법령명 검색
+- 특정 법령의 조문 본문 조회
+- 판례 / 유권해석 / 자치법규 검색
+- MCP 또는 CLI 경로 중 현재 환경에 맞는 방식 선택
+- 기존 경로 장애 시 `법망` fallback으로 이어가기
+
+## 가장 중요한 규칙
+
+한국 법령 관련 검색/조회가 필요할 때는 **`korean-law-mcp`를 먼저 사용**합니다.
+기존 서비스가 동작하지 않을 때만 승인된 fallback 표면인 **`법망`(`https://api.beopmang.org`)** 으로 전환합니다.
+별도 repo package, 별도 python package, 임의 크롤러를 새로 만들지 않습니다.
+
+## 먼저 필요한 것
+
+- 인터넷 연결
+- `node` 18+
+- `npm install -g korean-law-mcp` (로컬 CLI/로컬 MCP server 경로일 때)
+- remote MCP endpoint를 쓸 MCP 클라이언트
+- `법망` fallback (`https://api.beopmang.org`) 에 접근할 수 있는 네트워크
+
+무료 API key 발급처: `https://open.law.go.kr`
+
+로컬 CLI 또는 로컬 MCP server 경로는 `LAW_OC` 가 필요하다.
+remote MCP endpoint는 사용자 `LAW_OC` 없이 `url`만으로 연결한다.
+
+```bash
+npm install -g korean-law-mcp
+export LAW_OC=your-api-key
+
+korean-law list
+korean-law help search_law
+```
+
+로컬 설치가 막히면 먼저 `https://korean-law-mcp.fly.dev/mcp` remote endpoint를 사용한다. 그 경로도 응답하지 않거나 서비스 장애가 나면 `법망`(`https://api.beopmang.org`) MCP/REST를 fallback으로 사용한다.
+
+## MCP 연결 예시
+
+```json
+{
+  "mcpServers": {
+    "korean-law": {
+      "command": "korean-law-mcp",
+      "env": {
+        "LAW_OC": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+remote endpoint 예시:
+
+```json
+{
+  "mcpServers": {
+    "korean-law": {
+      "url": "https://korean-law-mcp.fly.dev/mcp"
+    }
+  }
+}
+```
+
+위 remote 예시는 upstream 문서 기준으로 사용자 `LAW_OC` 를 따로 넣지 않는다. 사용자 쪽에서 준비할 것은 `url` 등록뿐이다.
+
+## fallback: 법망
+
+기존 `korean-law-mcp` 경로가 동작하지 않을 때만 `법망`을 사용한다.
+
+### MCP fallback
+
+```json
+{
+  "mcpServers": {
+    "beopmang": {
+      "url": "https://api.beopmang.org/mcp"
+    }
+  }
+}
+```
+
+### REST fallback 예시
+
+```bash
+curl "https://api.beopmang.org/api/v4/law?action=search&q=관세법"
+curl "https://api.beopmang.org/api/v4/tools?action=overview&law_id=001706"
+curl "https://api.beopmang.org/api/v4/law?action=get&law_id=001706&article=제750조"
+```
+
+## 기본 흐름
+
+1. 질의가 법령/판례/행정해석/자치법규 중 어디에 가까운지 분류한다.
+2. 법령명만 찾으면 `search_law` 를 먼저 쓴다.
+3. 특정 조문이 필요하면 `search_law` 또는 `search_all` 로 식별자(`mst`)를 확인한 뒤 `get_law_text` 를 호출한다.
+4. 판례는 `search_precedents`, 유권해석은 `search_interpretations`, 자치법규는 `search_ordinance` 를 우선 사용한다.
+5. 범주가 애매하면 `search_all` 로 시작한다.
+6. `korean-law-mcp` 경로가 설치/네트워크/서비스 장애로 막히면 `법망` fallback으로 전환한다.
+7. fallback 검색 결과가 0건이어도 바로 "관련 규범이 없다"고 단정하지 말고 검색어와 범주를 다시 확인한다.
+
+## CLI 예시
+
+```bash
+korean-law search_law --query "관세법"
+korean-law get_law_text --mst 160001 --jo "제38조"
+korean-law search_precedents --query "부당해고"
+```
+
+## 운영 팁
+
+- `화관법` 같은 약칭은 `search_law` / `search_all` 로 정식 법령명을 먼저 확인한다.
+- 조문 번호가 헷갈리면 `get_law_text` 전에 법령 식별자부터 다시 확인한다.
+- 로컬 CLI/MCP 경로를 쓰는데 `LAW_OC` 가 없으면 credential resolution order에 따라 확보를 안내한다.
+- remote MCP endpoint를 쓰면 사용자 `LAW_OC` 없이 `url` 등록 상태만 확인한다.
+- 기존 `korean-law-mcp` 경로가 실패하면 `https://api.beopmang.org/mcp` 또는 `/api/v4/law?action=search` 경로를 fallback으로 쓴다.
+- 요약은 할 수 있지만 법률 자문처럼 단정적으로 결론을 내리지는 않는다.
+
+## 라이브 확인 메모
+
+2026-04-01 기준 smoke test 에서 아래 명령은 실제로 정상 동작했다.
+
+- `korean-law list`
+- `korean-law help search_law`
+
+즉, `korean-law-mcp` CLI 설치와 기본 명령 진입은 검증했다. 실제 법령 검색은 로컬 CLI/MCP 경로라면 `LAW_OC` 가 준비된 환경에서 바로 이어서 사용할 수 있고, remote MCP endpoint는 사용자 `LAW_OC` 없이 URL 등록만으로 붙일 수 있다. 기존 경로 장애 시에는 `법망` fallback을 사용할 수 있다.

package/k-skill/docs/features/ktx-booking.md

@@ -0,0 +1,99 @@
+# KTX 예매 가이드
+
+## 이 기능으로 할 수 있는 일
+
+- KTX/Korail 열차 조회
+- 좌석 가능 여부 확인
+- 예약 진행
+- 예약 내역 확인
+- 예약 취소
+
+## 먼저 필요한 것
+
+- Python 3.10+
+- `python3 -m pip install korail2 pycryptodome`
+- [공통 설정 가이드](../setup.md) 완료
+- [보안/시크릿 정책](../security-and-secrets.md) 확인
+
+## 필요한 환경변수
+
+- `KSKILL_KTX_ID`
+- `KSKILL_KTX_PASSWORD`
+
+### Credential resolution order
+
+1. **이미 환경변수에 있으면** 그대로 사용한다.
+2. **에이전트가 자체 secret vault(1Password CLI, Bitwarden CLI, macOS Keychain 등)를 사용 중이면** 거기서 꺼내 환경변수로 주입해도 된다.
+3. **`~/.config/k-skill/secrets.env`** (기본 fallback) — plain dotenv 파일, 퍼미션 `0600`.
+4. **아무것도 없으면** 유저에게 물어서 2 또는 3에 저장한다.
+
+## 입력값
+
+- 출발역
+- 도착역
+- 날짜: `YYYYMMDD`
+- 희망 시작 시각: `HHMMSS`
+- 인원 수와 승객 유형
+- 좌석 선호
+- 조회 결과에서 복사한 `train_id`
+
+## 왜 helper 를 쓰는가
+
+현재 공개 배포된 `korail2` 0.4.0 예제만으로는 Korail 모바일 표면의 Dynapath anti-bot 체크에 막혀 `MACRO ERROR` 가 발생할 수 있다.
+
+이 저장소의 `scripts/ktx_booking.py` 는 다음 값을 보강해서 실제 KTX 예약 흐름을 복구한다.
+
+- `x-dynapath-m-token`
+- `Sid`
+- 최신 app version `250601002`
+- 최신 Android user-agent
+
+## 기본 흐름
+
+1. `korail2` 또는 `pycryptodome` 패키지가 없으면 다른 방법으로 우회하지 말고 먼저 전역 설치한다.
+2. `KSKILL_KTX_ID`, `KSKILL_KTX_PASSWORD` 가 없으면 credential resolution order에 따라 확보한다.
+3. helper 로 먼저 열차를 조회한다.
+4. 후보 열차의 `index`, `train_id`, 출발/도착 시각, KTX 여부, 좌석 여부를 보여준다.
+5. 대상 열차가 명확할 때만 예약한다.
+6. 예약 확인/취소는 대상 예약을 다시 식별한 뒤 진행한다.
+
+## 예시
+
+조회:
+
+```bash
+python3 scripts/ktx_booking.py search 서울 부산 20260328 090000 --limit 5
+```
+
+좌석이 없는 열차까지 같이 보고 싶으면 `--include-no-seats`, 예약 대기 가능 열차도 같이 보고 싶으면 `--include-waiting-list` 를 붙인다.
+
+응답 JSON 의 `train_id` 는 검색 시점의 정확한 열차를 가리키는 stable selector 다. 예약할 때는 이 값을 그대로 복사해서 쓴다. 같은 열차가 더 이상 조회되지 않으면 helper 가 실패하고 새로 조회하게 만든다.
+
+예약:
+
+```bash
+python3 scripts/ktx_booking.py reserve 서울 부산 20260328 090000 --train-id <train_id> --seat-option general-first
+```
+
+좌석이 없을 때 예약 대기까지 시도하려면 조회 단계에서도 `--include-waiting-list` 를 켜고, 예약 단계에서 `--try-waiting` 을 추가한다.
+
+예약 확인:
+
+```bash
+python3 scripts/ktx_booking.py reservations
+```
+
+취소:
+
+```bash
+python3 scripts/ktx_booking.py cancel <reservation_id>
+```
+
+응답은 JSON 으로 나오며 예약번호, 구입기한, 운임 확인에 바로 쓸 수 있다. **결제는 제외** 하고 예약까지만 자동화한다.
+
+## 주의할 점
+
+- SRT 예매와는 별도 표면이므로 혼용하지 않는다.
+- credential은 환경변수로 주입한다.
+- 결제 완료까지 자동화하는 범위는 아니다.
+- Korail anti-bot 규칙이 다시 바뀌면 helper 도 함께 점검해야 한다.

package/k-skill/docs/features/lotto-results.md

@@ -0,0 +1,41 @@
+# 로또 결과 가이드
+
+## 이 기능으로 할 수 있는 일
+
+- 최신 회차 확인
+- 특정 회차 당첨번호 조회
+- 번호 대조로 몇 등인지 확인
+- 상세 당첨금 정보 확인
+
+## 먼저 필요한 것
+
+- Node.js 18+
+- 배포 후: `npm install -g k-lotto`
+- 실행 전: `export NODE_PATH="$(npm root -g)"`
+- 이 저장소에서 개발할 때: 루트에서 `npm install`
+
+## 입력값
+
+- 회차 번호 또는 `latest`
+- 선택 사항: 사용자의 번호 6개
+
+## 기본 흐름
+
+1. 패키지가 없으면 다른 방법으로 우회하지 말고 먼저 전역 설치합니다.
+2. 최신 회차 또는 요청 회차를 확인합니다.
+3. 당첨번호와 추첨일, 당첨금 분포를 요약합니다.
+4. 사용자 번호가 있으면 일치 번호와 등수를 계산합니다.
+
+## 예시
+
+```bash
+NODE_PATH="$(npm root -g)" node - <<'JS'
+const lotto = require("k-lotto");
+lotto.getDetailResult(1216).then((result) => console.log(JSON.stringify(result, null, 2)));
+JS
+```
+
+## 주의할 점
+
+- 사용자 번호는 영구 저장하지 않는 것을 기준으로 합니다.
+- 최신 회차는 결과 페이지 HTML에서 읽고, 상세 결과는 공식 JSON 응답을 사용합니다.

package/k-skill/docs/features/seoul-subway-arrival.md

@@ -0,0 +1,61 @@
+# 서울 지하철 도착정보 가이드
+
+## 이 기능으로 할 수 있는 일
+
+- 역 기준 실시간 도착 예정 열차 조회
+- 상/하행 또는 외/내선 정보 확인
+- 첫 번째/두 번째 도착 메시지 확인
+- 개인 OpenAPI key 없이 `k-skill-proxy` 경유 조회
+
+## 먼저 필요한 것
+
+- [공통 설정 가이드](../setup.md) 완료
+- [보안/시크릿 정책](../security-and-secrets.md) 확인
+- self-host 또는 배포 확인이 끝난 proxy base URL: `KSKILL_PROXY_BASE_URL`
+
+## 필요한 환경변수
+
+- `KSKILL_PROXY_BASE_URL` (필수: self-host 또는 배포 확인이 끝난 proxy base URL)
+
+사용자가 서울 열린데이터 광장 OpenAPI key를 직접 발급할 필요는 없다. 대신 `KSKILL_PROXY_BASE_URL` 은 `/v1/seoul-subway/arrival` route가 실제로 배포된 proxy를 가리켜야 한다. upstream key는 proxy 서버에서만 관리한다.
+
+### Proxy resolution order
+
+1. **`KSKILL_PROXY_BASE_URL` 이 있으면** 그 값을 사용합니다.
+2. **없으면** 사용자/운영자에게 self-host 또는 배포 확인이 끝난 proxy URL 을 먼저 확보합니다.
+3. **직접 proxy를 운영하는 경우에만** proxy 서버 upstream key를 서버 쪽에만 설정합니다.
+
+## 입력값
+
+- 역명
+- 선택 사항: 가져올 건수
+
+## 기본 흐름
+
+1. `KSKILL_PROXY_BASE_URL` 로 self-host 또는 배포 확인이 끝난 proxy base URL 을 확인합니다.
+2. `/v1/seoul-subway/arrival?stationName=...` 로 역명 기준 실시간 도착정보를 조회합니다.
+3. 호선, 진행 방향, 도착 메시지, 조회 시점을 함께 요약합니다.
+
+## 예시
+
+```bash
+curl -fsS --get 'https://your-proxy.example.com/v1/seoul-subway/arrival' \
+  --data-urlencode 'stationName=강남'
+```
+
+범위를 줄이거나 늘리고 싶으면:
+
+```bash
+curl -fsS --get 'https://your-proxy.example.com/v1/seoul-subway/arrival' \
+  --data-urlencode 'stationName=서울역' \
+  --data-urlencode 'startIndex=0' \
+  --data-urlencode 'endIndex=4'
+```
+
+## 주의할 점
+
+- 실시간 데이터라 몇 초 단위로 바뀔 수 있습니다.
+- 역명 표기가 다르면 결과가 비어 있을 수 있습니다.
+- 일일 호출 제한이나 quota 초과 가능성이 있습니다.
+- public hosted route rollout 이 끝나기 전까지는 `KSKILL_PROXY_BASE_URL` 을 반드시 명시합니다.
+- self-host proxy 설정은 [k-skill 프록시 서버 가이드](k-skill-proxy.md)를 봅니다.

package/k-skill/docs/features/srt-booking.md

@@ -0,0 +1,67 @@
+# SRT 예매 가이드
+
+## 이 기능으로 할 수 있는 일
+
+- 수서 출발 SRT 열차 조회
+- 좌석 가능 여부 확인
+- 예약 진행
+- 예약 내역 확인
+- 예약 취소
+
+## 먼저 필요한 것
+
+- Python 3.10+
+- `python3 -m pip install SRTrain`
+- [공통 설정 가이드](../setup.md) 완료
+- [보안/시크릿 정책](../security-and-secrets.md) 확인
+
+## 필요한 환경변수
+
+- `KSKILL_SRT_ID`
+- `KSKILL_SRT_PASSWORD`
+
+### Credential resolution order
+
+1. **이미 환경변수에 있으면** 그대로 사용한다.
+2. **에이전트가 자체 secret vault(1Password CLI, Bitwarden CLI, macOS Keychain 등)를 사용 중이면** 거기서 꺼내 환경변수로 주입해도 된다.
+3. **`~/.config/k-skill/secrets.env`** (기본 fallback) — plain dotenv 파일, 퍼미션 `0600`.
+4. **아무것도 없으면** 유저에게 물어서 2 또는 3에 저장한다.
+
+## 입력값
+
+- 출발역
+- 도착역
+- 날짜: `YYYYMMDD`
+- 희망 시작 시각: `HHMMSS`
+- 인원 수
+- 좌석 선호
+
+## 기본 흐름
+
+1. `SRTrain` 패키지가 없으면 다른 방법으로 우회하지 말고 먼저 전역 설치합니다.
+2. `KSKILL_SRT_ID`, `KSKILL_SRT_PASSWORD` 가 없으면 credential resolution order에 따라 확보합니다.
+3. 먼저 열차를 조회합니다.
+4. 후보 열차의 출발/도착 시각, 좌석 여부, 운임을 보여줍니다.
+5. 대상 열차가 명확할 때만 예약합니다.
+6. 예약 확인/취소는 예약을 다시 식별한 뒤 진행합니다.
+
+## 예시
+
+```bash
+python3 - <<'PY'
+import os
+from SRT import SRT
+
+srt = SRT(os.environ["KSKILL_SRT_ID"], os.environ["KSKILL_SRT_PASSWORD"])
+trains = srt.search_train("수서", "부산", "20260328", "080000", time_limit="120000")
+
+for idx, train in enumerate(trains[:5], start=1):
+    print(idx, train)
+PY
+```
+
+## 주의할 점
+
+- credential은 환경변수로 주입합니다.
+- 결제 완료까지 자동화하는 문서는 아닙니다.
+- 매진 시 공격적인 재시도 루프는 피합니다.

package/k-skill/docs/features/toss-securities.md

@@ -0,0 +1,83 @@
+# 토스증권 조회 가이드
+
+## 이 기능으로 할 수 있는 일
+
+- `tossctl` 기반 토스증권 계좌 목록 / 계좌 요약 조회
+- 포트폴리오 보유 종목 / 자산 비중 조회
+- 단일 종목 / 다중 종목 시세 조회
+- 미체결 주문 / 월간 체결 내역 조회
+- 관심종목 목록 조회
+
+## 먼저 필요한 것
+
+- macOS + Homebrew
+- `tossctl` 설치
+- `tossctl auth login` 으로 브라우저 세션 확보
+- `node` 18+
+
+## upstream 설치와 로그인
+
+이 기능은 `JungHoonGhae/tossinvest-cli` 의 `tossctl` 을 그대로 사용한다.
+
+```bash
+brew tap JungHoonGhae/tossinvest-cli
+brew install tossctl
+tossctl doctor
+tossctl auth doctor
+tossctl auth login
+```
+
+로그인이 끝나기 전에는 계좌/포트폴리오 조회를 시도하지 않는다.
+
+## 지원하는 read-only 명령
+
+- `tossctl account list --output json`
+- `tossctl account summary --output json`
+- `tossctl portfolio positions --output json`
+- `tossctl portfolio allocation --output json`
+- `tossctl quote get TSLA --output json`
+- `tossctl quote batch TSLA 005930 VOO --output json`
+- `tossctl orders list --output json`
+- `tossctl orders completed --market all --output json`
+- `tossctl watchlist list --output json`
+
+## Node.js 예시
+
+```js
+const {
+  getAccountSummary,
+  getPortfolioPositions,
+  getQuote,
+  listCompletedOrders
+} = require("toss-securities");
+
+async function main() {
+  const summary = await getAccountSummary();
+  const positions = await getPortfolioPositions();
+  const quote = await getQuote("TSLA");
+  const completed = await listCompletedOrders({ market: "all" });
+
+  console.log(summary.data);
+  console.log(positions.data);
+  console.log(quote.data);
+  console.log(completed.data);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});
+```
+
+## 운영 팁
+
+- 계좌 요약과 포트폴리오는 로그인 세션이 있어야만 동작한다.
+- `TSLA`, `VOO`, `005930` 같이 심볼을 그대로 넘기면 된다.
+- 주문 관련 답변은 **조회 결과만** 정리하고, 실거래로 이어지는 행동은 권하지 않는다.
+- 민감한 계좌 정보는 꼭 필요한 값만 답한다.
+
+## 주의할 점
+
+- `tossctl` 은 비공식 CLI 이므로 웹 내부 API 변경에 영향을 받을 수 있다.
+- 브라우저 세션이 만료되면 `tossctl auth login` 을 다시 해야 할 수 있다.
+- 이 레포의 `toss-securities` 패키지는 read-only wrapper 이며, 거래 mutation 명령은 공개 API에 포함하지 않는다.

package/k-skill/docs/features/used-car-price-search.md

@@ -0,0 +1,86 @@
+# 중고차 가격 조회 가이드
+
+## 이 기능으로 할 수 있는 일
+
+- 주요 한국 렌터카 업체를 먼저 비교한 뒤 v1 공급자를 선택하기
+- `SK렌터카 다이렉트 타고BUY` inventory snapshot 에서 차종별 중고차 가격 조회
+- `인수가`, `월 렌트료`, `연식`, `주행거리`, `연료`, `변속기` 정리
+- 같은 구조의 조회를 **최소 10회 이상** 반복해도 안정적으로 응답하는지 검증
+
+## 먼저 알아둘 점
+
+### 현재 공급자 선정 결과
+
+이 저장소와 현재 세션에는 중고차 가격 조회용 전용 **MCP** 나 **Skill** 이 없어서, 먼저 대표 렌터카 업체의 공개 표면을 비교했다.
+
+| 업체 | 점검한 공개 표면 | API / 크롤링 판단 | 선택 여부 |
+| --- | --- | --- | --- |
+| SK렌터카 | `https://www.skdirect.co.kr/tb` | 별도 공개 API 문서는 못 찾았지만, 공개 HTML 안 `__NEXT_DATA__` 에 `carListProd` inventory snapshot 이 들어 있다. 로그인 없이 반복 조회가 가능해 가장 구현이 쉽다. | 선택 |
+| 롯데렌탈(롯데오토옥션) | `https://www.lotteautoauction.net/hp/pub/cmm/viewMain.do` | 공개 진입점은 열리지만 legacy `.do` 화면 중심이고, 공개 일반 매물 목록 계약을 안정적으로 고정하기 어려웠다. | 보류 |
+| 레드캡렌터카 | `https://biz.redcap.co.kr/rent/` | business portal 만 확인되었고 공개 중고차 inventory 검색/API 표면을 찾지 못했다. | 보류 |
+
+즉, v1 은 **SK렌터카 다이렉트 타고BUY** 를 사용한다.
+
+## 입력값
+
+- 차종/모델 키워드
+  - 예: `아반떼`
+  - 예: `현대 아반떼`
+  - 예: `K3`
+  - 예: `캐스퍼`
+
+차종 키워드가 없으면 먼저 물어본다.
+
+## 공식 표면
+
+- SK direct 타고BUY inventory page: `https://www.skdirect.co.kr/tb`
+
+## 기본 흐름
+
+1. 차종 키워드를 받는다.
+2. `https://www.skdirect.co.kr/tb` HTML 을 가져온다.
+3. HTML 안의 `__NEXT_DATA__` JSON 에서 `carListProd` 를 읽는다.
+4. 차종 키워드와 `maker/model/grade` 조합으로 필터링한다.
+5. `인수가`, `월 렌트료`, `연식`, `주행거리`, `연료`, `변속기`를 정리한다.
+6. 같은 차종이라도 재고가 변할 수 있으므로 snapshot 시점 기준 결과라고 답한다.
+
+## Node.js 예시
+
+```js
+const { lookupUsedCarPrices } = require("used-car-price-search")
+
+async function main() {
+  const result = await lookupUsedCarPrices("K3", { limit: 3 })
+
+  console.log({
+    provider: result.provider,
+    matchedCount: result.matchedCount,
+    summary: result.summary,
+    items: result.items
+  })
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exitCode = 1
+})
+```
+
+## 응답 예시 포맷
+
+- 공급자: `SK렌터카 다이렉트 타고BUY`
+- 검색어: `아반떼`
+- 매칭 수: `N대`
+- 인수가 범위: `1,290만원 ~ 1,590만원`
+- 월 렌트료 범위: `39.2만원 ~ 44.1만원`
+- 대표 매물: 연식 / 주행거리 / 연료 / 변속기 순으로 2~5대
+
+## 구현 메모
+
+- 별도의 공개 REST API 문서는 확인하지 못했다.
+- 대신 공개 HTML 에 들어 있는 `__NEXT_DATA__` inventory snapshot 을 읽는 방식이라 anti-bot 우회나 로그인 세션 없이도 동작한다.
+- v1 은 차종 검색과 가격 요약에 집중하고, 계약/상담/결제 자동화는 하지 않는다.
+
+## 라이브 검증 메모
+
+2026-04-02T07:52:24Z 기준 `https://www.skdirect.co.kr/tb` 에 대해 live smoke run 을 다시 수행했고, inventory 규모는 시점에 따라 변동될 수 있었지만 `캐스퍼`, `K3`, `티볼리`, `아반떼`, `쏘나타`, `투싼`, `싼타페`, `QM6`, `그랜저`, `스포티지` 순으로 **10회** 차종 조회를 반복해도 구조화된 결과를 계속 얻을 수 있었다.

package/k-skill/docs/features/zipcode-search.md

@@ -0,0 +1,100 @@
+# 우편번호 검색 가이드
+
+## 이 기능으로 할 수 있는 일
+
+- 주소 키워드로 공식 우체국 우편번호 조회
+- 같은 도로명/건물명 후보가 여러 개일 때 상위 결과 비교
+- 검색 결과가 없을 때 바로 재검색 키워드 조정
+
+## 먼저 필요한 것
+
+- 인터넷 연결
+- `curl`
+- 선택 사항: `python3`
+
+## 입력값
+
+- 주소 키워드
+  - 예: `세종대로 209`
+  - 예: `판교역로 235`
+
+## 기본 흐름
+
+1. 비공식 지도/블로그 검색으로 우회하지 말고 우체국 공식 검색 페이지를 먼저 조회합니다.
+2. 주소 키워드를 `keyword` 파라미터로 넘겨 HTML 결과를 받습니다.
+3. 결과에서 우편번호(`sch_zipcode`)와 표준 주소(`sch_address1`), 건물명(`sch_bdNm`)을 추출합니다.
+4. 후보가 여러 개면 상위 3~5개만 간단히 비교해 줍니다.
+5. 전송 timeout/reset이 나면 `curl` 재시도 옵션을 유지한 채 한 번 더 돌리고, 그래도 실패하면 `세종대로 209` 같은 짧은 도로명 + 건물번호 → `서울 종로구 세종대로 209` 같은 시/군/구 포함 전체 주소 → 동/리 + 지번 순으로 재시도합니다.
+
+## 예시
+
+```bash
+python3 - <<'PY'
+import html
+import re
+import subprocess
+
+query = "세종대로 209"
+cmd = [
+    "curl",
+    "--http1.1",
+    "--tls-max",
+    "1.2",
+    "--silent",
+    "--show-error",
+    "--location",
+    "--retry",
+    "3",
+    "--retry-all-errors",
+    "--retry-delay",
+    "1",
+    "--max-time",
+    "20",
+    "--get",
+    "--data-urlencode",
+    f"keyword={query}",
+    "https://parcel.epost.go.kr/parcel/comm/zipcode/comm_newzipcd_list.jsp",
+]
+result = subprocess.run(
+    cmd,
+    check=True,
+    capture_output=True,
+    text=True,
+    encoding="utf-8",
+)
+page = result.stdout
+
+matches = re.findall(
+    r'name="sch_zipcode"\s+value="([^"]+)".*?name="sch_address1"\s+value="([^"]+)".*?name="sch_bdNm"\s+value="([^"]*)"',
+    page,
+    re.S,
+)
+
+if not matches:
+    raise SystemExit("검색 결과가 없습니다.")
+
+for zip_code, address, building in matches[:5]:
+    suffix = f" ({building})" if building else ""
+    print(f"{zip_code}\t{html.unescape(address)}{suffix}")
+PY
+```
+
+## 실전 운영 팁
+
+- 쉘 래퍼나 에이전트 환경에서는 here-doc + Python one-liner보다 `mktemp` 같은 임시 파일에 HTML을 저장한 뒤 파싱하는 쪽이 더 안전합니다.
+- 응답 일부만 빨리 보려고 `curl ... | head` 를 붙이면 다운스트림이 먼저 닫히면서 `curl: (23)` 이 보일 수 있습니다. 이때는 전체 응답을 임시 파일에 저장한 뒤 확인합니다.
+- 재시도 순서는 보통 `세종대로 209` 같은 짧은 도로명 + 건물번호 → `서울 종로구 세종대로 209` 같은 전체 주소 → 동/리 + 지번 순이 가장 덜 헷갈립니다.
+
+## 프로토콜/클라이언트 제약
+
+- 현재 ePost 엔드포인트는 로컬 기본 `urllib` 전송으로 붙으면 TLS/HTTP 협상 중 연결 reset이 날 수 있습니다.
+- 현재 ePost 엔드포인트는 같은 curl 플래그여도 간헐적인 timeout/reset이 있을 수 있으므로 문서 기본 예시는 `--retry 3 --retry-all-errors --retry-delay 1`을 포함합니다.
+- 문서 기본 예시는 `curl --http1.1 --tls-max 1.2` 전송을 사용하고, Python은 응답 파싱/정리에만 사용합니다.
+- 바깥쪽 Python `timeout`은 두지 않고 `curl` 자체 제한(`--max-time` + `--retry`)으로 전체 전송 시간을 제어합니다.
+- 다른 클라이언트를 쓰더라도 최소한 HTTP/1.1 + TLS 1.2 경로에서 실제 응답을 먼저 확인한 뒤 정규식 추출을 붙입니다.
+
+## 주의할 점
+
+- 같은 번지라도 건물명에 따라 여러 행이 나올 수 있으니 첫 결과만 바로 확정하지 않습니다.
+- 결과가 너무 많으면 시/군/구를 포함해 검색어를 더 구체화합니다.
+- 조회형 스킬이므로 개인정보를 저장하지 않습니다.