saju8z 1.0.0 → 1.2.0

package/README.md

@@ -1,27 +1,361 @@
 # saju8z
 
-브라우저와 Node.js에서 생년월일시를 사주팔자로 변환하는 오프라인 만세력 계산 라이브러리입니다. 양력·한국 음력·윤달을 지원하며, 사주팔자와 십성 계산 결과를 객체·텍스트·JSON으로 사용할 수 있습니다.
+생년월일시로 사주팔자와 십성을 계산하고, 시간을 모르면 삼주(년·월·일)를 제공하는 만세력 CLI 라이브러리입니다. 
 
-- TypeScript 타입 선언과 ESM·CommonJS 빌드 제공
-- 네트워크·API 키·데이터베이스 없이 실행
-- 현재 시각과 실행 환경의 시간대에 의존하지 않는 계산
-- 음력 변환 의존성을 번들에 포함하여 별도 런타임 의존성 설치 불필요
+양력/음력/윤달을 지원하고, 결과를 텍스트/JSON/AI 전달용 프롬프트로 출력합니다.
 
-Node.js에서는 22 이상을 사용합니다. 브라우저에서는 ES2022를 지원하는 환경과 ESM 번들러를 사용할 수 있습니다.
+**Node.js 22 이상과 npm**이 필요합니다. 터미널에서 바로 사용하려면 `--date`·`--time` 또는 `--dt`를 본인의 생년월일시로 바꾸세요.
 
-## 설치
 
