@nomadamas/k-skill 0.1.0

package/skills/korean-character-count/instruction.md

@@ -0,0 +1,87 @@
+# 한국어 글자 수 세기
+
+## What this skill does
+
+자기소개서, 지원서, 자유서술형 폼처럼 **글자 수 제한이 중요한 한국어 텍스트**를 대상으로 LLM 추정 없이 결정론적으로 카운트한다.
+
+- 기본 글자 수: `Intl.Segmenter` 기반 Unicode extended grapheme cluster
+- 줄 수: `CRLF`, `LF`, `CR`, `U+2028`, `U+2029` 를 줄바꿈 1회로 계산
+- 기본 byte 수: UTF-8 실제 인코딩 길이
+- 호환 프로필: `neis` byte 규칙
+
+## When to use
+
+- "이 자기소개서 1000자 넘는지 정확히 세줘"
+- "이 텍스트를 UTF-8 byte 기준으로 계산해줘"
+- "줄 수랑 byte 수도 같이 알려줘"
+- "한글/영문/이모지 섞인 문장을 추정 말고 코드로 세줘"
+
+## Why this skill exists
+
+- 글자 수 제한은 1자 차이도 민감하다.
+- LLM이 글자 수를 눈대중으로 예측하면 재현성이 없다.
+- 이 스킬은 **입력을 임의로 trim/정규화하지 않고**, 문서화된 계약으로만 센다.
+
+## Contracts
+
+### `default` profile
+
+- characters: `Intl.Segmenter("ko", { granularity: "grapheme" })`
+- bytes: `Buffer.byteLength(text, "utf8")`
+- lines:
+  - empty string => `0`
+  - non-empty => 줄바꿈 시퀀스 수 + `1`
+  - `CRLF` 는 `2`줄바꿈이 아니라 `1`줄바꿈으로 센다.
+
+### `neis` profile
+
+- characters: `default` 와 동일
+- lines: `default` 와 동일
+- bytes:
+  - 한글 grapheme => `3B`
+  - ASCII grapheme => `1B`
+  - Enter/줄바꿈 시퀀스 => `2B`
+  - 그 외 문자는 UTF-8 byte 길이로 fallback
+
+## Prerequisites
+
+- `node` 18+
+- 설치된 skill payload 안에 `scripts/korean_character_count.js` helper 포함
+- 별도 API 키 없음
+
+## Workflow
+
+1. 텍스트를 직접 받거나 파일/STDIN으로 읽는다.
+2. `node scripts/korean_character_count.js` 로 결정론적 카운트를 실행한다.
+3. 필요한 프로필(`default`/`neis`)과 출력 형식(`json`/`text`)을 고른다.
+4. 결과를 그대로 반환하고, 어떤 계약으로 셌는지 함께 알려준다.
+
+## CLI examples
+
+```bash
+node scripts/korean_character_count.js --text "가나다"
+node scripts/korean_character_count.js --text $'첫 줄\r\n둘째 줄🙂'
+node scripts/korean_character_count.js --text $'첫 줄\n둘째 줄🙂' --profile neis --format text
+node scripts/korean_character_count.js --file ./essay.txt --profile default
+cat essay.txt | node scripts/korean_character_count.js --stdin --profile neis
+```
+
+## Response policy
+
+- 추정하지 말고 helper 결과를 그대로 쓴다.
+- 어떤 profile로 셌는지 함께 보여준다.
+- 기본값이 필요하면 `default` profile을 사용한다.
+- 제출처가 NEIS/학교생활기록부 같은 별도 계약을 요구할 때만 `neis` 를 쓴다.
+
+## Done when
+
+- 글자 수, 줄 수, byte 수가 함께 반환된다.
+- `default` 와 `neis` 계약 차이가 문서에 명시된다.
+- `node scripts/korean_character_count.js --help` 가 동작한다.
+- 혼합 한국어/영문/공백/개행/emoji 입력에 대한 테스트가 있다.
+
+## Notes
+
+- Unicode grapheme clusters: https://www.unicode.org/reports/tr29/
+- WHATWG Encoding Standard: https://encoding.spec.whatwg.org/
+- Node `Buffer.byteLength`: https://nodejs.org/api/buffer.html

