@nomadamas/k-skill 0.1.0

package/bin/k-skill.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+"use strict";
+
+const { assemble, bundledFiles, listSkills } = require("../src/assemble");
+const { detectRuntime } = require("../src/detect");
+
+function usage() {
+  return [
+    "Usage: k-skill <command> [skill]",
+    "",
+    "Commands:",
+    "  instruct <skill>   Print runtime-aware assembled instructions for a skill",
+    "  files <skill>      Print local paths of the skill's bundled helper files",
+    "  list               List bundled skills",
+    "",
+    "Runtime detection: DOLSHOI_ACTION_BROKER_URL enables Dolshoi mode;",
+    "CLOAKBROWSER_PEEK_TOKEN marks CloakBrowser availability.",
+  ].join("\n");
+}
+
+function main() {
+  const [command, skillName] = process.argv.slice(2);
+
+  if (!command || command === "--help" || command === "-h") {
+    console.log(usage());
+    return 0;
+  }
+
+  if (command === "list") {
+    for (const name of listSkills()) console.log(name);
+    return 0;
+  }
+
+  if (command === "instruct" || command === "files") {
+    if (!skillName) {
+      console.error(`error: "${command}" requires a skill name\n\n${usage()}`);
+      return 1;
+    }
+
+    try {
+      if (command === "instruct") {
+        process.stdout.write(assemble(skillName, detectRuntime()));
+      } else {
+        for (const filePath of bundledFiles(skillName)) console.log(filePath);
+      }
+      return 0;
+    } catch (error) {
+      if (error.code === "EUNKNOWNSKILL") {
+        console.error(`error: ${error.message}`);
+        return 1;
+      }
+      throw error;
+    }
+  }
+
+  console.error(`error: unknown command "${command}"\n\n${usage()}`);
+  return 1;
+}
+
+process.exitCode = main();

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@nomadamas/k-skill",
+  "version": "0.1.0",
+  "description": "k-skill unified CLI: assembles runtime-aware skill instructions and ships bundled helper files",
+  "license": "MIT",
+  "bin": {
+    "k-skill": "bin/k-skill.js"
+  },
+  "main": "src/assemble.js",
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "skills",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NomaDamas/k-skill.git"
+  },
+  "keywords": [
+    "k-skill",
+    "korea",
+    "agent-skills",
+    "cli"
+  ],
+  "scripts": {
+    "lint": "node --check bin/k-skill.js && node --check src/assemble.js && node --check src/detect.js && node --check test/cli.test.js",
+    "test": "node --test"
+  }
+}

package/skills/assembly-bill-vote-search/instruction.md

