@simplysm/sd-claude 14.0.53 → 14.0.55

package/claude/references/sd-simplysm-v14/core-node/README.md

@@ -9,51 +9,41 @@
 npm install @simplysm/core-node
 ```
 
-## 하려는 작업 → 먼저 읽을 파일
+## 하려는 작업 → 읽을 파일
 
-| 작업 | 먼저 읽을 파일 |
-|------|----------------|
-| 파일 읽기/쓰기/복사/삭제 | [fsx](./utils/fsx.md) |
-| 자식 프로세스 실행 | [cpx](./utils/cpx.md) |
-| 경로 변환/비교 | [pathx](./utils/pathx.md) |
-| 파일 변경 감시 | [FsWatcher](./features/fs-watcher.md) |
-| 로깅 설정 | [setupConsola](./logging/setup-consola.md) |
-| 커스텀 터미널 로깅 | [PrettyReporter](./logging/pretty-reporter.md) |
-| 커스텀 파일 로깅 | [createFileReporter](./logging/create-file-reporter.md) |
-| 워커 스레드로 작업 분리 | [Worker](./worker/worker.md) + [createWorker](./worker/create-worker.md) |
+### 파일 시스템 작업
 
-## API Overview
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 파일/디렉토리 읽기, 쓰기, 복사, 삭제, glob 검색 | [fsx](./utils/fsx.md) |
+| 파일/디렉토리 변경을 지속적으로 감시하고 이벤트를 받아야 할 때 | [FsWatcher](./features/fs-watcher.md) |
 
-### Utils
+### 프로세스 실행
 
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`fsx`](./utils/fsx.md) | namespace | 파일 시스템 작업(존재 확인, 읽기/쓰기, 복사, 삭제, glob)이 필요할 때 |
-| [`cpx`](./utils/cpx.md) | namespace | 외부 명령어나 자식 프로세스를 실행할 때 |
-| [`pathx`](./utils/pathx.md) | namespace | 경로를 POSIX 스타일로 변환하거나, 경로 간 관계(하위 경로 여부)를 확인할 때 |
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 외부 명령어(git, npm, 빌드 도구 등)를 실행하고 결과를 받아야 할 때 | [cpx](./utils/cpx.md) |
+| CPU 집약적 작업을 워커 스레드로 분리할 때 | [Worker](./worker/worker.md) + [createWorker](./worker/create-worker.md) |
 
-### Features
+### 경로 처리
 
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`FsWatcher`](./features/fs-watcher.md) | class | 파일/디렉토리 변경을 지속적으로 감시하고 이벤트를 받아야 할 때 |
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 경로를 POSIX 스타일로 변환하거나, 경로 간 관계를 확인할 때 | [pathx](./utils/pathx.md) |
 
-### Logging
+### 로깅 설정
 
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`setupConsola`](./logging/setup-consola.md) | function | 서버/CLI 시작 시 consola 로깅을 환경에 맞게 자동 구성할 때 |
-| [`PrettyReporter`](./logging/pretty-reporter.md) | class | 터미널에 아이콘/색상이 포함된 포맷으로 로그를 출력할 때 |
-| [`createFileReporter`](./logging/create-file-reporter.md) | function | 로그를 JSON 라인 파일로 기록하고 날짜별 로테이션이 필요할 때 |
-
-### Worker
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`Worker`](./worker/worker.md) | const | 메인 스레드에서 타입 안전하게 워커 메서드를 호출할 때 |
-| [`createWorker`](./worker/create-worker.md) | function | 워커 파일에서 메서드/이벤트를 등록할 때 (`Worker`와 쌍으로 사용) |
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 서버/CLI 시작 시 consola 로깅을 환경에 맞게 자동 구성할 때 | [setupConsola](./logging/setup-consola.md) |
+| 터미널에 아이콘/색상이 포함된 포맷으로 로그를 출력할 때 | [PrettyReporter](./logging/pretty-reporter.md) |
+| 로그를 JSON 라인 파일로 기록하고 날짜별 로테이션이 필요할 때 | [createFileReporter](./logging/create-file-reporter.md) |
 
 ## 이 패키지를 쓰지 말아야 할 때
 
 - 브라우저 환경 → `@simplysm/core-browser`
 - 플랫폼 중립 유틸리티(DateTime, UUID, EventEmitter 등) → `@simplysm/core-common`
+
+---
+
+> API 이름으로 검색: [_api-index.md](./_api-index.md)

package/claude/references/sd-simplysm-v14/core-node/_api-index.md

@@ -0,0 +1,34 @@
+# API Index — @simplysm/core-node
+
+> API 이름을 알고 있을 때 해당 문서를 찾는 인덱스.
+> 작업 기반으로 찾으려면 [README.md](./README.md) 참조.
+
+## Utils
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `fsx` | namespace | [fsx.md](./utils/fsx.md) | 파일 시스템 CRUD, glob 검색, JSON 파일 처리가 필요할 때 |
+| `cpx` | namespace | [cpx.md](./utils/cpx.md) | 외부 명령어나 자식 프로세스를 실행할 때 |
+| `pathx` | namespace | [pathx.md](./utils/pathx.md) | 경로를 POSIX 스타일로 변환하거나 경로 간 관계를 확인할 때 |
+
+## Features
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `FsWatcher` | class | [fs-watcher.md](./features/fs-watcher.md) | 파일/디렉토리 변경을 지속적으로 감시하고 이벤트를 받아야 할 때 |
+
+## Logging
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `setupConsola` | function | [setup-consola.md](./logging/setup-consola.md) | 서버/CLI 시작 시 consola 로깅을 환경별로 자동 구성할 때 |
+| `withMaxLevel` | function | [setup-consola.md](./logging/setup-consola.md) | reporter에 로그 레벨 상한선을 설정할 때 |
+| `PrettyReporter` | class | [pretty-reporter.md](./logging/pretty-reporter.md) | 터미널에 아이콘/색상이 포함된 포맷으로 로그를 출력할 때 |
+| `createFileReporter` | function | [create-file-reporter.md](./logging/create-file-reporter.md) | 로그를 JSON 라인 파일로 기록하고 날짜별 로테이션이 필요할 때 |
+
+## Worker
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `Worker` | const | [worker.md](./worker/worker.md) | 메인 스레드에서 타입 안전하게 워커 메서드를 호출할 때 |
+| `createWorker` | function | [create-worker.md](./worker/create-worker.md) | 워커 파일에서 메서드/이벤트를 등록할 때 |

package/claude/references/sd-simplysm-v14/core-node/features/fs-watcher.md

@@ -1,4 +1,6 @@
-# FsWatcher
+# `FsWatcher`
+
+> **읽어야 하는 상황**: 파일/디렉토리 변경을 지속적으로 감시하고, 짧은 시간 내 연속 이벤트를 하나로 병합해서 받아야 할 때. 단발성 파일 변경 확인은 `fsx.stat`으로 mtime 비교.
 
 Chokidar 기반 파일 시스템 감시 래퍼. 짧은 시간 내에 발생하는 이벤트를 병합하여 콜백을 한 번만 호출한다.
 EPERM 에러 발생 시 최대 3회까지 watcher를 자동 재시작한다.

package/claude/references/sd-simplysm-v14/core-node/logging/create-file-reporter.md

@@ -1,4 +1,6 @@
-# createFileReporter
+# `createFileReporter`
+
+> **읽어야 하는 상황**: 로그를 파일로 영구 보관하고, 날짜별 로테이션/크기 제한이 필요할 때. 터미널 출력은 [`PrettyReporter`](./pretty-reporter.md), 환경별 자동 구성은 [`setupConsola`](./setup-consola.md) 참조.
 
 파일 기반 consola reporter를 생성한다. `.logs/` 디렉토리에 `app.YYYY-MM-DD.log` 형식으로 JSON 라인을 기록하며, 날짜별 로테이션과 크기 제한을 지원한다.
 

package/claude/references/sd-simplysm-v14/core-node/logging/pretty-reporter.md

@@ -1,4 +1,6 @@
-# PrettyReporter
+# `PrettyReporter`
+
+> **읽어야 하는 상황**: 터미널에 아이콘/색상이 포함된 가독성 좋은 로그를 출력할 때. 로그를 파일로 저장하려면 [`createFileReporter`](./create-file-reporter.md), 환경별 자동 구성은 [`setupConsola`](./setup-consola.md) 참조.
 
 터미널 출력용 consola reporter. 로그 타입별 아이콘과 색상을 지원하며, 에러 스택 트레이스를 포맷팅한다.
 

package/claude/references/sd-simplysm-v14/core-node/logging/setup-consola.md

@@ -1,4 +1,6 @@
-# setupConsola
+# `setupConsola`
+
+> **읽어야 하는 상황**: 서버/CLI 애플리케이션 시작 시 환경별(개발/프로덕션) 로깅을 한 번에 구성할 때. reporter를 세밀하게 커스텀 조합하려면 [`createFileReporter`](./create-file-reporter.md)/[`PrettyReporter`](./pretty-reporter.md)를 직접 사용.
 
 환경에 따라 consola reporter를 자동 구성한다. 이 패키지의 `console.*` 사용 금지 규칙을 대체하는 표준 로깅 진입점이다.
 

package/claude/references/sd-simplysm-v14/core-node/utils/cpx.md

@@ -1,4 +1,6 @@
-# cpx
+# `cpx`
+
+> **읽어야 하는 상황**: 외부 명령어(git, npm, 빌드 도구 등)를 실행하고 결과를 받아야 할 때. CPU 집약적 작업을 별도 스레드로 분리하려면 [`Worker`](../worker/worker.md) 참조.
 
 자식 프로세스 실행 및 인코딩 감지 유틸리티 네임스페이스.
 

package/claude/references/sd-simplysm-v14/core-node/utils/fsx.md

@@ -1,4 +1,6 @@
-# fsx
+# `fsx`
+
+> **읽어야 하는 상황**: Node.js에서 파일/디렉토리 CRUD, glob 검색, JSON 파일 처리가 필요할 때. 자식 프로세스 실행은 [`cpx`](./cpx.md), 파일 변경 감시는 [`FsWatcher`](../features/fs-watcher.md) 참조.
 
 파일 시스템 작업을 위한 유틸리티 네임스페이스. 모든 연산은 동기(`*Sync`)와 비동기 쌍으로 제공된다.
 비동기 버전을 기본으로 사용하고, CLI 초기화 등 동기가 반드시 필요한 경우에만 동기 버전을 사용한다.

package/claude/references/sd-simplysm-v14/core-node/utils/pathx.md

@@ -1,4 +1,6 @@
-# pathx
+# `pathx`
+
+> **읽어야 하는 상황**: Windows 경로를 POSIX 슬래시로 정규화하거나, 경로 간 하위 관계를 확인하거나, 파일 경로의 디렉토리를 변경해야 할 때. 단순 `path.join`/`path.resolve`만 필요하면 Node.js `path` 모듈을 직접 사용.
 
 경로 처리 및 `PosixPath` 브랜드 타입 유틸리티 네임스페이스.
 

package/claude/references/sd-simplysm-v14/core-node/worker/create-worker.md

@@ -1,4 +1,6 @@
-# createWorker
+# `createWorker`
+
+> **읽어야 하는 상황**: 워커 파일에서 메인 스레드에 노출할 메서드를 정의하고, 메인 스레드로 이벤트를 보내야 할 때. 메인 스레드에서 워커를 호출하려면 [`Worker.create()`](./worker.md) 참조.
 
 Worker thread 파일에서 메서드와 이벤트 전송 함수를 등록하는 팩토리 함수. 메인 스레드의 [`Worker.create()`](./worker.md)와 쌍으로 사용한다.
 

package/claude/references/sd-simplysm-v14/core-node/worker/worker.md

@@ -1,4 +1,6 @@
-# Worker
+# `Worker`
+
+> **읽어야 하는 상황**: CPU 집약적 작업을 별도 워커 스레드로 분리하면서 타입 안전한 메서드 호출과 이벤트 수신이 필요할 때. 외부 프로세스 실행은 [`cpx.spawn`](../utils/cpx.md) 참조. 워커 파일 작성은 [`createWorker`](./create-worker.md) 참조.
 
 타입 안전한 Worker thread 프록시를 생성하는 팩토리 객체. `Worker.create()`로 워커 파일의 메서드를 메인 스레드에서 직접 호출할 수 있다.
 

package/claude/references/sd-simplysm-v14/excel/README.md

@@ -10,57 +10,43 @@
 npm install @simplysm/excel
 ```
 