package/skills/korean-character-count/scripts/korean_character_count.js

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+
+const LINE_BREAK_PATTERN = /\r\n|[\n\r\u2028\u2029]/gu;
+const HANGUL_OR_MARK_PATTERN = /^[\p{Script=Hangul}\p{Mark}]+$/u;
+const HAS_HANGUL_PATTERN = /\p{Script=Hangul}/u;
+const WHITESPACE_ONLY_PATTERN = /^\s+$/u;
+const ASCII_ONLY_PATTERN = /^[\x00-\x7F]+$/;
+
+function ensureSegmenter() {
+  if (!globalThis.Intl?.Segmenter) {
+    throw new Error("Intl.Segmenter is required. Use Node.js 18 or newer.");
+  }
+
+  return new Intl.Segmenter("ko", { granularity: "grapheme" });
+}
+
+function segmentGraphemes(text) {
+  return Array.from(ensureSegmenter().segment(text), ({ segment }) => segment);
+}
+
+function countUtf8Bytes(text) {
+  return Buffer.byteLength(text, "utf8");
+}
+
+function countLines(text) {
+  if (text.length === 0) {
+    return 0;
+  }
+
+  return Array.from(text.matchAll(LINE_BREAK_PATTERN)).length + 1;
+}
+
+function countNeisBytes(text) {
+  let total = 0;
+  let lastIndex = 0;
+
+  for (const match of text.matchAll(LINE_BREAK_PATTERN)) {
+    const breakIndex = match.index ?? 0;
+    total += countNeisChunkBytes(text.slice(lastIndex, breakIndex));
+    total += 2;
+    lastIndex = breakIndex + match[0].length;
+  }
+
+  total += countNeisChunkBytes(text.slice(lastIndex));
+  return total;
+}
+
+function countNeisChunkBytes(chunk) {
+  return segmentGraphemes(chunk).reduce((sum, grapheme) => sum + countNeisGraphemeBytes(grapheme), 0);
+}
+
+function countNeisGraphemeBytes(grapheme) {
+  if (!grapheme) {
+    return 0;
+  }
+
+  if (ASCII_ONLY_PATTERN.test(grapheme)) {
+    return 1;
+  }
+
+  if (HANGUL_OR_MARK_PATTERN.test(grapheme) && HAS_HANGUL_PATTERN.test(grapheme)) {
+    return 3;
+  }
+
+  return countUtf8Bytes(grapheme);
+}
+
+function createReport(text, profile = "default") {
+  const graphemes = segmentGraphemes(text);
+  const bytesUtf8 = countUtf8Bytes(text);
+  const bytesNeis = countNeisBytes(text);
+  const selectedBytes = profile === "neis" ? bytesNeis : bytesUtf8;
+
+  return {
+    profile,
+    contract: {
+      characters: "Unicode extended grapheme clusters via Intl.Segmenter",
+      bytes:
+        profile === "neis"
+          ? "NEIS-compatible bytes: Hangul grapheme=3B, ASCII grapheme=1B, each line break=2B, everything else falls back to UTF-8 bytes"
+          : "Actual UTF-8 encoded byte length",
+      lines:
+        "Empty string => 0 lines; otherwise count CRLF, LF, CR, U+2028, U+2029 as one line break each and add 1",
+    },
+    counts: {
+      characters: graphemes.length,
+      characters_without_whitespace: graphemes.filter((grapheme) => !WHITESPACE_ONLY_PATTERN.test(grapheme)).length,
+      code_points: Array.from(text).length,
+      utf16_code_units: text.length,
+      lines: countLines(text),
+      bytes: selectedBytes,
+      bytes_utf8: bytesUtf8,
+      bytes_neis: bytesNeis,
+    },
+  };
+}
+
+function parseArgs(argv, stdinIsTTY = process.stdin.isTTY) {
+  const options = {
+    format: "json",
+    inputMode: null,
+    profile: "default",
+    text: null,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      continue;
+    }
+
+    if (arg === "--text") {
+      setInputMode(options, "text");
+      options.text = readNextValue(argv, ++index, arg);
+      continue;
+    }
+
+    if (arg === "--file") {
+      setInputMode(options, "file");
+      options.file = readNextValue(argv, ++index, arg);
+      continue;
+    }
+
+    if (arg === "--stdin") {
+      setInputMode(options, "stdin");
+      continue;
+    }
+
+    if (arg === "--profile") {
+      const value = readNextValue(argv, ++index, arg);
+
+      if (!["default", "neis"].includes(value)) {
+        throw new Error(`Unknown profile: ${value}`);
+      }
+
+      options.profile = value;
+      continue;
+    }
+
+    if (arg === "--format") {
+      const value = readNextValue(argv, ++index, arg);
+
+      if (!["json", "text"].includes(value)) {
+        throw new Error(`Unknown format: ${value}`);
+      }
+
+      options.format = value;
+      continue;
+    }
+
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  if (options.help) {
+    return options;
+  }
+
+  if (!options.inputMode) {
+    if (stdinIsTTY) {
+      throw new Error("Provide exactly one input source with --text, --file, or --stdin.");
+    }
+
+    options.inputMode = "stdin";
+  }
+
+  return options;
+}
+
+function setInputMode(options, nextMode) {
+  if (options.inputMode) {
+    throw new Error("Provide exactly one input source with --text, --file, or --stdin.");
+  }
+
+  options.inputMode = nextMode;
+}
+
+function readNextValue(argv, index, flagName) {
+  const value = argv[index];
+
+  if (value == null) {
+    throw new Error(`Missing value after ${flagName}`);
+  }
+
+  return value;
+}
+
+function readInput(options) {
+  if (options.inputMode === "text") {
+    return options.text ?? "";
+  }
+
+  if (options.inputMode === "file") {
+    return fs.readFileSync(options.file, "utf8");
+  }
+
+  return fs.readFileSync(0, "utf8");
+}
+
+function formatTextReport(report) {
+  return [
+    `profile: ${report.profile}`,
+    `characters: ${report.counts.characters}`,
+    `characters_without_whitespace: ${report.counts.characters_without_whitespace}`,
+    `code_points: ${report.counts.code_points}`,
+    `utf16_code_units: ${report.counts.utf16_code_units}`,
+    `lines: ${report.counts.lines}`,
+    `bytes: ${report.counts.bytes}`,
+    `bytes_utf8: ${report.counts.bytes_utf8}`,
+    `bytes_neis: ${report.counts.bytes_neis}`,
+    `character_contract: ${report.contract.characters}`,
+    `byte_contract: ${report.contract.bytes}`,
+    `line_contract: ${report.contract.lines}`,
+  ].join("\n");
+}
+
+function printHelp() {
+  console.log(`Usage: node scripts/korean_character_count.js [--text <text> | --file <path> | --stdin] [--profile default|neis] [--format json|text]
+
+Deterministically count Korean text characters, lines, and bytes.
+
+Options:
+  --text <text>      Count the provided text
+  --file <path>      Read UTF-8 text from a file
+  --stdin            Read UTF-8 text from stdin
+  --profile <name>   default (grapheme + UTF-8) or neis
+  --format <name>    json (default) or text
+  --help, -h         Show this help text
+`);
+}
+
+function main(argv = process.argv.slice(2)) {
+  const options = parseArgs(argv);
+
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  const report = createReport(readInput(options), options.profile);
+  const output = options.format === "text" ? formatTextReport(report) : JSON.stringify(report, null, 2);
+
+  console.log(output);
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = {
+  countLines,
+  countNeisBytes,
+  countUtf8Bytes,
+  createReport,
+  formatTextReport,
+  main,
+  parseArgs,
+  segmentGraphemes,
+};

package/skills/korean-character-count/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "korean-character-count",
+  "description": "Count Korean text deterministically with exact grapheme, line, and byte contracts for self-intros and form limits.",
+  "profiles": [
+    "local"
+  ],
+  "frontmatter": "name: korean-character-count\ndescription: Count Korean text deterministically with exact grapheme, line, and byte contracts for self-intros and form limits.\nlicense: MIT\nmetadata:\n  category: writing\n  locale: ko-KR\n  phase: v1"
+}