-사용할 프로젝트에서 npm 패키지를 설치합니다.
+
+## CLI 빠른 시작
+
+### 바로 실행하고 결과 보기
+
+전역 설치 없이 한 줄로 실행합니다. 아래 예시는 양력 2000년 2월 23일 00시 10분, 현재 GMT 기준입니다.
+
+```sh
+npx --yes saju8z --date 2000-02-25 --time 04:10
+```
+
+### 전역 설치 후 실행
+
+```sh
+npm install -g saju8z
+saju8z --date 2000-02-25 --time 04:10
+```
+
+
+
+### 인자 없이 실행하고 날짜·시각 입력하기
+
+옵션 없이 `saju8z`를 실행하면 생년월일과 출생 시각을 차례로 질문합니다. 아래처럼 값을 입력한 뒤 각각 Enter를 누르세요.
+
+```sh
+saju8z
+```
+
+입력 예시:
+
+```text
+생년월일과 출생 시각을 입력하세요. 양력·현재 GMT 시차로 계산합니다.
+생년월일 (YYYY-MM-DD, 예: 1998-03-05): 1998-03-05
+출생 시각 (HH:mm, 예: 11:00 / 시간을 모르면 비워두고 Enter): 11:00
+
+[만세력]
+...
+```
+
+- 날짜는 `1998-03-05`처럼 연도 4자리·월 2자리·일 2자리를 하이픈으로 구분합니다.
+- 시각은 `11:00`처럼 24시간제의 시·분을 콜론으로 구분합니다. 오후 11시는 `23:00`, 자정은 `00:00`입니다.
+- 시간을 모르면 시각 질문에서 아무것도 적지 않고 Enter를 누르세요. 삼주만 출력합니다.
+- 시간을 입력하면 **양력·실행 환경의 현재 GMT 시차·기본 텍스트 형식**으로 사주를 출력합니다. 시간을 생략하면 양력 날짜 기준으로 계산하며 GMT 환산과 -30분 보정은 생략합니다.
+- 잘못된 날짜·시각이나 빈 날짜는 오류로 종료합니다. 빈 시각은 시간 미상으로 처리합니다. 다시 실행해 입력하세요. 음력·윤달·고정 시차·다른 출력 형식은 아래 CLI 옵션을 사용하세요.
+
+대화형 입력은 **인자가 전혀 없을 때만** 시작합니다. 옵션을 전달하면 `--date` 또는 `--dt`가 필요하며, `--time`은 선택입니다. 입력 안내는 표준 오류(stderr), 계산 결과는 표준 출력(stdout)에 기록합니다.
+
+### 날짜와 시각을 한 번에 입력하기
+
+`--dt`는 날짜만 적는 **`YYYYMMDD` 8자리**와 시각까지 적는 **`YYYYMMDDHHmm` 12자리**를 지원합니다. `19980305`는 `--date 1998-03-05`와 같으며 삼주를 출력합니다. `199803051100`은 `--date 1998-03-05 --time 11:00`과 같은 사주를 출력합니다.
+
+```sh
+saju8z --dt 19980305
+saju8z --dt 199803051100
+saju8z --dt 199803051100 --gmt +09:00 --format json
+saju8z --dt=199803051100 --gmt +09:00 --format prompt
+```
+
+**옵션으로 실행할 때는 `--date` 또는 `--dt`를 입력해야 합니다. `--time`은 선택입니다.** `--dt`와 `--date`·`--time`을 혼용하면 오류가 발생합니다. 월·일·시·분은 각각 두 자리로 입력하며, 날짜와 시각의 유효성 검사는 기존 입력 방식과 같습니다. 시간이 있으면 `--gmt` 생략 시 현재 시차를 사용합니다. 시간이 없으면 시차 환산을 생략합니다. `--calendar lunar`·`--leap`는 두 방식 모두 사용할 수 있습니다.
+
+### 시간을 모를 때 삼주 출력
+
+```sh
+saju8z --date 1998-03-05
+saju8z --dt 19980305
+```
+
+위 두 명령은 동일한 삼주 결과를 반환합니다.
+
+```text
+
+[만세력]
+양력 날짜: 1998-03-05
+출생 시각: 미상 (삼주만 제공하며 시주는 추정하거나 해석하지 않습니다.)
+시간 미상으로 GMT 환산과 -30분 보정은 적용하지 않았습니다.
+일간: 신금(辛金)
+
+년주: 무인(戊寅)
+- 천간: 무(戊), 토(土), 정인
+- 지지: 인(寅), 목(木), 정재
+
+월주: 갑인(甲寅)
+- 천간: 갑(甲), 목(木), 정재
+- 지지: 인(寅), 목(木), 정재
+
+일주: 신해(辛亥)
+- 천간: 신(辛), 금(金), 본원
+- 지지: 해(亥), 수(水), 상관
+```
+
+시각이 없으면 입력 날짜를 그대로 사용합니다. 음력 입력은 양력으로 변환한 날짜를 사용하며, GMT 환산과 -30분 보정은 적용하지 않습니다. 입춘·절입 당일부터 새 년주·월주를 적용합니다. 이 기준은 출생 시각을 추정한 결과가 아닙니다.
 
 ```sh
-npm install saju8z
+saju8z --dt 19980305 --format json
+```
+
+<details>
+<summary>시간 미상 JSON 결과 펼치기</summary>
+
+```json
+{
+  "normalizedDateTime": {
+    "year": 1998,
+    "month": 3,
+    "day": 5,
+    "hour": null,
+    "minute": null
+  },
+  "calculationDateTime": {
+    "year": 1998,
+    "month": 3,
+    "day": 5,
+    "hour": null,
+    "minute": null
+  },
+  "fourPillars": {
+    "year": {
+      "stem": "무",
+      "branch": "인"
+    },
+    "month": {
+      "stem": "갑",
+      "branch": "인"
+    },
+    "day": {
+      "stem": "신",
+      "branch": "해"
+    },
+    "hour": null
+  },
+  "tenGods": {
+    "yearStem": "정인",
+    "yearBranch": "정재",
+    "monthStem": "정재",
+    "monthBranch": "정재",
+    "dayBranch": "상관",
+    "hourStem": null,
+    "hourBranch": null
+  }
+}
+```
+
+</details>
+
+시간 미상 결과는 `fourPillars.hour`, `tenGods.hourStem`, `tenGods.hourBranch`가 `null`이며, `normalizedDateTime`·`calculationDateTime`의 `hour`·`minute`도 `null`입니다. 두 날짜 객체는 같은 양력 날짜를 담습니다. 텍스트·프롬프트에는 년주·월주·일주만 표시하고, 프롬프트에는 시주를 추정하거나 해석하지 않도록 안내합니다.
+
+### 출력 형식 선택
+
+
+| 옵션                | 결과                       |
+| ----------------- | ------------------------ |
+| `--format text`   | 만세력 텍스트 (기본값)            |
+| `--format json`   | 환산·계산 시각, 사주팔자, 십성의 JSON |
+| `--format prompt` | AI 전달용 프롬프트 텍스트          |
+
+
+
+
+### 만세력 텍스트 출력:
+
+```text
+2000-02-25 04:10
 ```
 