-## 하려는 작업 → 먼저 읽을 파일
-
-| 작업 | 먼저 읽을 파일 |
-|------|----------------|
-| Excel 파일 생성/읽기/저장 | [ExcelWorkbook](./core-classes/excel-workbook.md) |
-| 셀 값/수식/스타일 설정 | [ExcelCell](./core-classes/excel-cell.md) |
-| 행/열 복사, 데이터 테이블, 이미지 삽입 | [ExcelWorksheet](./core-classes/excel-worksheet.md) |
-| Zod 스키마 기반 타입 안전한 읽기/쓰기 | [ExcelWrapper](./wrapper/excel-wrapper.md) |
-| 셀 주소 변환, 날짜↔숫자 변환 | [ExcelUtils](./utilities/excel-utils.md) |
-
-## API Overview
-
-### Core Classes
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`ExcelWorkbook`](./core-classes/excel-workbook.md) | class | xlsx 파일을 열거나 새로 만들 때. 워크시트 조회/생성, 바이트 내보내기의 진입점 |
-| [`ExcelWorksheet`](./core-classes/excel-worksheet.md) | class | 시트 내 셀/행/열 접근, 행 복사, 데이터 테이블 읽기/쓰기, 이미지 삽입이 필요할 때 |
-| [`ExcelCell`](./core-classes/excel-cell.md) | class | 개별 셀의 값/수식/스타일/병합을 조작할 때 |
-| [`ExcelRow`](./core-classes/excel-row.md) | class | 특정 행의 셀들을 일괄 접근할 때 |
-| [`ExcelCol`](./core-classes/excel-col.md) | class | 특정 열의 셀들을 일괄 접근하거나 열 너비를 설정할 때 |
-
-### Wrapper
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`ExcelWrapper`](./wrapper/excel-wrapper.md) | class | Zod 스키마로 타입 안전한 Excel 읽기/쓰기가 필요할 때. 헤더 자동 생성, 유효성 검사 포함 |
-
-### Utilities
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`ExcelUtils`](./utilities/excel-utils.md) | class | 셀 주소 문자열↔좌표 변환, Excel 날짜 숫자↔JS 타임스탬프 변환이 필요할 때 |
-
-### Types
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`ExcelValueType`](./types/excel-value-type.md) | type | 셀 값의 타입을 지정할 때. `ExcelCellType`, `ExcelNumberFormat` 포함 |
-| [`ExcelAddressPoint`](./types/excel-address-point.md) | interface | 셀 좌표를 전달할 때. `ExcelAddressRangePoint` 포함 |
-| [`ExcelStyleOptions`](./types/excel-style-options.md) | interface | 셀 스타일(배경색, 테두리, 정렬, 숫자 형식)을 설정할 때 |
-| [`ExcelXml`](./types/excel-xml.md) | interface | 내부 XML 처리 클래스의 공통 인터페이스 (직접 사용하지 않음) |
-| [`ExcelXmlContentTypeData`](./types/excel-xml-content-type-data.md) | interface | 내부 `[Content_Types].xml` 데이터 구조 (직접 사용하지 않음) |
-| [`ExcelXmlRelationshipData`](./types/excel-xml-relationship-data.md) | interface | 내부 `*.rels` 데이터 구조 (직접 사용하지 않음) |
-| [`ExcelXmlWorkbookData`](./types/excel-xml-workbook-data.md) | interface | 내부 `workbook.xml` 데이터 구조 (직접 사용하지 않음) |
-| [`ExcelXmlWorksheetData`](./types/excel-xml-worksheet-data.md) | interface | 내부 `worksheet*.xml` 데이터 구조 (직접 사용하지 않음) |
-| [`ExcelXmlDrawingData`](./types/excel-xml-drawing-data.md) | interface | 내부 `drawing*.xml` 데이터 구조 (직접 사용하지 않음) |
-| [`ExcelXmlSharedStringData`](./types/excel-xml-shared-string-data.md) | interface | 내부 `sharedStrings.xml` 데이터 구조 (직접 사용하지 않음) |
-| [`ExcelXmlStyleData`](./types/excel-xml-style-data.md) | interface | 내부 `styles.xml` 데이터 구조 (직접 사용하지 않음) |
+## 하려는 작업 → 읽을 파일
+
+### Excel 파일 생성·읽기·저장
+
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| xlsx 파일을 새로 만들거나 기존 파일을 열어 수정·저장할 때 | [ExcelWorkbook](./core-classes/excel-workbook.md) |
+| Zod 스키마로 타입 안전하게 Excel 파일을 읽기/쓰기할 때 | [ExcelWrapper](./wrapper/excel-wrapper.md) |
+
+### 셀·행·열 조작
+
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 개별 셀의 값·수식·스타일·병합을 설정할 때 | [ExcelCell](./core-classes/excel-cell.md) |
+| 행 단위로 셀들을 일괄 접근할 때 | [ExcelRow](./core-classes/excel-row.md) |
+| 열 단위로 셀들을 일괄 접근하거나 열 너비를 설정할 때 | [ExcelCol](./core-classes/excel-col.md) |
+| 셀 스타일(배경색, 테두리, 정렬, 숫자 형식) 옵션을 확인할 때 | [ExcelStyleOptions](./types/excel-style-options.md) |
+
+### 시트 데이터·레이아웃
+
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 행/열 복사, 데이터 테이블 읽기/쓰기, 이미지 삽입, 뷰 설정이 필요할 때 | [ExcelWorksheet](./core-classes/excel-worksheet.md) |
+
+### 주소·유틸리티
+
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| "A1" 형식 문자열과 0 기반 좌표 간 변환이 필요할 때 | [ExcelUtils](./utilities/excel-utils.md) |
+| 셀 좌표·범위 좌표 타입을 확인할 때 | [ExcelAddressPoint](./types/excel-address-point.md) |
+| 셀 값의 타입(ExcelValueType, ExcelCellType)을 확인할 때 | [ExcelValueType](./types/excel-value-type.md) |
 
 ## 이 패키지를 쓰지 말아야 할 때
 
 - xls(구형 바이너리 포맷) 파일 처리가 필요한 경우 -- xlsx만 지원한다
 - CSV 파일만 처리하면 되는 경우 -- 별도 CSV 파서가 더 적합하다