@@ -0,0 +1,111 @@
+# Assembly Bill Vote Search
+
+## What this skill does
+
+열린국회정보 Open API `https://open.assembly.go.kr/portal/openapi` 를 `k-skill-proxy` 경유로 호출한다.
+
+지원 endpoint:
+
+- `GET /v1/assembly/bills` → `ALLBILLV2` 의안정보 통합 API
+- `GET /v1/assembly/bill-detail` → `BILLINFODETAIL` 의안 상세정보
+- `GET /v1/assembly/votes` → `nojepdqqaweusdfbi` 국회의원 본회의 표결정보
+
+## When to use
+
+- "간호법 의안 검색해줘"
+- "BILL_ID로 의안 상세 보여줘"
+- "21대 국회 특정 의안 표결에서 의원별 찬반 알려줘"
+
+## Prerequisites
+
+- 인터넷 연결
+- hosted/self-host `k-skill-proxy`의 `/v1/assembly/*` route 접근 가능
+
+## Credential requirements
+
+- 사용자 측 필수 시크릿 없음.
+- `KSKILL_PROXY_BASE_URL` — self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted `https://k-skill-proxy.nomadamas.org` 를 사용한다.
+- `ASSEMBLY_API_KEY` 또는 `KSKILL_ASSEMBLY_API_KEY` 는 프록시 운영 서버 환경에만 둔다.
+
+키 발급: <https://open.assembly.go.kr/portal/openapi/openApiActKeyIssPage.do>
+
+## Inputs
+
+의안 검색:
+
+- `query`/`q`/`billName` → `BILL_NM`
+- `billId`, `billNo`, `billKind`, `committeeName`, `proposalDate`, `result`
+- `eraco`/`ageLabel` → `ERACO`, 기본 `제21대`
+- `page`/`pIndex`, `limit`/`pSize`
+
+의안 상세:
+
+- `billId` 필수
+
+표결 조회:
+
+- `age` 필수 (`21` 등 숫자)
+- `billId` 필수
+- `memberName`, `party`, `memberNo`, `voteDate`, `billNo`, `billName`, `committee`, `voteResult`
+- `page`/`pIndex`, `limit`/`pSize`
+
+## Workflow
+
+### 1. Search bills first
+
+```bash
+BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
+curl -fsS --get "$BASE/v1/assembly/bills" \
+  --data-urlencode "query=간호법" \
+  --data-urlencode "eraco=제21대" \
+  --data-urlencode "limit=10"
+```
+
+### 2. Fetch bill detail
+
+```bash
+curl -fsS --get "$BASE/v1/assembly/bill-detail" \
+  --data-urlencode "billId=PRC_N2D0H0W9P2S3Z1Q2X0L8W4B1G8E3F4"
+```
+
+### 3. Fetch plenary votes
+
+```bash
+curl -fsS --get "$BASE/v1/assembly/votes" \
+  --data-urlencode "age=21" \
+  --data-urlencode "billId=PRC_N2D0H0W9P2S3Z1Q2X0L8W4B1G8E3F4" \
+  --data-urlencode "limit=100"
+```
+
+## Failure modes
+
+- `400 bad_request`: 필수 `billId`/`age` 누락, 페이지 크기 초과, 잘못된 숫자 형식.
+- `503 upstream_not_configured`: 프록시 서버에 `ASSEMBLY_API_KEY`/`KSKILL_ASSEMBLY_API_KEY` 없음.
+- 열린국회정보 `RESULT.CODE`:
+  - `ERROR-290`: 키 누락/오류
+  - `ERROR-300`: 필수 파라미터 누락
+  - `ERROR-337`: 일일 트래픽 초과
+  - `INFO-200`: 결과 없음
+- 빈 결과: 대수(`ERACO`/`age`), 의안명, 의안번호, BILL_ID를 다시 확인한다.
+
+## Done when
+
+- 먼저 의안 검색으로 `BILL_ID`를 확정했다.
+- 상세 또는 표결 조회 결과에 `BILL_ID`, 국회 대수, endpoint를 함께 적었다.
+- 표결 요약은 찬성/반대/기권 등 upstream 원문 분류를 임의 변경하지 않았다.
+
+## Maintainer review notes
+
+키 없이 가능한 검증:
+
+- `./scripts/validate-skills.sh`
+- `node --test packages/k-skill-proxy/test/server.test.js`
+- `curl -i --get "$KSKILL_PROXY_BASE_URL/v1/assembly/bills" --data-urlencode "query=간호법"` (키 미설정이면 503 확인)
+
+Live smoke는 hosted/self-host proxy에 `ASSEMBLY_API_KEY`가 설정된 뒤 수행한다.
+
+## Safety notes
+
+- 조회 전용 스킬이다.
+- 정치적 평가·추천을 자동 생성하지 않고, 공식 원천의 의안·표결 사실을 요약한다.
+- 인증키는 프록시 서버에서만 다루며 repo/GitHub Actions/public docs에 저장하지 않는다.