-설치 후 `saju8z`에서 함수를 가져와 바로 사용할 수 있습니다. 패키지 사용을 위해 이 저장소를 내려받거나 직접 빌드할 필요는 없습니다.
 
-## 빠른 시작
 
-Node.js ESM, TypeScript, 브라우저 번들러 환경에서 동일하게 사용합니다.
+&nbsp;
+
+```text
+
+[만세력]
+양력 환산 시각: 2000-02-25 04:10 (GMT+09:00)
+-30분 보정 후 계산 시각: 2000-02-25 03:40
+일간: 계수(癸水)
+
+년주: 경진(庚辰)
+- 천간: 경(庚), 금(金), 정인
+- 지지: 진(辰), 토(土), 정관
+
+월주: 무인(戊寅)
+- 천간: 무(戊), 토(土), 정관
+- 지지: 인(寅), 목(木), 상관
+
+일주: 계축(癸丑)
+- 천간: 계(癸), 수(水), 본원
+- 지지: 축(丑), 토(土), 편관
+
+시주: 갑인(甲寅)
+- 천간: 갑(甲), 목(木), 상관
+- 지지: 인(寅), 목(木), 상관
+```
+
+
+
+**JSON 출력:**
+
+```sh
+npx --yes saju8z --date 2000-02-29 --time 00:10 --gmt +09:00 --format json
+```
+
+<details class="orca-details">
+<summary>실제 JSON 결과 펼치기</summary>
+
+```json
+{
+  "normalizedDateTime": {
+    "year": 2000,
+    "month": 2,
+    "day": 29,
+    "hour": 0,
+    "minute": 10
+  },
+  "calculationDateTime": {
+    "year": 2000,
+    "month": 2,
+    "day": 28,
+    "hour": 23,
+    "minute": 40
+  },
+  "fourPillars": {
+    "year": {
+      "stem": "경",
+      "branch": "진"
+    },
+    "month": {
+      "stem": "무",
+      "branch": "인"
+    },
+    "day": {
+      "stem": "병",
+      "branch": "진"
+    },
+    "hour": {
+      "stem": "무",
+      "branch": "자"
+    }
+  },
+  "tenGods": {
+    "yearStem": "편재",
+    "yearBranch": "식신",
+    "monthStem": "식신",
+    "monthBranch": "편인",
+    "dayBranch": "식신",
+    "hourStem": "식신",
+    "hourBranch": "정관"
+  }
+}
+```
+
+</details>
+
+
+
+**AI 전달용 프롬프트 출력:**
+
+```sh
+npx --yes saju8z --date 2000-02-29 --time 00:10 --gmt +09:00 --format prompt
+```
+
+해석 지침 사이에 만세력 계산 결과가 들어갑니다. 생성한 출력 전체를 AI 대화창에 붙여 넣어 사용합니다. 
+
+CLI 자체는 AI를 호출하거나 해석을 생성하지 않습니다.
+
+<details class="orca-details">
+<summary>실제 프롬프트 결과 펼치기</summary>
+
+```text
+너는 전통 명리학의 관점으로 사주 계산 결과를 설명하는 해설자다.
+
+아래 만세력 계산 결과를 바탕으로 사주를 설명해 줘.
+사주팔자를 다시 계산하지 말고 제공된 정보를 사용해 줘.
+
+[만세력]
+양력 환산 시각: 2000-02-29 00:10 (GMT+09:00)
+-30분 보정 후 계산 시각: 2000-02-28 23:40
+일간: 병화(丙火)
+
+년주: 경진(庚辰)
+- 천간: 경(庚), 금(金), 편재
+- 지지: 진(辰), 토(土), 식신
+
+월주: 무인(戊寅)
+- 천간: 무(戊), 토(土), 식신
+- 지지: 인(寅), 목(木), 편인
+
+일주: 병진(丙辰)
+- 천간: 병(丙), 화(火), 본원
+- 지지: 진(辰), 토(土), 식신
+
+시주: 무자(戊子)
+- 천간: 무(戊), 토(土), 식신
+- 지지: 자(子), 수(水), 정관
+
+다음 내용을 설명해라.
+1. 성격적으로 나타날 수 있는 경향과 강점
+2. 스트레스를 받을 때 나타날 수 있는 반응
+3. 대인관계와 의사소통에서 참고할 점
+4. 업무 방식과 협업에서 참고할 점
+5. 스스로 확인해 볼 질문 3가지
+
+답변 기준:
+- 전통적 상징 해석과 실제로 확인된 사실을 구분해라.
+- 사주 용어를 사용하지 마라.
+- 성격이나 미래를 단정하지 말고 가능한 경향으로 표현해라.
+- 10살짜리도 이해할 수 있도록 쉽게 풀어서 설명해라.
+- 제공되지 않은 대운·세운·지장간 등의 계산 결과를 만들어내지 마라.
+- 정보가 부족한 질문에는 무엇이 더 필요한지 설명해라
+```
+
+</details>
+
+
+
+### 음력과 윤달 입력
+
+양력은 기본값입니다. 한국 음력 날짜는 `--calendar lunar`를 추가하고, **음력 윤달이면 `--leap`도 함께** 지정합니다. 날짜와 출생 시각은 선택한 달력과 GMT 기준으로 입력합니다.
+
+```sh
+# 음력 평달 2017년 5월 1일 12:00
+npx --yes saju8z --date 2017-05-01 --time 12:00 --gmt +09:00 --calendar lunar
+
+# 음력 윤5월 1일 12:00 → 양력 2017-06-24 12:00과 같은 계산 결과
+npx --yes saju8z --date 2017-05-01 --time 12:00 --gmt +09:00 --calendar lunar --leap
+```
+
+
+
+### CLI 옵션과 시차
+
+
+| 옵션             | 필수  | 기본값·설명                                                |
+| -------------- | --- | ----------------------------------------------------- |
+| `--dt`         | 선택 | 날짜 `YYYYMMDD` 8자리 또는 날짜·시각 `YYYYMMDDHHmm` 12자리 |
+| `--date`       | 조건부 | 생년월일 `YYYY-MM-DD`. 옵션 실행 시 `--dt`가 없으면 필수                          |
+| `--time`       | 아니요 | 출생 시각 `HH:mm`, `00:00`\~`23:59`. 생략하면 삼주 출력 |
+| `--gmt`        | 아니요 | 고정 시차 `±HH:mm`, `-12:00`\~`+14:00` 기본값은 실행 환경의 현재 GMT |
+| `--calendar`   | 아니요 | `solar`(기본, 양력) 또는 `lunar`(한국 음력)                     |
+| `--leap`       | 아니요 | 음력 윤달일 때 지정. `--calendar lunar`와 함께 사용                |
+| `--format`     | 아니요 | `text`(기본), `json`, `prompt`                          |
+| `--help`, `-h` | 아니요 | 도움말 출력                                                |
+
+
+시차는 `--gmt -05:00` 또는 `--gmt=-05:00`처럼 전달합니다.
+
+`--gmt`를 생략하면 출생일 당시가 아닌 **실행 시점의 GMT 시차**를 사용합니다. 한국 표준시 환경에서는 `+09:00`이며, 서머타임을 사용하는 환경에서는 현재 서머타임도 반영됩니다. 출생 당시 위치의 시차로 계산하려면 해당 시차를 직접 지정하세요. 시간 미상일 때는 `--gmt` 값에 관계없이 날짜 기준 삼주를 계산합니다. 전달한 GMT 값의 형식과 범위는 계속 검증합니다.
+
+
+
+## 라이브러리 적용
 
 ```js
 import { calculateSajuChart, formatSajuChart } from "saju8z";
@@ -34,36 +368,39 @@ const result = calculateSajuChart({
 
 console.log(result.fourPillars); // 사주팔자 객체
 console.log(result.tenGods); // 십성 객체
-console.log(formatSajuChart(result, "text")); // Markdown 표 문자열
+console.log(formatSajuChart(result, "text")); // 만세력 텍스트 문자열
 console.log(formatSajuChart(result, "json")); // JSON 문자열
+console.log(formatSajuChart(result, "prompt")); // AI 전달용 프롬프트 문자열
 ```
 