+
+---
+
+> API 이름으로 검색: [_api-index.md](./_api-index.md)

package/claude/references/sd-simplysm-v14/excel/_api-index.md

@@ -0,0 +1,40 @@
+# API Index — @simplysm/excel
+
+> API 이름을 알고 있을 때 해당 문서를 찾는 인덱스.
+> 작업 기반으로 찾으려면 [README.md](./README.md) 참조.
+
+## Core Classes
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `ExcelWorkbook` | class | [excel-workbook.md](./core-classes/excel-workbook.md) | xlsx 파일을 열거나 새로 만들 때 |
+| `ExcelWorksheet` | class | [excel-worksheet.md](./core-classes/excel-worksheet.md) | 시트 내 셀/행/열 접근, 행 복사, 데이터 테이블, 이미지 삽입이 필요할 때 |
+| `ExcelCell` | class | [excel-cell.md](./core-classes/excel-cell.md) | 개별 셀의 값/수식/스타일/병합을 조작할 때 |
+| `ExcelRow` | class | [excel-row.md](./core-classes/excel-row.md) | 특정 행의 셀들을 일괄 접근할 때 |
+| `ExcelCol` | class | [excel-col.md](./core-classes/excel-col.md) | 특정 열의 셀들을 일괄 접근하거나 열 너비를 설정할 때 |
+
+## Wrapper
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `ExcelWrapper` | class | [excel-wrapper.md](./wrapper/excel-wrapper.md) | Zod 스키마로 타입 안전한 Excel 읽기/쓰기가 필요할 때 |
+
+## Utilities
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `ExcelUtils` | class | [excel-utils.md](./utilities/excel-utils.md) | 셀 주소 변환, 날짜↔숫자 변환이 필요할 때 |
+
+## Types
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `ExcelValueType` | type | [excel-value-type.md](./types/excel-value-type.md) | 셀 값의 타입을 지정할 때 |
+| `ExcelCellType` | type | [excel-value-type.md](./types/excel-value-type.md) | Excel 셀 타입을 확인할 때 |
+| `ExcelNumberFormat` | type | [excel-style-options.md](./types/excel-style-options.md) | 숫자 형식 프리셋을 지정할 때 |
+| `ExcelAddressPoint` | interface | [excel-address-point.md](./types/excel-address-point.md) | 셀 좌표를 전달할 때 |
+| `ExcelAddressRangePoint` | interface | [excel-address-point.md](./types/excel-address-point.md) | 셀 범위 좌표를 전달할 때 |
+| `ExcelStyleOptions` | interface | [excel-style-options.md](./types/excel-style-options.md) | 셀 스타일을 설정할 때 |
+| `ExcelBorderPosition` | type | [excel-style-options.md](./types/excel-style-options.md) | 테두리 위치를 지정할 때 |
+| `ExcelHorizontalAlign` | type | [excel-style-options.md](./types/excel-style-options.md) | 가로 정렬을 지정할 때 |
+| `ExcelVerticalAlign` | type | [excel-style-options.md](./types/excel-style-options.md) | 세로 정렬을 지정할 때 |