package/skills/korean-cinema-search/instruction.md

@@ -0,0 +1,177 @@
+# Korean Cinema Search
+
+## What this skill does
+
+upstream 원본 [`hmmhmmhm/daiso-mcp`](https://github.com/hmmhmmhm/daiso-mcp) 와 npm package [`daiso`](https://www.npmjs.com/package/daiso) 를 사용해 **CGV, 메가박스, 롯데시네마 영화관 검색, 상영작, 시간표, 잔여석 조회**를 안내한다.
+
+이 저장소는 upstream 코드를 vendoring 하지 않는다. 기본 경로는 **MCP 서버를 직접 설치하지 않고 CLI로 먼저 확인하는 방식**이다.
+
+핵심 조회 경로:
+
+- CGV: `/api/cgv/theaters`, `/api/cgv/movies`, `/api/cgv/timetable`
+- 메가박스: `/api/megabox/theaters`, `/api/megabox/movies`, `/api/megabox/seats`
+- 롯데시네마: `/api/lottecinema/theaters`, `/api/lottecinema/movies`, `/api/lottecinema/seats`
+- health check: `npx --yes daiso health`
+
+## When to use
+
+- "강남 근처 CGV 찾아줘"
+- "오늘 메가박스 코엑스 상영작 알려줘"
+- "롯데시네마 월드타워 잔여석 확인해줘"
+- "주변 영화관 시간표 비교해줘"
+
+## When not to use
+
+- 예매, 결제, 좌석 선점, 로그인 자동화
+- 영화관 계정이나 멤버십 권한이 필요한 기능
+- upstream 서버 코드를 이 저장소에 복사해서 유지하려는 경우
+
+## Prerequisites
+
+- 인터넷 연결
+- `node` 20 권장
+- `npx` 또는 `npm`
+- 필요하면 `git`
+
+## Preferred setup: CLI first
+
+먼저 MCP 연결이 아니라 upstream CLI로 공개 endpoint를 확인한다.
+
+날짜가 있는 요청은 Asia/Seoul 기준 `YYYYMMDD` 로 정규화하고 `--playDate <YYYYMMDD>` 를 항상 붙인다. 사용자가 오늘이라고 말하거나 날짜를 생략하면 KST 오늘 날짜를 계산한다.
+
+```bash
+npx --yes daiso health
+npx --yes daiso get /api/cgv/theaters --keyword 강남 --limit 5 --json
+npx --yes daiso get /api/cgv/movies --keyword 강남 --playDate <YYYYMMDD> --json
+npx --yes daiso get /api/cgv/timetable --keyword 강남 --playDate <YYYYMMDD> --json
+npx --yes daiso get /api/megabox/theaters --keyword 코엑스 --limit 5 --json
+npx --yes daiso get /api/megabox/movies --keyword 코엑스 --playDate <YYYYMMDD> --json
+npx --yes daiso get /api/megabox/seats --keyword 코엑스 --playDate <YYYYMMDD> --limit 10 --json
+npx --yes daiso get /api/lottecinema/theaters --keyword 월드타워 --limit 5 --json
+npx --yes daiso get /api/lottecinema/movies --keyword 월드타워 --playDate <YYYYMMDD> --json
+npx --yes daiso get /api/lottecinema/seats --keyword 월드타워 --playDate <YYYYMMDD> --limit 10 --json
+```
+
+반복 사용이면 전역 설치도 가능하다.
+
+```bash
+npm install -g daiso
+export NODE_PATH="$(npm root -g)"
+daiso health
+```
+
+## Fallback: clone the original repository
+
+public endpoint 재시도나 버전 고정이 필요하면 원본 저장소를 clone 해서 build 결과물 `dist/bin.js` 를 직접 실행한다.
+
+```bash
+git clone https://github.com/hmmhmmhm/daiso-mcp.git
+cd daiso-mcp
+npm install
+npm run build
+node dist/bin.js health
+node dist/bin.js get /api/cgv/theaters --keyword 강남 --limit 5 --json
+node dist/bin.js get /api/cgv/timetable --keyword 강남 --playDate <YYYYMMDD> --json
+node dist/bin.js get /api/megabox/seats --keyword 코엑스 --playDate <YYYYMMDD> --limit 10 --json
+node dist/bin.js get /api/lottecinema/seats --keyword 월드타워 --playDate <YYYYMMDD> --limit 10 --json
+```
+
+## Required inputs
+
+### 1. Cinema chain
+
+체인이 없으면 먼저 묻는다.
+
+- 권장 질문: `어느 영화관을 볼까요? CGV, 메가박스, 롯데시네마 중 하나를 알려주세요.`
+
+### 2. Theater or area keyword
+
+지역이나 지점명이 없으면 바로 조회하지 말고 기준 위치를 받는다.
+
+- 권장 질문: `어느 지역이나 지점을 기준으로 볼까요? 예: 강남, 코엑스, 월드타워`
+
+### 3. Movie title when seats are requested
+
+잔여석 질문인데 영화명이 없으면 먼저 영화 후보를 조회하거나 영화명을 물어본다.
+
+### 4. Date
+
+사용자가 날짜를 말하면 그 날짜를 우선한다. 날짜가 없으면 Asia/Seoul 기준 오늘을 `YYYYMMDD` 로 계산해 `--playDate <YYYYMMDD>` 로 넘긴다.
+
+| 체인 | 후보 조회 | 상영작 | 시간표 또는 잔여석 | 날짜 |
+| --- | --- | --- | --- | --- |
+| CGV | `keyword`, 선택 `limit` | `keyword` 또는 `theaterId`, `playDate` | `keyword` 또는 `theaterId`, `movieId`, `playDate` | 필수로 명시 |
+| 메가박스 | `keyword`, 선택 `limit` | `keyword` 또는 `theaterId`, `playDate` | `keyword` 또는 `theaterId`, `movieId`, `playDate` | 필수로 명시 |
+| 롯데시네마 | `keyword`, 선택 `limit` | `keyword` 또는 `theaterId`, `playDate` | `keyword` 또는 `theaterId`, `movieId`, `playDate` | 필수로 명시 |
+
+## Workflow
+
+### 1. Check server health
+
+```bash
+npx --yes daiso health
+```
+
+### 2. Resolve theater candidates
+
+```bash
+npx --yes daiso get /api/cgv/theaters --keyword 강남 --limit 5 --json
+```
+
+후보가 여러 개면 상위 2개에서 3개만 요약하고 다시 확인받는다.
+
+### 3. Resolve movie candidates
+
+```bash
+npx --yes daiso get /api/cgv/movies --keyword 강남 --playDate <YYYYMMDD> --json
+```
+
+영화 후보가 많으면 제목과 등급만 짧게 정리한다.
+
+### 4. Check timetable or seats
+
+CGV는 시간표 중심으로 본다.
+
+```bash
+npx --yes daiso get /api/cgv/timetable --keyword 강남 --playDate <YYYYMMDD> --json
+```
+
+메가박스와 롯데시네마는 잔여석 endpoint를 사용할 수 있다.
+
+```bash
+npx --yes daiso get /api/megabox/seats --keyword 코엑스 --playDate <YYYYMMDD> --limit 10 --json
+npx --yes daiso get /api/lottecinema/seats --keyword 월드타워 --playDate <YYYYMMDD> --limit 10 --json
+```
+
+### 5. Respond conservatively
+
+최종 응답은 짧게 정리한다.
+
+- 영화관 체인
+- 기준 지역이나 지점
+- 상영작 또는 선택 영화
+- 시간표와 잔여석
+- 조회 시각과 공개 endpoint 특성상 변동 가능하다는 점
+
+예매와 결제는 자동화하지 않는다.
+
+## Done when
+
+- `hmmhmmhm/daiso-mcp` 원본 repo와 `daiso` CLI 사용 경로를 명시했다.
+- MCP 서버를 직접 설치하는 대신 CLI first 흐름을 제시했다.
+- CGV, 메가박스, 롯데시네마 조회 범위를 구분했다.
+- 영화관 검색, 상영작, 시간표, 잔여석 중 필요한 호출을 실제로 안내했다.
+- 예매와 결제 자동화가 범위 밖임을 명시했다.
+
+## Failure modes
+
+- public endpoint는 upstream 상태에 따라 간헐적인 5xx를 줄 수 있다.
+- 지역 키워드가 넓으면 다른 지점이 섞일 수 있다.
+- 시간표와 잔여석은 시점에 따라 달라진다.
+- 일부 체인은 상영작, 시간표, 잔여석 endpoint의 입력값이 다르므로 theaterId, movieId가 있으면 그 값을 우선 사용한다.
+
+## Notes
+
+- 원본 프로젝트: `https://github.com/hmmhmmhm/daiso-mcp`
+- npm package: `https://www.npmjs.com/package/daiso`
+- 이 저장소는 upstream 코드를 vendoring 하지 않고 skill/docs만 유지한다.

package/skills/korean-cinema-search/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "korean-cinema-search",
+  "description": "CGV, 메가박스, 롯데시네마 영화관 검색, 상영작, 시간표, 잔여석 조회가 필요할 때 사용한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "action:booking"
+  ],
+  "frontmatter": "name: korean-cinema-search\ndescription: CGV, 메가박스, 롯데시네마 영화관 검색, 상영작, 시간표, 잔여석 조회가 필요할 때 사용한다. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: entertainment\n  locale: ko-KR\n  phase: v1"
+}