-CommonJS에서는 `require`로 가져옵니다.
 
-```js
-const { calculateSajuChart, formatSajuChart } = require("saju8z");
 
-const result = calculateSajuChart({
-  date: "2000-02-29",
-  time: "00:10",
-  gmt: "+09:00"
-});
-console.log(formatSajuChart(result));
+시간을 모르면 라이브러리에서도 `time`을 생략하거나 `undefined`로 전달합니다.
+
+```ts
+const unknown = calculateSajuChart({ date: "1998-03-05", gmt: "+09:00" });
+console.log(unknown.fourPillars.hour); // null
+console.log(unknown.normalizedDateTime.hour); // null
+console.log(formatSajuChart(unknown)); // 년·월·일 삼주
 ```
 
+시간을 명시한 호출은 `SajuChartResultWithTime`, 생략한 호출은 `SajuChartResultWithoutTime`으로 추론됩니다. `SajuChartResult`는 두 결과의 유니온입니다. `time`이 선택적인 `SajuChartInput` 변수를 전달하면 결과도 유니온이므로 시주를 사용하기 전에 `null`을 확인하세요. 두 결과 타입은 `saju8z`와 `saju8z/format`에서 가져올 수 있습니다. 저수준 `saju8z/core`의 기존 사주 타입과 함수는 그대로 사용합니다.
+
 ## 입력
 
 `calculateSajuChart(input)`은 다음 객체를 받습니다.
 
-| 필드        | 타입      | 필수     | 설명                                                   |
-| ----------- | --------- | -------- | ------------------------------------------------------ | ------------------------------------- |
-| `date`      | `string`  | 예       | `YYYY-MM-DD`. 선택한 달력 기준의 날짜                  |
-| `time`      | `string`  | 예       | `HH:mm`, `00:00`\~`23:59`. 초는 지원하지 않음          |
-| `gmt`       | `string`  | 예       | 부호를 포함한 고정 시차 `±HH:mm`, `-12:00`\~`+14:00`   |
-| `calendar`  | `"solar"  | "lunar"` | 아니요                                                 | 양력 또는 한국 음력. 기본값 `"solar"` |
-| `leapMonth` | `boolean` | 아니요   | 음력 윤달 여부. 기본값 `false`, 음력에서만 `true` 허용 |
 
-GMT는 출생 당시 날짜·시간의 시차를 직접 지정합니다. 예를 들어 한국 표준시는 `+09:00`, UTC는 `+00:00`입니다. 실행 환경의 시간대나 지역 이름으로 자동 추정하지 않습니다.
+| 필드          | 타입                   | 필수  | 설명                                         |
+| ----------- | -------------------- | --- | ------------------------------------------ |
+| `date`      | `string`             | 예   | `YYYY-MM-DD`. 선택한 달력 기준의 날짜                |
+| `time`      | `string`             | 아니요 | `HH:mm`, `00:00`\~`23:59`. 생략 또는 `undefined`이면 시간 미상 |
+| `gmt`       | `string`             | 예   | 부호를 포함한 고정 시차 `±HH:mm`, `-12:00`\~`+14:00` |
+| `calendar`  | `"solar"`, `"lunar"` | 아니요 | 양력 또는 한국 음력. 기본값 `"solar"`                 |
+| `leapMonth` | `boolean`            | 아니요 | 음력 윤달 여부. 기본값 `false`, 음력에서만 `true` 허용     |
+
+
+라이브러리 API의 `gmt`는 출생 당시 날짜·시간의 시차를 직접 지정합니다. 예를 들어 한국 표준시는 `+09:00`, UTC는 `+00:00`입니다. 실행 환경의 시간대나 지역 이름으로 자동 추정하지 않습니다. `gmt`는 시간 미상 입력에서도 필수이며 형식을 검증하지만, 날짜 기준 계산에는 사용하지 않습니다. `time: ""`·`time: null`은 허용하지 않습니다. CLI에서도 `--time` 값을 비우는 대신 옵션을 생략하고, 대화형 질문에서만 빈 시각을 허용합니다.
 
 음력 윤달은 다음과 같이 입력합니다.
 
@@ -78,113 +415,73 @@ const result = calculateSajuChart({
 // 양력 2017-06-24 12:00, GMT+09:00 입력과 같은 결과
 ```
 