package/claude/references/sd-simplysm-v14/excel/core-classes/excel-cell.md

@@ -1,4 +1,6 @@
-# ExcelCell
+# `ExcelCell`
+
+> **읽어야 하는 상황**: 개별 셀의 값·수식·스타일·병합을 조작할 때. 대량 데이터를 한번에 쓸 때는 [`ExcelWorksheet`](./excel-worksheet.md)의 `setDataMatrix()`/`setRecords()` 참조.
 
 Excel 셀을 나타내는 클래스. 값 읽기/쓰기, 수식, 스타일, 셀 병합 기능을 제공한다.
 

package/claude/references/sd-simplysm-v14/excel/core-classes/excel-col.md

@@ -1,4 +1,6 @@
-# ExcelCol
+# `ExcelCol`
+
+> **읽어야 하는 상황**: 특정 열의 셀들을 일괄 접근하거나 열 너비를 설정할 때. 행 단위 접근은 [`ExcelRow`](./excel-row.md) 참조.
 
 Excel 워크시트의 열을 나타내는 클래스. 셀 접근 및 열 너비 설정 기능을 제공한다.
 

package/claude/references/sd-simplysm-v14/excel/core-classes/excel-row.md

@@ -1,4 +1,6 @@
-# ExcelRow
+# `ExcelRow`
+
+> **읽어야 하는 상황**: 특정 행의 셀들을 일괄 접근할 때. 열 단위 접근은 [`ExcelCol`](./excel-col.md) 참조.
 
 Excel 워크시트의 행을 나타내는 클래스. 셀 접근 기능을 제공한다.
 