package/skills/assembly-bill-vote-search/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "assembly-bill-vote-search",
+  "description": "열린국회정보 Open API를 k-skill-proxy 경유로 호출해 의안 검색·상세와 국회의원 본회의 표결정보를 조회한다. 조회 전용.",
+  "profiles": [
+    "proxy",
+    "vault",
+    "lookup"
+  ],
+  "frontmatter": "name: assembly-bill-vote-search\ndescription: 열린국회정보 Open API를 k-skill-proxy 경유로 호출해 의안 검색·상세와 국회의원 본회의 표결정보를 조회한다. 조회 전용.\nlicense: MIT\nmetadata:\n  category: civic\n  locale: ko-KR\n  phase: v1"
+}

package/skills/biz-health-check/instruction.md

@@ -0,0 +1,69 @@
+# 사업자 실사 복합 조회 (biz-health-check)
+
+## What this skill does
+
+사업자등록번호(+상호/지역)를 입력하면 무료 공공 데이터 6종을 한 번에 교차 조회해 실사 리포트 한 장을 만든다. 같은 레포의 단품 스킬 helper를 그대로 재사용한다(단일 진실원천).
+
+| 섹션 | 데이터 | 단품 스킬 | 경로 |
+|---|---|---|---|
+| 국세청 상태 | 계속/휴업/폐업·과세유형 | `nts-business-registration` | proxy |
+| 국민연금 | 가입자수·당월 고지금액·월별 | `national-pension-workplace` | proxy |
+| 체납 명단 | 고액·상습체납자 명단공개 대조 | `nts-tax-delinquency` | 직접(무인증) |
+| 금융위 | 대표자·설립일·업종 법인개요 | `fsc-corporate-info` | proxy |
+| 부정당제재 | 조회시점 유효 제재 | `g2b-sanctioned-supplier` | proxy |
+| 인허가 영업상태 | 동네 사업장(208업종) 영업/폐업·업력 | `localdata-business-status` | 직접(무인증) |
+
+공시 유무는 기존 `k-dart` 스킬을 함께 쓰면 된다.
+
+## Design principles
+
+- **점수·등급·"위험" 같은 해석 라벨을 산출하지 않는다.** 각 항목의 사실 + 출처 + 조회시각만 병렬한다. 판단은 사용자 몫이다.
+- 한 항목 조회가 실패해도 전체를 막지 않고 그 항목만 정직하게 강등한다(`unavailable` + 사유).
+- 단품 helper를 찾지 못하면(개별 설치 등) 해당 섹션만 건너뛰고 나머지를 진행한다.
+
+## When to use
+
+- "이 사업자(거래처/의뢰인) 실제 문제 없는지 한 번에 확인해줘"
+- "○○○-○○-○○○○○ 살아있는 회사야? 직원은 좀 있고, 체납·입찰 제재 이력은 없어?"
+
+## Prerequisites
+
+- 인터넷 연결, `python3`
+- 같은 레포의 단품 스킬 6종(이 복합이 helper를 재사용)
+- proxy 섹션을 켜려면 hosted/self-host `k-skill-proxy` 접근 가능
+
+## Credential requirements
+
+- 사용자 측 필수 시크릿 없음.
+- proxy 섹션(국세청 상태·국민연금·금융위·부정당)은 운영 서버의 `DATA_GO_KR_API_KEY`로 동작한다. 활용신청 항목은 각 단품 스킬 문서를 따른다.
+- 무인증 섹션(체납·인허가)은 키 없이 사용자 머신에서 직접 동작한다.
+
+## Inputs
+
+- `b_no`: 사업자등록번호 10자리(하이픈 허용) — 상태조회·부정당제재에 필요
+- `--name`: 상호·법인명 — 국민연금·금융위·체납·인허가에 필요
+- `--region`: 시군구 — 인허가(동네 사업장) 조회에 필요 (예: `제주제주시`)
+- `--industry`: 인허가 업종(여러 번 지정 가능). 생략 시 음식점·카페·숙박
+
+## CLI examples
+
+```bash
+python3 biz-health-check/scripts/biz_health_check.py 124-81-00998 --name "삼성전자"
+
+# 동네 사업장까지 포함
+python3 biz-health-check/scripts/biz_health_check.py --name "호텔샬롬" --region 제주제주시 --industry 숙박업
+```
+
+## Output
+
+- `sections`: 6개 섹션 각각의 `data`(단품 응답 원문) 또는 `status: unavailable` + `note`
+- 입력에 따라 일부 섹션은 생략된다(예: `--name` 없으면 국민연금/금융위/체납 생략).
+
+## Failure modes
+
+- 섹션별 강등은 리포트에 그대로 남는다(전체 실패가 아니다).
+- proxy 섹션이 `503/502`면 운영 서버 키·활용신청 문제 — 각 단품 스킬 문서 참고.
+
+## Official surfaces
+
+- 각 단품 스킬 문서(`docs/features/<skill>.md`)의 공식 출처를 따른다.