-## 결과와 출력 형식
-
-`calculateSajuChart`는 JSON으로 직렬화 가능한 `SajuChartResult` 객체를 반환합니다.
 
-| 필드                  | 내용                                                                                                        |
-| --------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `normalizedDateTime`  | 양력으로 변환하고 GMT+09:00으로 환산한 `{ year, month, day, hour, minute }`                                 |
-| `calculationDateTime` | 환산 시각에 -30분 보정을 적용한 계산 시각                                                                   |
-| `fourPillars`         | `year`, `month`, `day`, `hour`의 사주팔자. 각 값은 `{ stem, branch }`                                       |
-| `tenGods`             | 일간 기준 십성. `yearStem`, `yearBranch`, `monthStem`, `monthBranch`, `dayBranch`, `hourStem`, `hourBranch` |
-| `calculationProfile`  | 계산 규칙 식별자. 현재 `saju8z-fixed-gmt-kst-minus30-v1`                                                    |
 
-천간·지지·십성은 `"병"`, `"진"`, `"식신"`과 같은 한국어 문자열입니다. 일간 자체의 십성 필드는 없으며, 텍스트 표에서는 `본원`으로 표시합니다.
+## 결과와 출력 형식
 
-### 텍스트
+`calculateSajuChart`는 JSON으로 직렬화 가능한 `SajuChartResult` 객체를 반환합니다.
 