package/skills/korean-heritage-search/instruction.md

@@ -0,0 +1,106 @@
+# 한국 국가유산 검색
+
+## What this skill does
+
+국가유산청(현 국가유산청 영문 Korea Heritage Service)의 공식 Open API에서 국가유산 목록·상세정보와 월별 국가유산 활용 행사를 조회한다.
+
+v1은 공식 XML API를 직접 호출하며, 별도 API key·로그인·프록시가 필요 없다.
+
+- 국가유산명·지역 기준 검색
+- 국가유산 상세 설명·주소·좌표·이미지 조회
+- 연도·월별 국가유산 행사 조회
+
+## When to use
+
+- "경복궁 관련 국가유산 찾아줘"
+- "서울 국보 목록 보여줘"
+- "숭례문 역사와 주소 알려줘"
+- "이번 달 국가유산 행사 알려줘"
+- "전주 지역 국가유산을 검색해줘"
+
+## When not to use
+
+- 현재 입장 가능 여부, 운영시간, 입장료를 확정해야 하는 경우
+- 실시간 통제·혼잡도·주차 가능 여부가 필요한 경우
+- 예매·결제·행사 신청을 자동화해야 하는 경우
+
+## Prerequisites
+
+- 인터넷 연결
+- Python 3.10+
+- 설치된 skill payload 안에 `scripts/korean_heritage_search.py` helper가 포함되어 있다.
+- 별도 API key나 로그인은 필요 없다.
+
+## Inputs
+
+### Search
+
+- 선택: 국가유산명 검색어
+- 선택: 시도명 또는 시도 코드
+- 선택: 페이지 번호
+- 선택: 결과 수(1~100)
+
+지원 지역명: 서울, 부산, 대구, 인천, 광주, 대전, 울산, 경기, 강원, 충북, 충남, 전북, 전남, 경북, 경남, 제주, 세종.
+
+### Detail
+
+목록 결과에서 받은 다음 세 식별자가 필요하다.
+
+- `ccbaKdcd`
+- `ccbaAsno`
+- `ccbaCtcd`
+
+### Events
+
+- 필수: 연도(`YYYY`)
+- 필수: 월(`1~12`)
+- 선택: 시도명·시군구명 부분 필터
+
+## Workflow
+
+1. 국가유산명과 지역을 확인한다. 모호한 요청이면 먼저 검색 결과를 보여주고 상세 대상을 선택하게 한다.
+2. 공식 `SearchKindOpenapiList.do`에서 목록을 조회한다.
+3. 목록 결과의 `ccbaKdcd`, `ccbaAsno`, `ccbaCtcd`를 사용해 `SearchKindOpenapiDt.do` 상세를 조회한다.
+4. 행사 요청이면 `selectEventListOpenapi.do`에 연도·월을 넣고, 반환된 지역·기간·행사명·공식 링크를 정리한다.
+5. 결과에 공식 출처 URL과 조회 시각을 포함한다.
+6. 입장료·운영시간·현재 행사 진행 여부처럼 변동 가능성이 있는 정보는 상세 API의 사실과 별도로 표시하고, 공식 안내 페이지를 확인하도록 안내한다.
+
+## CLI examples
+
+```bash
+python3 scripts/korean_heritage_search.py search --query "경복궁" --region 서울 --limit 5
+python3 scripts/korean_heritage_search.py search --region 전북 --limit 10
+python3 scripts/korean_heritage_search.py detail --ccba-kdcd 11 --ccba-asno 0000010000000 --ccba-ctcd 11
+python3 scripts/korean_heritage_search.py events --year 2026 --month 7 --region 서울 --limit 10
+```
+
+## Response policy
+
+- 국가유산명, 유형, 지역, 주소, 좌표, 지정일, 설명, 관리기관을 공식 응답 그대로 요약한다.
+- 상세 조회에서 받은 `content`는 역사 설명으로 표시하고, 현재 운영 상태로 해석하지 않는다.
+- 행사 응답의 `subContent`는 HTML을 제거한 텍스트로 정리하되, 원문 링크(`subPath`)를 함께 제공한다.
+- 결과가 없으면 다른 국가유산명 표기나 지역 조건을 제안한다.
+- API에 없는 입장료·운영시간·통제 상태를 추정하지 않는다.
+
+## Done when
+
+- 검색 요청이면 공식 목록 결과와 `total_results`가 정리되어 있다.
+- 상세 요청이면 공식 식별자와 설명·주소·좌표·이미지가 정리되어 있다.
+- 행사 요청이면 연도·월, 행사명, 기간, 지역, 공식 링크가 정리되어 있다.
+- 응답에 공식 출처와 조회 시각이 포함되어 있다.
+
+## Failure modes
+
+- 국가유산명·지역 조건에 해당하는 결과가 없음
+- `ccbaKdcd`, `ccbaAsno`, `ccbaCtcd` 조합이 유효하지 않음
+- 국가유산청 API의 일시적 timeout, HTTP 오류, XML 오류
+- 행사 데이터의 설명 HTML 또는 기간 문자열이 불완전함
+- 오래된 API 응답으로 이미지 URL 또는 일부 필드가 비어 있음
+
+## Notes
+
+- 목록 API: `https://www.khs.go.kr/cha/SearchKindOpenapiList.do`
+- 상세 API: `https://www.khs.go.kr/cha/SearchKindOpenapiDt.do`
+- 행사 API: `https://www.khs.go.kr/cha/openapi/selectEventListOpenapi.do`
+- 공식 Open API 안내: `https://www.khs.go.kr/html/HtmlPage.do?mn=NS_04_04_03&pg=%2Fpublicinfo%2Fpbinfo3_0201.jsp`
+- 이 기능은 검색·조회 전용이며 예약, 결제, 신청을 수행하지 않는다.