package/claude/references/sd-simplysm-v14/excel/core-classes/excel-workbook.md

@@ -1,4 +1,6 @@
-# ExcelWorkbook
+# `ExcelWorkbook`
+
+> **읽어야 하는 상황**: xlsx 파일을 새로 만들거나 기존 파일을 열어 수정·저장할 때. Zod 스키마 기반 타입 안전한 읽기/쓰기는 [`ExcelWrapper`](../wrapper/excel-wrapper.md) 참조.
 
 Excel 워크북 처리 클래스. 내부적으로 ZIP 리소스를 관리하므로 사용 후 반드시 `try-finally` 블록에서 `close()`를 호출해야 한다.
 
@@ -77,7 +79,9 @@ try {
   await wb.close();
 }
 
-### 전형 예제
+```
+
+### 기존 파일 읽기
 
 ```typescript
 // 기존 파일 읽기 (Uint8Array 또는 Blob)
@@ -90,4 +94,3 @@ try {
   await wb2.close();
 }
 ```
-```

package/claude/references/sd-simplysm-v14/excel/core-classes/excel-worksheet.md

@@ -1,4 +1,6 @@
-# ExcelWorksheet
+# `ExcelWorksheet`
+
+> **읽어야 하는 상황**: 시트 내 셀/행/열 접근, 행 복사, 데이터 테이블 읽기/쓰기, 이미지 삽입, 뷰 설정이 필요할 때. 타입 안전한 스키마 기반 읽기/쓰기는 [`ExcelWrapper`](../wrapper/excel-wrapper.md) 참조.
 
 Excel 워크시트를 나타내는 클래스. 셀 접근, 행/열 복사, 데이터 테이블 처리, 이미지 삽입, 뷰 설정 기능을 제공한다.
 