-`formatSajuChart(result)` 또는 `formatSajuChart(result, "text")`는 시주·일주·월주·년주 순서의 Markdown 표를 반환합니다. 천간·지지의 한자, 오행, 십성을 포함합니다. 빠른 시작 예제의 출력은 다음과 같습니다.
 
-```text
-| 구분 | 시주 | 일주 | 월주 | 년주 |
-| --- | --- | --- | --- | --- |
-| 천간 | 무(戊) | 병(丙) | 무(戊) | 경(庚) |
-| 천간 오행 | 土 | 火 | 土 | 金 |
-| 천간 십성 | 식신 | 본원 | 식신 | 편재 |
-| 지지 | 자(子) | 진(辰) | 인(寅) | 진(辰) |
-| 지지 오행 | 水 | 土 | 木 | 土 |
-| 지지 십성 | 정관 | 식신 | 편인 | 식신 |
-```
+| 필드                    | 내용                                                                                                    |
+| --------------------- | ----------------------------------------------------------------------------------------------------- |
+| `normalizedDateTime`  | 시간이 있으면 GMT+09:00으로 환산한 양력 시각. 시간이 없으면 양력 날짜와 `hour: null`, `minute: null`                                        |
+| `calculationDateTime` | 시간이 있으면 -30분 보정한 시각. 시간이 없으면 `normalizedDateTime`과 동일한 날짜·null 시각                                                                             |
+| `fourPillars`         | `year`, `month`, `day`, `hour`의 사주팔자. 시간이 없으면 `hour: null`                                         |
+| `tenGods`             | 일간 기준 십성. `yearStem`, `yearBranch`, `monthStem`, `monthBranch`, `dayBranch`, `hourStem`, `hourBranch`. 시간 미상이면 마지막 두 필드는 `null` |
 
-### JSON
 