package/skills/biz-health-check/scripts/biz_health_check.py

@@ -0,0 +1,163 @@
+"""Business due-diligence composite — runs the sibling k-skill providers at once.
+
+사업자등록번호(+상호/지역) 하나로 "이 사업자, 실제 문제 없나"를 무료 공공 데이터로
+교차 조회해 실사 리포트 한 장을 만든다. 점수·등급·"위험" 라벨을 만들지 않고,
+각 항목의 사실 + 출처 + 조회시각만 병렬한다. 판단은 사용자 몫이다.
+
+이 복합 스킬은 같은 레포의 단품 스킬 helper들을 그대로 재사용한다(단일 진실원천):
+
+- nts-business-registration   상태조회        (k-skill-proxy)
+- national-pension-workplace  국민연금 사업장  (k-skill-proxy)
+- fsc-corporate-info          금융위 법인개요  (k-skill-proxy)
+- g2b-sanctioned-supplier     부정당제재       (k-skill-proxy)
+- nts-tax-delinquency         체납 명단        (무인증 직접)
+- localdata-business-status   인허가 영업상태  (무인증 직접, --region 필요)
+
+단품 helper를 찾지 못하면 해당 항목만 정직하게 강등하고 나머지는 계속 진행한다.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import importlib.util
+import json
+import pathlib
+import re
+import sys
+from typing import Any, Callable
+
+KST = dt.timezone(dt.timedelta(hours=9))
+PROXY_DOWN_MSG = "설정된 k-skill-proxy 서버가 응답하지 않습니다. 잠시 후 재시도하거나 운영자에게 문의하세요."
+PROXY_KEY_NOT_CONFIGURED_MSG = "k-skill-proxy에 필요한 API 키가 설정되어 있지 않습니다. 운영자에게 문의하세요."
+_REPO_ROOT = pathlib.Path(__file__).resolve().parent.parent.parent
+
+# (섹션 키, 사람이 읽는 라벨, 단품 스킬 디렉토리, helper 파일명)
+_SIBLINGS = {
+    "nts_status": ("국세청 사업자등록 상태", "nts-business-registration", "nts_business_registration.py"),
+    "national_pension": ("국민연금 가입 사업장", "national-pension-workplace", "national_pension_workplace.py"),
+    "fsc_corp": ("금융위 기업기본정보", "fsc-corporate-info", "fsc_corporate_info.py"),
+    "g2b_sanction": ("조달청 부정당제재", "g2b-sanctioned-supplier", "g2b_sanctioned_supplier.py"),
+    "tax_delinquency": ("국세 체납 명단공개", "nts-tax-delinquency", "nts_tax_delinquency.py"),
+    "localdata": ("지방행정 인허가 영업상태", "localdata-business-status", "localdata_business_status.py"),
+}
+
+
+def _now_iso() -> str:
+    return dt.datetime.now(KST).isoformat(timespec="seconds")
+
+
+def _normalize_b_no(value: Any) -> str:
+    normalized = re.sub(r"\D", "", str(value or ""))
+    if not re.fullmatch(r"\d{10}", normalized):
+        raise ValueError("사업자등록번호는 숫자 10자리여야 합니다 (하이픈 허용).")
+    return normalized
+
+
+def _unavailable(module_key: str, note: str) -> dict:
+    label, skill_dir, _ = _SIBLINGS[module_key]
+    return {"provider": label, "skill": skill_dir, "status": "unavailable",
+            "looked_up_at": _now_iso(), "data": None, "note": note}
+
+def _load(module_key: str) -> Any | None:
+    """단품 스킬 helper를 레포 레이아웃 기준 파일 경로로 로드. 없으면 None."""
+    _, skill_dir, filename = _SIBLINGS[module_key]
+    path = _REPO_ROOT / skill_dir / "scripts" / filename
+    if not path.exists():
+        return None
+    spec = importlib.util.spec_from_file_location(f"_bhc_{module_key}", path)
+    if spec is None or spec.loader is None:
+        return None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def _section(module_key: str, caller: Callable[[Any], dict]) -> dict:
+    """단품 helper 하나를 호출해 섹션 결과로 감싼다. 어떤 오류든 강등."""
+    label, skill_dir, _ = _SIBLINGS[module_key]
+    base = {"provider": label, "skill": skill_dir, "looked_up_at": _now_iso()}
+    try:
+        module = _load(module_key)
+    except Exception as err:
+        return {**base, "status": "unavailable", "data": None,
+                "note": f"단품 스킬 '{skill_dir}' helper import 실패({type(err).__name__}: {err})."}
+    if module is None:
+        return {**base, "status": "unavailable", "data": None,
+                "note": f"단품 스킬 '{skill_dir}' helper를 찾지 못해 건너뜀 (개별 설치 시 함께 두세요)."}
+    try:
+        data = caller(module)
+        status = "unavailable" if isinstance(data, dict) and (data.get("status") == "unavailable" or data.get("error")) else "ok"
+        return {**base, "status": status, "data": data}
+    except Exception as err:  # 경계 계약: 한 항목 실패가 전체를 막지 않는다
+        return {**base, "status": "unavailable", "data": None, "note": f"조회 실패({type(err).__name__}: {err})."}
+
+
+def run(b_no: str | None, name: str | None = None, region: str | None = None,
+        industries: list[str] | None = None, *, base_url: str | None = None) -> dict:
+    no = _normalize_b_no(b_no) if b_no else None
+    name = (name or "").strip() or None
+    sections: dict[str, dict] = {}
+
+    if no:
+        sections["nts_status"] = _section(
+            "nts_status", lambda m: m.query_status([no], base_url=base_url))
+    else:
+        sections["nts_status"] = _unavailable("nts_status", "사업자등록번호가 없어 상태조회 생략.")
+
+    sections["national_pension"] = _section(
+        "national_pension",
+        lambda m: m.query_workplace(name, no, base_url=base_url)) if name else \
+        _unavailable("national_pension", "상호(--name)가 없어 국민연금 조회 생략.")
+
+    sections["fsc_corp"] = _section(
+        "fsc_corp",
+        lambda m: m.query_corp_outline(name, no, base_url=base_url)) if name else \
+        _unavailable("fsc_corp", "법인명(--name)이 없어 금융위 조회 생략.")
+
+    sections["g2b_sanction"] = _section(
+        "g2b_sanction", lambda m: m.query_sanctions(no, base_url=base_url)) if no else \
+        _unavailable("g2b_sanction", "사업자등록번호가 없어 부정당제재 조회 생략.")
+
+    sections["tax_delinquency"] = _section(
+        "tax_delinquency", lambda m: m.lookup(name)) if name else \
+        _unavailable("tax_delinquency", "상호(--name)가 없어 체납 명단 조회 생략.")
+
+    if name and region:
+        sections["localdata"] = _section(
+            "localdata", lambda m: m.lookup(name, region, industries))
+    else:
+        sections["localdata"] = _unavailable("localdata", "동네 사업장 인허가 조회는 상호(--name)와 지역(--region)이 함께 필요.")
+
+    return {
+        "query": {"b_no": no, "name": name, "region": region, "industries": industries},
+        "generated_at": _now_iso(),
+        "disclaimer": ("무료 공공 데이터의 사실만 병렬한 실사 리포트다. 점수·등급·위험 판정은 "
+                       "하지 않으며, 동일성·해석은 사용자가 판단한다."),
+        "sections": sections,
+    }
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="사업자 실사 복합 조회 (단품 k-skill 6종 묶음)")
+    parser.add_argument("b_no", nargs="?", default=None, help="사업자등록번호 10자리(하이픈 허용)")
+    parser.add_argument("--name", help="상호·법인명 — 국민연금/금융위/체납/인허가 조회에 필요")
+    parser.add_argument("--region", help="시군구 (동네 사업장 인허가 조회용 — 예: 제주제주시)")
+    parser.add_argument("--industry", action="append", dest="industries", help="인허가 업종(여러 번 지정 가능)")
+    parser.add_argument("--proxy-base-url")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        report = run(args.b_no, args.name, args.region, args.industries, base_url=args.proxy_base_url)
+    except ValueError as err:
+        print(json.dumps({"error": str(err)}, ensure_ascii=False, indent=2), file=sys.stderr)
+        return 1
+    print(json.dumps(report, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/biz-health-check/skill.json

@@ -0,0 +1,10 @@
+{
+  "name": "biz-health-check",
+  "description": "사업자등록번호 하나로 \"이 사업자, 실제 문제 없나\"를 확인한다 — 국세청 사업자등록 상태·국민연금 가입 사업장·국세 체납 명단·금융위 법인개요·조달청 부정당제재·지방행정 인허가 영업상태를 무료 공공 데이터로 교차 조회해 사실만 병렬하는 실사 리포트(점수·등급·위험 판정 없음).",
+  "profiles": [
+    "proxy",
+    "vault",
+    "lookup"
+  ],
+  "frontmatter": "name: biz-health-check\ndescription: 사업자등록번호 하나로 \"이 사업자, 실제 문제 없나\"를 확인한다 — 국세청 사업자등록 상태·국민연금 가입 사업장·국세 체납 명단·금융위 법인개요·조달청 부정당제재·지방행정 인허가 영업상태를 무료 공공 데이터로 교차 조회해 사실만 병렬하는 실사 리포트(점수·등급·위험 판정 없음).\nlicense: MIT\nmetadata:\n  category: business\n  locale: ko-KR\n  phase: v1"
+}

package/skills/bok-ecos-stats/instruction.md

@@ -0,0 +1,95 @@
+# 한국은행 ECOS 경제통계 조회
+
+## What this skill does
+
+한국은행 경제통계시스템(ECOS) Open API `https://ecos.bok.or.kr/api/` 로 중앙은행 경제통계를 조회한다.
+
+- `search` — 통계코드(또는 alias) 기반 시계열 데이터 조회
+- `tables` — 통계표 카탈로그 목록
+- `items` — 특정 통계표의 항목(item) 목록
+- `key` — 100대 핵심지표 (환율/금리/물가/국민소득 등 최신값)
+- `word` — 통계 용어 사전 검색
+
+**조회 전용**이다. 투자 판단·전망 단정은 범위 밖이다.
+
+## When to use
+
+- "지금 한국은행 기준금리 몇 %야?"
+- "최근 원달러 환율 추이 보여줘"
+- "소비자물가지수 월별로 뽑아줘"
+- "M2 통화량 통계 찾아줘"
+- "ECOS에서 국고채 3년 금리 조회해줘"
+
+## When not to use
+
+- 주식/증권 시세 → `korean-stock-search`, `toss-securities`
+- KOSIS 일반 통계(인구/가구/고용 등) → `kosis-stats`
+- 환전 수수료·실시간 매매 환율 비교 (ECOS는 공식 통계 기준)
+
+## Prerequisites
+
+- Python 3.9+ (stdlib only, 외부 패키지 없음)
+- 사용자 API 키 **불필요** — ECOS 공개 데모 키(`sample`)로 무가입 동작 확인 (2026-07-21). 단 **호출당 최대 10행** 제한이 있다. 공개 엔드포인트이므로 k-skill-proxy를 경유하지 않고 직접 호출한다.
+
+선택 환경변수 (더 많은 행이 필요할 때):
+
+- `KSKILL_BOK_ECOS_API_KEY` — https://ecos.bok.or.kr/api 회원가입 후 무료 발급. `~/.config/k-skill/secrets.env` 의 같은 키도 읽는다.
+
+## Workflow
+
+### 1. 자주 쓰는 지표는 alias로 바로 조회
+
+```bash
+python3 bok-ecos-stats/scripts/bok_ecos.py search --alias 기준금리 --start 20260101 --end 20260721 --text
+python3 bok-ecos-stats/scripts/bok_ecos.py search --alias 원달러환율 --start 20260701 --end 20260721 --text
+python3 bok-ecos-stats/scripts/bok_ecos.py search --alias 소비자물가지수 --start 202501 --end 202606 --text
+```
+
+지원 alias: `기준금리`, `원달러환율`, `소비자물가지수`(=`cpi`), `M2`(=`통화량`), `국고채3년`.
+
+`--start`/`--end`는 주기 형식을 따른다: 일(D) `YYYYMMDD`, 월(M) `YYYYMM`, 분기(Q) `YYYYQn`, 연(A) `YYYY`.
+
+### 2. 최신 핵심지표 한 번에 보기
+
+```bash
+python3 bok-ecos-stats/scripts/bok_ecos.py key --limit 10 --text
+```
+
+### 3. 임의 통계표 탐색 → 항목 확인 → 시계열 조회
+
+```bash
+python3 bok-ecos-stats/scripts/bok_ecos.py tables --text
+python3 bok-ecos-stats/scripts/bok_ecos.py items --stat-code 722Y001 --text
+python3 bok-ecos-stats/scripts/bok_ecos.py search --stat-code 722Y001 --cycle D \
+  --start 20260101 --end 20260721 --item-code 0101000 --text
+```
+
+### 4. 용어가 낯설면 사전 검색
+
+```bash
+python3 bok-ecos-stats/scripts/bok_ecos.py word --query 소비자물가지수 --text
+```
+
+`--text` 없이 실행하면 구조화 JSON(`result`, `rows`, `source`)을 출력한다.
+
+## Data source
+
+- `https://ecos.bok.or.kr/api/<Service>/<key>/json/kr/<start>/<end>/<segments...>` — 쿼리스트링 없는 positional URL. 한글 검색어는 helper가 percent-encoding 처리한다.
+- 데모 키 `sample`: 무가입, 호출당 최대 10행 (초과 시 `ERROR-301`).
+- 잘못된 키: HTTP 200 + `{"RESULT":{"CODE":"INFO-100"}}`.
+- 빈 결과: `{"RESULT":{"CODE":"INFO-200","MESSAGE":"해당하는 데이터가 없습니다."}}` → `result: "empty"`.
+
+## Failure modes
+
+| 상황 | 동작 |
+| --- | --- |
+| 빈 결과 (`INFO-200`) | `result: "empty"` — 기간/코드 확인 안내 |
+| 인증키 오류 (`INFO-100`) | 개인 키 발급/확인 안내 |
+| sample 10행 초과 (`ERROR-301`) | 개인 키 발급 안내 (helper는 sample 사용 시 limit을 10으로 자동 캡) |
+| 알 수 없는 alias, stat-code 없는 search | upstream 미호출, 사용법 오류 출력 |
+| HTTP 오류/타임아웃/JSON 파싱 실패 | 차단·점검 가능성 안내 후 종료 코드 1 |
+
+## Notes
+
+- 시계열 값은 공식 통계 원천 그대로 전달하고, 해석·전망은 덧붙이지 않는다.
+- 통계 기준 시점(`time`)을 반드시 함께 표시한다.