package/claude/references/sd-simplysm-v14/excel/types/excel-address-point.md

@@ -1,4 +1,6 @@
-# ExcelAddressPoint
+# `ExcelAddressPoint`
+
+> **읽어야 하는 상황**: 셀 좌표(`{r, c}`)나 셀 범위 좌표(`{s, e}`)를 전달할 때.
 
 셀 좌표를 나타내는 인터페이스이다. 모든 좌표는 0 기반이다.
 

package/claude/references/sd-simplysm-v14/excel/types/excel-style-options.md

@@ -1,4 +1,6 @@
-# ExcelStyleOptions
+# `ExcelStyleOptions`
+
+> **읽어야 하는 상황**: 셀 스타일(배경색, 테두리, 정렬, 숫자 형식)을 설정할 때. `ExcelNumberFormat`, `ExcelBorderPosition`, `ExcelHorizontalAlign`, `ExcelVerticalAlign` 타입도 이 파일에서 확인.
 
 셀 스타일 옵션 인터페이스이다. [`ExcelCell.setStyle()`](../core-classes/excel-cell.md)에서 사용한다.
 

package/claude/references/sd-simplysm-v14/excel/types/excel-value-type.md

@@ -1,4 +1,6 @@
-# ExcelValueType
+# `ExcelValueType`
+
+> **읽어야 하는 상황**: 셀 값의 타입이나 Excel 셀 타입(`ExcelCellType`)을 확인할 때.
 
 셀에 저장할 수 있는 값의 타입이다.
 

package/claude/references/sd-simplysm-v14/excel/utilities/excel-utils.md

@@ -1,4 +1,6 @@
-# ExcelUtils
+# `ExcelUtils`
+
+> **읽어야 하는 상황**: "A1" 형식 문자열과 0 기반 좌표 간 변환, JavaScript 타임스탬프와 Excel 날짜 숫자 간 변환이 필요할 때. 셀 값 읽기/쓰기 시 날짜 변환은 `ExcelCell`이 자동 처리하므로 직접 호출 불필요.
 
 Excel 유틸리티 함수 모음. 셀 주소 변환, 날짜/숫자 변환, 숫자 형식 처리 정적 메서드를 제공한다.
 

package/claude/references/sd-simplysm-v14/excel/wrapper/excel-wrapper.md

@@ -1,4 +1,6 @@
-# ExcelWrapper
+# `ExcelWrapper`
+
+> **읽어야 하는 상황**: Zod 스키마로 정형화된 레코드 구조의 Excel 파일을 타입 안전하게 읽기/쓰기할 때. 셀 단위 세밀한 조작(병합, 이미지, 수식 등)이 필요하면 [`ExcelWorkbook`](../core-classes/excel-workbook.md) + [`ExcelWorksheet`](../core-classes/excel-worksheet.md) 참조.
 
 Zod 스키마 기반 타입 안전한 Excel 읽기/쓰기 래퍼. 스키마에서 타입 정보를 추론하여 타입 안전한 읽기/쓰기를 제공한다.
 

package/claude/references/sd-simplysm-v14/orm-common/README.md

@@ -1,6 +1,7 @@
 # @simplysm/orm-common
 