-`formatSajuChart(result, "json")`은 결과 객체 전체를 들여쓰기한 JSON 문자열로 반환합니다. 저장하거나 전송할 때 사용합니다. 객체가 필요하면 `calculateSajuChart`의 반환값을 바로 사용하면 됩니다.
+천간·지지·십성은 `"병"`, `"진"`, `"식신"`과 같은 한국어 문자열입니다. 일간 자체의 십성 필드는 없으며, 만세력 텍스트에서는 `본원`으로 표시합니다.
 
-```js
-const json = formatSajuChart(result, "json");
-const restored = JSON.parse(json);
-console.log(restored.fourPillars.day); // { stem: "병", branch: "진" }
-```
 
-## TypeScript와 오류 처리
 
-주 진입점은 계산·출력 함수, 오류 클래스와 세 가지 타입을 제공합니다.
+## 추가 진입점
 
-```ts
-import { calculateSajuChart, formatSajuChart, UserInputError } from "saju8z";
-import type { SajuChartInput, SajuChartResult, SajuChartFormat } from "saju8z";
 
-const input: SajuChartInput = {
-  date: "2000-02-29",
-  time: "00:10",
-  gmt: "+09:00"
-};
-const format: SajuChartFormat = "json";
-
-try {
-  const result: SajuChartResult = calculateSajuChart(input);
-  console.log(formatSajuChart(result, format));
-} catch (error) {
-  if (error instanceof UserInputError) {
-    console.error(error.message);
-  } else {
-    throw error;
-  }
-}
-```
+| 가져오기 경로         | 용도                                                                 |
+| --------------- | ------------------------------------------------------------------ |
+| `saju8z`        | `calculateSajuChart`, `formatSajuChart`, `UserInputError` 및 입출력 타입 |
+| `saju8z/core`   | 저수준 계산 함수, 상수, 간지·오행 데이터와 도메인 타입                                   |
+| `saju8z/lunar`  | `lunarToSolar`, `lunarMonthDays`, `hasLunarLeapMonth`              |
+| `saju8z/format` | `formatSajuChart`, `SajuChartFormat`, `SajuChartResult` 타입         |
 
-잘못된 날짜·시각·GMT, 지원 범위 밖 날짜, 존재하지 않는 윤달은 `UserInputError`를 발생시킵니다. 출력 형식은 `"text"`와 `"json"`만 허용합니다.
 
-## 추가 진입점
+일반적인 만세력 계산에는 `saju8z`를 사용합니다. 저수준 함수는 입력 검증과 보정 적용 방식을 호출자가 확인해야 합니다.
 
-| 가져오기 경로   | 용도                                                                     |
-| --------------- | ------------------------------------------------------------------------ |
-| `saju8z`        | `calculateSajuChart`, `formatSajuChart`, `UserInputError` 및 입출력 타입 |
-| `saju8z/core`   | 저수준 계산 함수, 상수, 간지·오행 데이터와 도메인 타입                   |
-| `saju8z/lunar`  | `lunarToSolar`, `lunarMonthDays`, `hasLunarLeapMonth`                    |
-| `saju8z/format` | `formatSajuChart`, `SajuChartFormat`, `SajuChartResult` 타입             |
 
-일반적인 만세력 계산에는 `saju8z`를 사용합니다. 저수준 함수는 입력 검증과 보정 적용 방식을 호출자가 확인해야 합니다.
 
 ## 계산 기준과 지원 범위
 
+시간을 입력한 경우 기존 계산 기준을 적용합니다.
+
 1. 음력이면 양력으로 변환합니다.
 2. 입력 GMT에서 GMT+09:00으로 환산합니다.
 3. -30분을 보정한 시각으로 사주팔자를 계산합니다.
 
-년주는 입춘, 월주는 프로젝트의 고정 절입 시각 표, 일주는 자정을 기준으로 합니다. 고정 절입 표는 실제 연도별 천문 절기 시각과 차이가 있을 수 있습니다. 서머타임·역사적 시차·출생지 경도 보정은 자동 적용하지 않습니다.
+시간을 생략한 경우 음력 변환만 수행하고, 시차 환산과 -30분 보정 없이 해당 양력 날짜로 삼주를 계산합니다. 입춘·절입 당일부터 새 년주·월주를 적용하고 일주는 입력 날짜 기준입니다. 임의의 자정·정오를 출생 시각으로 대입하지 않습니다.
+
+시간을 입력한 경우 년주는 입춘, 월주는 프로젝트의 고정 절입 시각 표, 일주는 자정을 기준으로 합니다. 고정 절입 표는 실제 연도별 천문 절기 시각과 차이가 있을 수 있습니다. 서머타임·역사적 시차·출생지 경도 보정은 자동 적용하지 않습니다.
 
-양력 입력과 GMT+09:00 환산 날짜는 1900~2100년을 지원합니다. 음력은 1900년부터 음력 2050년 11월 18일까지의 유효 날짜를 지원합니다. -30분 보정으로 1900년 첫날이 전년 말로 이동할 수 있습니다.
+양력 입력과 GMT+09:00 환산 날짜는 1900~2100년을 지원합니다. 음력은 1900년부터 음력 2050년 11월 18일까지의 유효 날짜를 지원합니다. 시간을 입력하면 -30분 보정으로 1900년 첫날이 전년 말로 이동할 수 있습니다. 시간이 없으면 해당 날짜를 보존합니다.
 
 성별 입력은 필요하지 않습니다. 대운·세운·운세·성격 해석 기능은 제공하지 않습니다.
 
-## 소스 개발과 패키지 검증
 
-라이브러리 자체를 수정하는 경우 저장소를 내려받은 뒤 아래 명령을 사용합니다.
 
-```sh
-npm ci
-npm run build        # ESM·CommonJS 번들과 타입 선언 생성
-npm test             # 빌드 후 계산·출력 테스트
-npm run lint
-npm run typecheck
-npm pack --dry-run   # 배포 파일 목록 확인
-npm run test:package # tarball 설치 후 ESM/CJS·타입·브라우저·시간대 검증
-npm pack             # saju8z-1.0.0.tgz 생성
-```
+## 폴더 역할
+
+
+| 위치                         | 역할                            |
+| -------------------------- | ----------------------------- |
+| `src/input/`               | 입력 문자열 해석, 형식 검증, 사용자 입력 오류   |
+| `src/application/`         | 음력·시차 환산과 사주 계산 순서 조합         |
+| `src/calendar/`            | 날짜 산술, 음력 변환, 절기·태양시 보정       |
+| `src/saju/`, `src/domain/` | 사주·십성 계산 규칙, 타입과 기준 데이터       |
+| `src/output/`              | 만세력 텍스트 생성, 프롬프트 조립과 출력 형식 선택 |
+| `bin/`                     | CLI 옵션 해석과 표준 입출력             |
+| `test/`, `scripts/`        | 회귀 테스트, 빌드와 설치 패키지 검증         |
+
+
 
-계산 원본은 `src/`, 테스트는 `test/`, 빌드·패키지 검증 스크립트는 `scripts/`에 있습니다. JavaScript 스크립트는 `package.json`의 `"type": "module"` 설정에 따라 ES 모듈로 실행합니다. `dist/`는 빌드 산출물이며 npm 패키지에는 실행 번들·타입 선언·README·LICENSE·제3자 고지를 포함합니다.
 
 ## 라이선스
 
@@ -192,4 +489,4 @@ npm pack             # saju8z-1.0.0.tgz 생성
 
 상업적 사용·수정·재배포를 허용하며, 소프트웨어의 복사본이나 주요 부분에 저작권 및 라이선스 고지를 유지해야 합니다. 소프트웨어는 보증 없이 제공됩니다. 정확한 조건은 LICENSE 전문을 참고하세요.
 
-번들에 포함된 `korean-lunar-calendar`의 원 저작권 및 MIT 라이선스 고지는 [THIRD-PARTY-LICENSES.txt](THIRD-PARTY-LICENSES.txt)에 별도로 보존합니다.
+번들에 포함된 `korean-lunar-calendar`의 원 저작권 및 MIT 라이선스 고지는 [THIRD-PARTY-LICENSES.txt](THIRD-PARTY-LICENSES.txt)에 별도로 보존합니다.