-DBMS 독립적인 ORM 코어 라이브러리. TypeScript Fluent API로 스키마를 정의하고, SQL AST(QueryDef)를 경유하여 MySQL/MSSQL/PostgreSQL 세 방언(dialect)의 SQL을 생성한다.
+> DBMS 독립적인 ORM 코어 라이브러리. TypeScript Fluent API로 스키마를 정의하고, SQL AST(QueryDef)를 경유하여 MySQL/MSSQL/PostgreSQL 세 방언(dialect)의 SQL을 생성한다.
+> 의존성은 `@simplysm/core-common` 전용이며, 실제 DB 연결은 `DbContextExecutor` 인터페이스로 위임한다.
 
 ## 스키마 정의 지침
 
@@ -47,76 +48,66 @@ DBMS 독립적인 ORM 코어 라이브러리. TypeScript Fluent API로 스키마
 npm install @simplysm/orm-common
 ```
 
-## 하려는 작업 → 먼저 읽을 파일
-
-| 작업 | 먼저 읽을 파일 |
-|------|----------------|
-| 테이블/뷰 스키마 정의 | [Table](./schema-builders/table.md), [View](./schema-builders/view.md) |
-| DbContext 정의 및 연결/트랜잭션 관리 | [DbContext](./core/db-context.md) |
-| SELECT/INSERT/UPDATE/DELETE 쿼리 구성 | [Queryable](./queryable-executable/queryable.md) |
-| WHERE 조건, 집계, 문자열/날짜 표현식 작성 | [expr](./expression/expr.md) |
-| FK/관계 정의 (N:1, 1:N, 1:1) | [ForeignKeyBuilder](./schema-builders/foreign-key-builder.md) |
-| Stored Procedure 정의 및 실행 | [Procedure](./schema-builders/procedure.md), [Executable](./queryable-executable/executable.md) |
-| 사용자 검색어를 SQL LIKE 패턴으로 변환 | [parseSearchQuery](./queryable-executable/parse-search-query.md) |
-| QueryDef AST를 SQL 문자열로 변환 (테스트용) | [createQueryBuilder](./query-builder/create-query-builder.md) |
-| DB 원시 결과를 중첩 객체로 파싱 (커스텀 executor용) | [parseQueryResult](./types/parse-query-result.md) |
-
-## API Overview
-
-### Core
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-------------|
-| [`DbContext`](./core/db-context.md) | class | DB 연결/트랜잭션/DDL/초기화를 관리할 때 |
-| [`DbTransactionError`](./core/db-transaction-error.md) | class | 트랜잭션 에러를 DBMS 독립적으로 처리할 때 |
-
-### Queryable / Executable
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-------------|
-| [`Queryable`](./queryable-executable/queryable.md) | class | SELECT/INSERT/UPDATE/DELETE/UPSERT 쿼리를 체이닝으로 구성할 때 |
-| [`Executable`](./queryable-executable/executable.md) | class | Stored Procedure를 실행할 때 |
-| [`parseSearchQuery`](./queryable-executable/parse-search-query.md) | function | 사용자 검색 텍스트를 SQL LIKE 패턴으로 변환할 때 |
-
-### Expression
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-------------|
-| [`expr`](./expression/expr.md) | const | WHERE 조건, SELECT 표현식, 집계/윈도우 함수를 작성할 때 |
-| [`ExprUnit`](./expression/expr-unit.md) | class | 표현식의 타입 정보를 래핑하여 타입 안전 체인을 구성할 때 |
-
-### Schema Builders
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-------------|
-| [`Table`](./schema-builders/table.md) | function | 테이블 스키마를 정의할 때 |
-| [`View`](./schema-builders/view.md) | function | 뷰 스키마를 정의할 때 |
-| [`Procedure`](./schema-builders/procedure.md) | function | Stored Procedure 스키마를 정의할 때 |
-| [`ColumnBuilder`](./schema-builders/column-builder.md) | class | 컬럼의 타입/nullable/autoIncrement/default를 설정할 때 |
-| [`IndexBuilder`](./schema-builders/index-builder.md) | class | 인덱스를 정의할 때 |
-| [`ForeignKeyBuilder`](./schema-builders/foreign-key-builder.md) | class | FK/역참조/논리적 관계를 정의할 때 |
-
-### Models
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-------------|
-| [`_Migration`](./models/migration.md) | const | 마이그레이션 이력을 관리하는 시스템 테이블 |
-
-### Query Builder
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-------------|
-| [`createQueryBuilder`](./query-builder/create-query-builder.md) | function | QueryDef AST를 dialect별 SQL 문자열로 변환할 때 (테스트용) |
-
-### Types
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-------------|
-| [`Dialect`](./types/dialect.md) | type | DB 방언 및 런타임 타입을 참조할 때 |
-| [`DataType`](./types/data-type.md) | type | SQL 데이터 타입 매핑을 참조할 때 |
-| [`QueryDef`](./types/query-def.md) | type | SQL AST 구조를 이해할 때 |
-| [`Expr`](./types/expr.md) | type | 표현식 AST 구조를 이해할 때 |
-| [`parseQueryResult`](./types/parse-query-result.md) | function | DB 원시 결과를 중첩 TypeScript 객체로 변환할 때 (커스텀 executor용) |
+## 하려는 작업 → 읽을 파일
+
+### 스키마 정의
+
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 테이블 스키마를 정의할 때 (컬럼, PK, 인덱스) | [Table](./schema-builders/table.md) |
+| 뷰 스키마를 정의할 때 | [View](./schema-builders/view.md) |
+| Stored Procedure 스키마를 정의할 때 | [Procedure](./schema-builders/procedure.md) |
+| 컬럼의 타입/nullable/autoIncrement/default를 설정할 때 | [ColumnBuilder](./schema-builders/column-builder.md) |
+| 인덱스를 정의할 때 (유니크, 복합, 정렬 순서) | [IndexBuilder](./schema-builders/index-builder.md) |
+| FK/역참조/논리적 관계를 정의할 때 (N:1, 1:N, 1:1) | [ForeignKeyBuilder](./schema-builders/foreign-key-builder.md) |
+
+### DB 연결 및 초기화
+
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| DbContext를 정의하고 테이블/프로시저를 등록할 때 | [DbContext](./core/db-context.md) |
+| 연결/트랜잭션을 관리할 때 (connect, transaction) | [DbContext](./core/db-context.md) |
+| Code First 초기화 및 마이그레이션을 실행할 때 | [DbContext](./core/db-context.md) |
+| DDL 작업을 수행할 때 (createTable, addColumn 등) | [DbContext](./core/db-context.md) |
+| 트랜잭션 에러를 DBMS 독립적으로 처리할 때 | [DbTransactionError](./core/db-transaction-error.md) |
+
+### 쿼리 구성 및 실행
+
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| SELECT/INSERT/UPDATE/DELETE/UPSERT 쿼리를 체이닝으로 구성할 때 | [Queryable](./queryable-executable/queryable.md) |
+| JOIN, include, 재귀 CTE, UNION 쿼리를 구성할 때 | [Queryable](./queryable-executable/queryable.md) |
+| Stored Procedure를 실행할 때 | [Executable](./queryable-executable/executable.md) |
+| 사용자 검색 텍스트를 SQL LIKE 패턴으로 변환할 때 | [parseSearchQuery](./queryable-executable/parse-search-query.md) |
+
+### 표현식 작성
+
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| WHERE 조건을 작성할 때 (eq, gt, like, in, exists 등) | [expr](./expression/expr.md) |
+| SELECT 표현식을 작성할 때 (concat, dateDiff, cast 등) | [expr](./expression/expr.md) |
+| 집계 함수를 사용할 때 (sum, count, avg) | [expr](./expression/expr.md) |
+| 윈도우 함수를 사용할 때 (rowNumber, rank, lag, lead) | [expr](./expression/expr.md) |
+| CASE WHEN / IF 조건 분기를 작성할 때 | [expr](./expression/expr.md) |
+| Raw SQL 표현식을 사용할 때 (DB 전용 함수) | [expr](./expression/expr.md) |
+| 표현식 타입 래퍼를 이해할 때 | [ExprUnit](./expression/expr-unit.md) |
+
+### SQL 생성 및 결과 파싱
+
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| QueryDef AST를 dialect별 SQL 문자열로 변환할 때 (테스트용) | [createQueryBuilder](./query-builder/create-query-builder.md) |
+| DB 원시 결과를 중첩 TypeScript 객체로 변환할 때 (커스텀 executor용) | [parseQueryResult](./types/parse-query-result.md) |
+
+### 타입 참조
+
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| DB 방언 타입 및 격리 수준을 참조할 때 | [Dialect](./types/dialect.md) |
+| SQL 데이터 타입 매핑을 참조할 때 | [DataType](./types/data-type.md) |
+| SQL AST 구조를 이해할 때 | [QueryDef](./types/query-def.md) |
+| 표현식 AST 구조를 이해할 때 | [Expr](./types/expr.md) |
+| 마이그레이션 시스템 테이블을 참조할 때 | [_Migration](./models/migration.md) |
 
 ## Usage Examples
 
@@ -154,3 +145,7 @@ await db.connect(async () => {
 
 - 실제 DB 연결이 필요하면 `@simplysm/orm-node` (`NodeDbContextExecutor`)를 함께 사용한다. 이 패키지는 SQL AST 생성까지만 담당하고, DB 드라이버 연결은 제공하지 않는다.
 - 서비스 클라이언트에서 서버를 경유하여 DB에 접근하려면 `@simplysm/service-client`의 `SdServiceDbContextExecutor`를 사용한다.
+
+---
+
+> API 이름으로 검색: [_api-index.md](./_api-index.md)