@simplysm/sd-claude 14.0.53 → 14.0.55

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

@@ -0,0 +1,59 @@
+# API Index — @simplysm/orm-common
+
+> API 이름을 알고 있을 때 해당 문서를 찾는 인덱스.
+> 작업 기반으로 찾으려면 [README.md](./README.md) 참조.
+
+## Core
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `DbContext` | class | [db-context.md](./core/db-context.md) | DB 연결/트랜잭션/DDL/초기화를 관리할 때 |
+| `DbTransactionError` | class | [db-transaction-error.md](./core/db-transaction-error.md) | 트랜잭션 에러를 DBMS 독립적으로 처리할 때 |
+
+## Queryable / Executable
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `Queryable` | class | [queryable.md](./queryable-executable/queryable.md) | SELECT/INSERT/UPDATE/DELETE/UPSERT 쿼리를 체이닝으로 구성할 때 |
+| `Executable` | class | [executable.md](./queryable-executable/executable.md) | Stored Procedure를 실행할 때 |
+| `parseSearchQuery` | function | [parse-search-query.md](./queryable-executable/parse-search-query.md) | 사용자 검색 텍스트를 SQL LIKE 패턴으로 변환할 때 |
+
+## Expression
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `expr` | const | [expr.md](./expression/expr.md) | WHERE 조건, SELECT 표현식, 집계/윈도우 함수를 작성할 때 |
+| `ExprUnit` | class | [expr-unit.md](./expression/expr-unit.md) | 표현식의 타입 정보를 래핑하여 타입 안전 체인을 구성할 때 |
+
+## Schema Builders
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `Table` | function | [table.md](./schema-builders/table.md) | 테이블 스키마를 정의할 때 |
+| `View` | function | [view.md](./schema-builders/view.md) | 뷰 스키마를 정의할 때 |
+| `Procedure` | function | [procedure.md](./schema-builders/procedure.md) | Stored Procedure 스키마를 정의할 때 |
+| `ColumnBuilder` | class | [column-builder.md](./schema-builders/column-builder.md) | 컬럼의 타입/nullable/autoIncrement/default를 설정할 때 |
+| `IndexBuilder` | class | [index-builder.md](./schema-builders/index-builder.md) | 인덱스를 정의할 때 |
+| `ForeignKeyBuilder` | class | [foreign-key-builder.md](./schema-builders/foreign-key-builder.md) | FK/역참조/논리적 관계를 정의할 때 |
+
+## Models
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `_Migration` | const | [migration.md](./models/migration.md) | 마이그레이션 이력을 관리하는 시스템 테이블 |
+
+## Query Builder
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `createQueryBuilder` | function | [create-query-builder.md](./query-builder/create-query-builder.md) | QueryDef AST를 dialect별 SQL 문자열로 변환할 때 (테스트용) |
+
+## Types
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `Dialect` | type | [dialect.md](./types/dialect.md) | DB 방언 및 런타임 타입을 참조할 때 |
+| `DataType` | type | [data-type.md](./types/data-type.md) | SQL 데이터 타입 매핑을 참조할 때 |
+| `QueryDef` | type | [query-def.md](./types/query-def.md) | SQL AST 구조를 이해할 때 |
+| `Expr` | type | [expr.md](./types/expr.md) | 표현식 AST 구조를 이해할 때 |
+| `parseQueryResult` | function | [parse-query-result.md](./types/parse-query-result.md) | DB 원시 결과를 중첩 TypeScript 객체로 변환할 때 (커스텀 executor용) |

package/claude/references/sd-simplysm-v14/orm-common/core/db-context.md

@@ -1,4 +1,6 @@
-# DbContext
+# `DbContext`
+
+> **읽어야 하는 상황**: DbContext를 정의하여 테이블/프로시저를 등록하고, DB 연결/트랜잭션/DDL/초기화를 관리할 때. 쿼리 구성은 [`Queryable`](../queryable-executable/queryable.md), 표현식 작성은 [`expr`](../expression/expr.md) 참조.
 
 DB 연결/트랜잭션/DDL/초기화를 제공하는 추상 클래스. `queryable()`/`executable()`로 테이블/프로시저를 class 프로퍼티로 등록하며, 각 프로퍼티가 독립 직렬화되어 40+ 테이블에서도 TS7056이 발생하지 않는다.
 

package/claude/references/sd-simplysm-v14/orm-common/core/db-transaction-error.md

@@ -1,4 +1,6 @@
-# DbTransactionError
+# `DbTransactionError`
+
+> **읽어야 하는 상황**: 트랜잭션 롤백/커밋 실패 시 DBMS 독립적으로 에러를 분류하고 처리할 때. 연결/트랜잭션 관리 자체는 [`DbContext`](./db-context.md) 참조.
 
 DBMS별 네이티브 트랜잭션 에러를 표준화된 에러 코드로 래핑하는 에러 클래스. DBMS 독립적인 에러 처리를 지원한다.
 

package/claude/references/sd-simplysm-v14/orm-common/expression/expr-unit.md

@@ -1,4 +1,6 @@
-# ExprUnit
+# `ExprUnit`
+
+> **읽어야 하는 상황**: 표현식의 반환 타입 정보를 이해하거나, `ExprInput<T>` 타입으로 리터럴 값과 표현식을 혼합하여 사용할 때. 표현식 함수 자체는 [`expr`](./expr.md) 참조.
 
 타입 안전 표현식 래퍼. TypeScript 제네릭으로 표현식의 반환 타입을 추적한다. `expr.*` 함수들이 반환하며, `Queryable` 콜백에서 column 참조에 사용된다.
 

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

@@ -1,4 +1,6 @@
-# expr
+# `expr`
+
+> **읽어야 하는 상황**: WHERE 조건, SELECT 표현식, 집계/윈도우 함수, CASE WHEN 분기, Raw SQL 등 SQL 표현식을 작성할 때. 쿼리 체이닝은 [`Queryable`](../queryable-executable/queryable.md) 참조.
 
 Dialect 독립적 SQL 표현식 빌더 네임스페이스. SQL 문자열 대신 JSON AST(`Expr`)를 생성하며, `QueryBuilder`가 각 DBMS(MySQL, MSSQL, PostgreSQL)로 변환한다.
 

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

@@ -1,4 +1,6 @@
-# _Migration
+# `_Migration`
+
+> **읽어야 하는 상황**: 마이그레이션 시스템 테이블 구조를 참조할 때. `DbContext.initialize()`가 내부적으로 사용한다.
 
 시스템 마이그레이션 테이블 정의. `DbContext`가 내부적으로 사용하며, `initialize()`가 실행된 마이그레이션 이름을 이 테이블에 기록한다.
 

package/claude/references/sd-simplysm-v14/orm-common/query-builder/create-query-builder.md

@@ -1,4 +1,6 @@
-# createQueryBuilder
+# `createQueryBuilder`
+
+> **읽어야 하는 상황**: QueryDef AST를 dialect별 SQL 문자열로 변환할 때. 주로 테스트 목적으로 사용하며, 일반 쿼리 실행은 `Queryable.execute()`가 자동 처리한다.
 
 주어진 Dialect에 맞는 QueryBuilder 인스턴스를 생성한다. `Queryable.execute()` 내부에서 자동 호출되며, 직접 호출은 테스트 목적에만 사용한다.
 

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

@@ -1,4 +1,6 @@
-# Executable
+# `Executable`
+
+> **읽어야 하는 상황**: Stored Procedure를 실행할 때. Procedure 스키마 정의는 [`Procedure`](../schema-builders/procedure.md) 참조.
 
 Stored Procedure 실행 래퍼 클래스. `DbContext.executable()`로 등록된 프로퍼티를 호출하면 반환된다.
 

package/claude/references/sd-simplysm-v14/orm-common/queryable-executable/parse-search-query.md

@@ -1,4 +1,6 @@
-# parseSearchQuery
+# `parseSearchQuery`
+
+> **읽어야 하는 상황**: 사용자 검색 텍스트를 SQL LIKE 패턴으로 변환할 때. `Queryable.search()`가 내부적으로 사용하므로, 단순 검색은 [`Queryable`](./queryable.md)의 `search()` 메서드를 직접 사용하는 것이 간편하다.
 
 사용자 입력 검색 텍스트를 파싱하여 SQL LIKE 패턴으로 변환한다. `Queryable.search()`가 내부적으로 사용한다.
 

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

@@ -1,4 +1,6 @@
-# Queryable
+# `Queryable`
+
+> **읽어야 하는 상황**: SELECT/INSERT/UPDATE/DELETE/UPSERT 쿼리를 체이닝으로 구성하고 실행할 때. JOIN, include, 재귀 CTE, UNION, 페이지네이션 등 포함. 표현식 작성은 [`expr`](../expression/expr.md) 참조.
 
 SELECT/INSERT/UPDATE/DELETE/UPSERT 체인 빌더. 메서드 체이닝으로 쿼리를 구성하고 `execute()` 계열 메서드로 실행한다. `DbContext.queryable()`로 등록된 프로퍼티를 호출하면 반환된다.
 

package/claude/references/sd-simplysm-v14/orm-common/schema-builders/column-builder.md

@@ -1,4 +1,6 @@
-# ColumnBuilder
+# `ColumnBuilder`
+
+> **읽어야 하는 상황**: 컬럼의 데이터 타입, nullable, autoIncrement, default를 설정할 때. `Table().columns()` 및 `Procedure().params()`/`returns()` 콜백 내에서 팩토리 함수(`c.bigint()`, `c.varchar(100)` 등)를 통해 생성된다.
 
 Column 타입, nullable, autoIncrement, default, description을 정의하는 빌더. `TableBuilder.columns()` 및 `ProcedureBuilder.params()`/`returns()` 콜백에서 `createColumnFactory()`가 반환하는 팩토리 객체를 통해 생성된다.
 

package/claude/references/sd-simplysm-v14/orm-common/schema-builders/foreign-key-builder.md

@@ -1,4 +1,6 @@
-# ForeignKeyBuilder
+# `ForeignKeyBuilder`
+
+> **읽어야 하는 상황**: FK(N:1), 역참조(1:N, 1:1), 논리적 관계(DB FK 미생성)를 정의할 때. `Table().relations()` 또는 `View().relations()` 콜백 내에서 팩토리를 통해 생성된다.
 
 FK/역참조/논리적 관계 빌더들. `TableBuilder.relations()` 및 `ViewBuilder.relations()` 콜백에서 `createRelationFactory()`가 반환하는 팩토리 객체를 통해 생성된다.
 

package/claude/references/sd-simplysm-v14/orm-common/schema-builders/index-builder.md

@@ -1,4 +1,6 @@
-# IndexBuilder
+# `IndexBuilder`
+
+> **읽어야 하는 상황**: 인덱스를 정의할 때 (유니크, 복합, 정렬 순서). `Table().indexes()` 콜백 내에서 `i.index(...)` 팩토리를 통해 생성된다.
 
 Index 정의 빌더. `TableBuilder.indexes()` 콜백에서 `createIndexFactory()`가 반환하는 팩토리 객체를 통해 생성된다.
 

package/claude/references/sd-simplysm-v14/orm-common/schema-builders/procedure.md

@@ -1,4 +1,6 @@
-# Procedure
+# `Procedure`
+
+> **읽어야 하는 상황**: Stored Procedure 스키마를 정의할 때. 실행은 [`Executable`](../queryable-executable/executable.md) 참조.
 
 Fluent API로 Stored Procedure 스키마를 정의하는 빌더 팩토리 함수.
 

package/claude/references/sd-simplysm-v14/orm-common/schema-builders/table.md

@@ -1,4 +1,6 @@
-# Table
+# `Table`
+
+> **읽어야 하는 상황**: 테이블 스키마를 정의할 때 (컬럼, PK, 인덱스, 관계 포함). 뷰 정의는 [`View`](./view.md), Procedure 정의는 [`Procedure`](./procedure.md) 참조.
 
 Fluent API로 Database Table 스키마를 정의하는 빌더 팩토리 함수. 반환된 `TableBuilder`에 컬럼, PK, 인덱스, 관계를 메서드 체이닝으로 정의한다. 각 메서드는 새 인스턴스를 반환하므로 불변(immutable)이다.
 

package/claude/references/sd-simplysm-v14/orm-common/schema-builders/view.md

@@ -1,4 +1,6 @@
-# View
+# `View`
+
+> **읽어야 하는 상황**: 뷰 스키마를 정의할 때. SELECT 쿼리 기반으로 정의하며 논리적 관계(RelationKey)만 사용 가능하다. 테이블 정의는 [`Table`](./table.md) 참조.
 
 Fluent API로 Database View 스키마를 정의하는 빌더 팩토리 함수. 반환된 `ViewBuilder`에 쿼리와 관계를 메서드 체이닝으로 정의한다.
 

package/claude/references/sd-simplysm-v14/orm-common/types/data-type.md

@@ -1,4 +1,6 @@
-# DataType
+# `DataType`
+
+> **읽어야 하는 상황**: SQL 데이터 타입과 TypeScript 타입 간의 매핑을 참조하거나, `expr.cast()`에 전달할 대상 타입을 확인할 때.
 
 SQL 데이터 타입 및 TypeScript 타입 매핑 관련 타입/상수 모음.
 

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

@@ -1,4 +1,6 @@
-# Dialect
+# `Dialect`
+
+> **읽어야 하는 상황**: DB 방언 타입(`"mysql"` | `"mssql"` | `"postgresql"`)이나 격리 수준, executor 인터페이스를 참조할 때.
 
 지원하는 DB 방언 타입 및 관련 런타임 타입 모음.
 

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

@@ -1,4 +1,6 @@
-# Expr
+# `Expr`
+
+> **읽어야 하는 상황**: 표현식 AST 구조를 이해하거나, 커스텀 ExprRenderer를 구현할 때. 일반 표현식 작성에서는 [`expr`](../expression/expr.md)의 함수가 자동 생성하므로 직접 참조할 일이 드물다.
 
 SQL 표현식 AST 타입 모음. `expr.*` 함수들이 내부적으로 생성하며, `QueryBuilderBase`가 SQL 문자열로 변환한다.
 

package/claude/references/sd-simplysm-v14/orm-common/types/parse-query-result.md

@@ -1,4 +1,6 @@
-# parseQueryResult
+# `parseQueryResult`
+
+> **읽어야 하는 상황**: 커스텀 `DbContextExecutor`를 구현하여 DB 원시 결과를 중첩 TypeScript 객체로 변환할 때. `Queryable.execute()` 내부에서 자동 호출되므로 일반 사용에서는 직접 호출 불필요.
 
 DB 쿼리 원시 결과(`Record<string, unknown>[]`)를 `ResultMeta`를 이용해 타입 변환하고, JOIN 결과를 중첩 TypeScript 객체로 재구성한다. `Queryable.execute()` 내부에서 자동 호출되며, 직접 호출은 커스텀 executor 구현 시에만 필요하다.
 

package/claude/references/sd-simplysm-v14/orm-common/types/query-def.md

@@ -1,4 +1,6 @@
-# QueryDef
+# `QueryDef`
+
+> **읽어야 하는 상황**: SQL AST 구조를 이해하거나, 커스텀 QueryBuilder를 구현할 때. 일반 쿼리 실행에서는 `Queryable`이 자동 생성하므로 직접 참조할 일이 드물다.
 
 SQL AST 정의 타입 모음. `Queryable`이 내부적으로 생성하며, `QueryBuilderBase.build(def)`에 전달되어 SQL 문자열로 변환된다.
 

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

@@ -22,44 +22,43 @@ npm install pg pg-copy-streams
 npm install tedious
 ```
 
-## 하려는 작업 → 먼저 읽을 파일
+## 하려는 작업 → 읽을 파일
 
-| 작업 | 먼저 읽을 파일 |
-|------|----------------|
-| DbContext로 ORM 쿼리 실행 | [createOrm](./core/create-orm.md) |
-| 저수준 SQL 직접 실행 | [createDbConn](./core/create-db-conn.md) |
-| 연결 설정 구성 | [DbConnConfig](./types/db-conn-config.md) |
-| 특정 DBMS의 bulk insert 동작 확인 | [MssqlDbConn](./connections/mssql-db-conn.md), [MysqlDbConn](./connections/mysql-db-conn.md), [PostgresqlDbConn](./connections/postgresql-db-conn.md) |
-| DbConn 인터페이스 확인 | [DbConn](./types/db-conn.md) |
+### ORM 쿼리 실행
 
-## API Overview
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| DbContext 기반으로 트랜잭션 관리하며 ORM 쿼리를 실행할 때 | [createOrm](./core/create-orm.md) |
 
-### Types
+### SQL 직접 실행
 
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`DbConn`](./types/db-conn.md) | interface | DbConn 구현체의 공통 인터페이스를 확인할 때 |
-| [`DbConnConfig`](./types/db-conn-config.md) | type | DB 연결 설정을 구성할 때. `dialect` 필드로 DBMS를 결정한다 |
-| [`DB_CONN_CONNECT_TIMEOUT`](./types/db-conn-constants.md) | const | 타임아웃 상수나 오류 메시지 상수를 참조할 때 |
-| [`getDialectFromConfig`](./types/get-dialect-from-config.md) | function | `DbConnConfig`에서 정규화된 `Dialect`를 추출할 때 (`"mssql-azure"` → `"mssql"`) |
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| ORM 없이 생 SQL을 직접 실행하거나 연결 생명주기를 직접 제어할 때 | [createDbConn](./core/create-db-conn.md) |
+| 특정 DBMS의 bulk insert 동작이나 내부 구현을 확인할 때 (MSSQL) | [MssqlDbConn](./connections/mssql-db-conn.md) |
+| 특정 DBMS의 bulk insert 동작이나 내부 구현을 확인할 때 (MySQL) | [MysqlDbConn](./connections/mysql-db-conn.md) |
+| 특정 DBMS의 bulk insert 동작이나 내부 구현을 확인할 때 (PostgreSQL) | [PostgresqlDbConn](./connections/postgresql-db-conn.md) |
 
-### Connections
+### 연결 설정 및 타입
 
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`MssqlDbConn`](./connections/mssql-db-conn.md) | class | MSSQL/Azure SQL에 저수준으로 연결할 때 (tedious 사용) |
-| [`MysqlDbConn`](./connections/mysql-db-conn.md) | class | MySQL에 저수준으로 연결할 때 (mysql2/promise 사용) |
-| [`PostgresqlDbConn`](./connections/postgresql-db-conn.md) | class | PostgreSQL에 저수준으로 연결할 때 (pg + pg-copy-streams 사용) |
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| DB 연결 설정을 구성할 때 (`dialect`별 필드 확인) | [DbConnConfig](./types/db-conn-config.md) |
+| DBMS에 무관한 연결 인터페이스를 확인할 때 | [DbConn](./types/db-conn.md) |
+| 타임아웃 상수나 오류 메시지 상수를 참조할 때 | [DB_CONN_CONNECT_TIMEOUT](./types/db-conn-constants.md) |
+| `DbConnConfig`에서 정규화된 `Dialect`를 추출할 때 | [getDialectFromConfig](./types/get-dialect-from-config.md) |
 
-### Core
+### 내부 구현
 
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`createDbConn`](./core/create-db-conn.md) | function | dialect 기반으로 DbConn 인스턴스를 자동 생성할 때 |
-| [`NodeDbContextExecutor`](./core/node-db-context-executor.md) | class | DbContext 내부에서 사용하는 실행자. 직접 사용할 일은 거의 없다 |
-| [`createOrm`](./core/create-orm.md) | function | DbContext 서브클래스와 연결 설정으로 트랜잭션 관리 ORM 인스턴스를 만들 때 |
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| DbContext 내부 실행자의 동작을 확인하거나 커스텀 실행 파이프라인을 구성할 때 | [NodeDbContextExecutor](./core/node-db-context-executor.md) |
 
 ## 이 패키지를 쓰지 말아야 할 때
 
 - 브라우저/클라이언트에서 DB 접근 → `@simplysm/service-client`로 서버를 경유한다.
 - ORM 쿼리빌더·스키마 정의만 필요 → `@simplysm/orm-common`을 직접 사용한다.
+
+---
+
+> API 이름으로 검색: [_api-index.md](./_api-index.md)

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

@@ -0,0 +1,29 @@
+# API Index — @simplysm/orm-node
+
+> API 이름을 알고 있을 때 해당 문서를 찾는 인덱스.
+> 작업 기반으로 찾으려면 [README.md](./README.md) 참조.
+
+## Types
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `DbConn` | interface | [db-conn.md](./types/db-conn.md) | DBMS에 무관한 연결 객체의 공통 인터페이스를 확인할 때 |
+| `DbConnConfig` | type | [db-conn-config.md](./types/db-conn-config.md) | DB 연결 설정을 구성할 때. `dialect` 필드로 DBMS를 결정한다 |
+| `DB_CONN_CONNECT_TIMEOUT` | const | [db-conn-constants.md](./types/db-conn-constants.md) | 타임아웃 상수나 오류 메시지 상수를 참조할 때 |
+| `getDialectFromConfig` | function | [get-dialect-from-config.md](./types/get-dialect-from-config.md) | `DbConnConfig`에서 정규화된 `Dialect`를 추출할 때 |
+
+## Connections
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `MssqlDbConn` | class | [mssql-db-conn.md](./connections/mssql-db-conn.md) | MSSQL/Azure SQL에 저수준으로 연결할 때 |
+| `MysqlDbConn` | class | [mysql-db-conn.md](./connections/mysql-db-conn.md) | MySQL에 저수준으로 연결할 때 |
+| `PostgresqlDbConn` | class | [postgresql-db-conn.md](./connections/postgresql-db-conn.md) | PostgreSQL에 저수준으로 연결할 때 |
+
+## Core
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `createDbConn` | function | [create-db-conn.md](./core/create-db-conn.md) | dialect 기반으로 DbConn 인스턴스를 자동 생성할 때 |
+| `NodeDbContextExecutor` | class | [node-db-context-executor.md](./core/node-db-context-executor.md) | DbContext 내부에서 사용하는 실행자. 직접 사용할 일은 거의 없다 |
+| `createOrm` | function | [create-orm.md](./core/create-orm.md) | DbContext 서브클래스와 연결 설정으로 트랜잭션 관리 ORM 인스턴스를 만들 때 |

package/claude/references/sd-simplysm-v14/orm-node/connections/mssql-db-conn.md

@@ -1,5 +1,7 @@
 # `MssqlDbConn`
 
+> **읽어야 하는 상황**: MSSQL/Azure SQL의 저수준 연결 동작이나 bulk insert 구현을 확인할 때. 일반적으로 [`createDbConn`](../core/create-db-conn.md)이 자동 생성하므로 직접 사용할 일은 드물다.
+
 tedious 라이브러리를 사용하여 MSSQL/Azure SQL 연결을 관리하는 클래스.
 
 ## When to use

package/claude/references/sd-simplysm-v14/orm-node/connections/mysql-db-conn.md

@@ -1,5 +1,7 @@
 # `MysqlDbConn`
 
+> **읽어야 하는 상황**: MySQL의 저수준 연결 동작이나 bulk insert 구현을 확인할 때. 일반적으로 [`createDbConn`](../core/create-db-conn.md)이 자동 생성하므로 직접 사용할 일은 드물다.
+
 mysql2/promise 라이브러리를 사용하여 MySQL 연결을 관리하는 클래스.
 
 ## When to use

package/claude/references/sd-simplysm-v14/orm-node/connections/postgresql-db-conn.md

@@ -1,5 +1,7 @@
 # `PostgresqlDbConn`
 
+> **읽어야 하는 상황**: PostgreSQL의 저수준 연결 동작이나 bulk insert 구현을 확인할 때. 일반적으로 [`createDbConn`](../core/create-db-conn.md)이 자동 생성하므로 직접 사용할 일은 드물다.
+
 pg + pg-copy-streams 라이브러리를 사용하여 PostgreSQL 연결을 관리하는 클래스.
 
 ## When to use

package/claude/references/sd-simplysm-v14/orm-node/core/create-db-conn.md

@@ -1,5 +1,7 @@
 # `createDbConn`
 
+> **읽어야 하는 상황**: ORM 없이 생 SQL을 직접 실행하거나 트랜잭션·연결 생명주기를 직접 제어할 때. DbContext 기반 ORM을 사용하려면 [`createOrm`](./create-orm.md) 참조.
+
 dialect 기반 DbConn 팩토리. 네이티브 드라이버를 지연 로딩하여 DbConn 인스턴스를 생성한다.
 
 ## When to use

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

@@ -1,5 +1,7 @@
 # `createOrm`
 
+> **읽어야 하는 상황**: DbContext 기반으로 트랜잭션 관리하며 ORM 쿼리를 실행할 때. 생 SQL만 실행하려면 [`createDbConn`](./create-db-conn.md) 참조.
+
 Node.js ORM 팩토리 함수. `DbContext` 서브클래스와 DB 연결 설정을 받아 트랜잭션을 관리하는 [`Orm<T>`](#orm) 인스턴스를 반환한다.
 
 ## When to use

package/claude/references/sd-simplysm-v14/orm-node/core/node-db-context-executor.md

@@ -1,5 +1,7 @@
 # `NodeDbContextExecutor`
 
+> **읽어야 하는 상황**: DbContext 내부 실행자의 동작을 확인하거나 커스텀 실행 파이프라인을 구성할 때. 일반적인 ORM 사용은 [`createOrm`](./create-orm.md) 참조.
+
 `orm-common`의 `DbContextExecutor` 인터페이스를 구현하는 Node.js 환경용 실행자. `DbContext`에서 내부적으로 사용한다.
 
 ## When to use

package/claude/references/sd-simplysm-v14/orm-node/types/db-conn-config.md

@@ -1,5 +1,7 @@
 # `DbConnConfig`
 
+> **읽어야 하는 상황**: DB 연결 설정을 구성할 때. `dialect` 필드로 DBMS별 설정을 분기한다.
+
 DB 연결 설정 discriminated union. `dialect` 필드로 구현체를 분기한다.
 
 ```typescript

package/claude/references/sd-simplysm-v14/orm-node/types/db-conn-constants.md

@@ -1,5 +1,7 @@
 # `DB_CONN_CONNECT_TIMEOUT`
 
+> **읽어야 하는 상황**: 타임아웃 상수나 오류 메시지 상수의 값을 참조할 때.
+
 DB 연결 수립 타임아웃 (10초).
 
 ```typescript

package/claude/references/sd-simplysm-v14/orm-node/types/db-conn.md

@@ -1,5 +1,7 @@
 # `DbConn`
 
+> **읽어야 하는 상황**: DBMS에 무관한 코드에서 연결 객체의 공통 인터페이스를 확인할 때. 연결 설정 타입은 [`DbConnConfig`](./db-conn-config.md) 참조.
+
 저수준 DB 연결 인터페이스. 각 DBMS 구현체(`MssqlDbConn`, `MysqlDbConn`, `PostgresqlDbConn`)가 이 인터페이스를 구현한다.
 
 ## When to use

package/claude/references/sd-simplysm-v14/orm-node/types/get-dialect-from-config.md

@@ -1,5 +1,7 @@
 # `getDialectFromConfig`
 
+> **읽어야 하는 상황**: `DbConnConfig`에서 정규화된 `Dialect` 값을 추출할 때 (`"mssql-azure"` → `"mssql"` 변환).
+
 `DbConnConfig`에서 정규화된 `Dialect`를 추출한다.
 
 ```typescript

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

@@ -1,8 +1,8 @@
 # @simplysm/sd-claude
 
-Claude Code 에셋을 소비 프로젝트의 `.claude/` 디렉토리에 자동 설치하는 패키지. 다수의 스킬(`sd-*` 접두어 포함), 2개 rules 파일, 참조 문서, 6개 훅 스크립트를 포함한다. CLI(`sd-claude`)로 멀티 계정 전환 기능도 제공한다.
-
-TypeScript 소스 없음. `scripts/`는 Node.js `.mjs` 스크립트이고, `claude/`는 배포 에셋 디렉토리다.
+> Claude Code 에셋(스킬, 규칙, 훅, 참조 문서)을 소비 프로젝트의 `.claude/` 디렉토리에 자동 설치하는 패키지.
+> CLI(`sd-claude`)로 멀티 계정 전환 기능도 제공한다.
+> TypeScript 소스 없음. Node.js `.mjs` 스크립트와 배포 에셋으로 구성된다.
 
 ## Installation
 
@@ -10,76 +10,37 @@ TypeScript 소스 없음. `scripts/`는 Node.js `.mjs` 스크립트이고, `clau
 npm install @simplysm/sd-claude
 ```
 
-설치 시 `postinstall` 스크립트가 자동 실행되어, `claude/sd-*` 에셋과 `settings.json`을 프로젝트 루트 `.claude/`에 복사한다. `settings.json`은 훅이 미리 등록된 정적 파일이다.
-
-## API Overview
-
-### CLI Commands
-
-| API | Type | Description |
-|-----|------|-------------|
-| `sd-claude auth save` | CLI command | 현재 Claude Code 계정의 Organization 이름과 refresh token을 `~/.claude/profiles.json`에 저장 |
-| `sd-claude auth switch` | CLI command | 저장된 계정 목록을 표시하고 선택한 계정으로 전환 (TTY 필수) |
-
-→ See [docs/cli.md](./cli.md) for details.
-
-### Scripts (Internal)
-
-| API | Type | Description |
-|-----|------|-------------|
-| `postinstall.mjs` | lifecycle script | `pnpm install` 후 `claude/sd-*` 및 `settings.json`을 소비 프로젝트 `.claude/`에 복사 |
-| `sync.mjs` | lifecycle script | `prepack` 시 루트 `.claude/sd-*` 에셋을 `claude/`로 동기화 |
-| `forEachSdEntry(dir, callback)` | function | 디렉토리에서 `sd-*` 항목을 2단계 깊이로 탐색하며 콜백 호출 |
-| `collectSdEntries(dir)` | function | `forEachSdEntry`로 수집한 `sd-*` 항목의 상대 경로 배열 반환 |
+설치 시 `postinstall` 스크립트가 자동 실행되어, `claude/sd-*` 에셋과 `settings.json`을 프로젝트 루트 `.claude/`에 복사한다.
 
-→ See [docs/scripts.md](./scripts.md) for details.
+## 하려는 작업 → 읽을 파일
 
-### Hooks
+### 계정 관리
 
-| API | Type | Description |
-|-----|------|-------------|
-| `sd-subagent-start.sh` | SubagentStart hook | subagent 시작 시 `CLAUDE.md` 내용을 출력하여 subagent가 프로젝트 지침을 참조하도록 안내 |
-| `sd-check-write.py` | PreToolUse hook (Write) | 기존 파일에 Write 도구 사용 시 차단하고 Edit 도구 사용을 안내 |
-| `sd-check-bash.py` | PreToolUse hook (Bash) | 금지된 명령어 차단 (git stash/checkout/restore/reset/clean, cd, npx tsc, npx eslint) |
-| `sd-check-forbidden-files.py` | PreToolUse hook (Write/Edit) | `tsconfig.json`, `eslint.config.ts` 등 보호 파일 수정 차단 |
-| `sd-cache-read-hash.py` | PostToolUse hook (Read) | Read 후 파일 SHA-256 해시를 세션별 캐시에 저장 |
-| `sd-statusline.py` | statusLine hook | 상태바에 `폴더 | 모델 | 컨텍스트% | 5h사용량 | 7d사용량 | $추가요금` 표시 |
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| Claude Code 계정을 저장하거나 멀티 계정 간 전환하기 | [cli.md](./cli.md) |
 
-→ See [docs/hooks.md](./hooks.md) for details.
+### 설치 및 동기화 동작 이해
 
-### Asset Structure
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| postinstall이 에셋을 어떻게 설치하는지 파악하기 | [scripts.md](./scripts.md) |
+| prepack 동기화(sync.mjs) 동작 파악하기 | [scripts.md](./scripts.md) |
+| `sd-*` 항목 탐색 유틸리티 함수 사용하기 | [scripts.md](./scripts.md) |
 
-| API | Type | Description |
-|-----|------|-------------|
-| `claude/skills/` | asset directory | 19개 sd-* 스킬 디렉토리 (각 스킬은 `SKILL.md` + 선택적 `SKILL.eval.md`와 `references/` 포함) |
-| `claude/rules/` | asset directory | Claude Code 규칙 파일 (`sd-claude-rules.md`, `sd-options.md`) |
-| `claude/references/` | asset directory | 스킬/규칙에서 참조하는 공유 문서 (`sd-frontend-design.md`) |
+### 훅 동작 파악
 
-→ See [docs/assets.md](./assets.md) for details.
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 금지 명령어 차단, 파일 보호, Write 검증 등 훅 동작 파악하기 | [hooks.md](./hooks.md) |
+| 상태바(statusline) 표시 내용 및 캐시 구조 파악하기 | [hooks.md](./hooks.md) |
 
-## Usage Examples
+### 에셋 구조 파악
 
-### 멀티 계정 관리
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 배포 에셋(스킬, 규칙, 참조 문서) 구조와 소스 오브 트루스 파악하기 | [assets.md](./assets.md) |
 
-```bash
-# 현재 계정을 저장
-sd-claude auth save
-
-# 저장된 계정 목록에서 선택하여 전환
-sd-claude auth switch
-```
-
-### 소비 프로젝트에 설치
+---
 
-```bash
-# pnpm install 시 자동으로 .claude/에 에셋 설치됨
-pnpm add -D @simplysm/sd-claude
-
-# 설치 후 .claude/ 디렉토리 구조:
-# .claude/
-#   rules/sd-claude-rules.md
-#   skills/sd-commit/, sd-check/, ...
-#   references/sd-*.md
-#   sd-subagent-start.sh, sd-check-write.py, ...
-#   settings.json  (훅 자동 등록)
-```
+> API 이름으로 검색: [_api-index.md](./_api-index.md)

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

@@ -0,0 +1,39 @@
+# API Index — @simplysm/sd-claude
+
+> API 이름을 알고 있을 때 해당 문서를 찾는 인덱스.
+> 작업 기반으로 찾으려면 [README.md](./README.md) 참조.
+
+## CLI Commands
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `sd-claude auth save` | CLI command | [cli.md](./cli.md) | 현재 계정을 프로필에 저장할 때 |
+| `sd-claude auth switch` | CLI command | [cli.md](./cli.md) | 저장된 계정 간 전환할 때 |
+
+## Scripts
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `postinstall.mjs` | lifecycle script | [scripts.md](./scripts.md) | 에셋 설치 흐름을 파악할 때 |
+| `sync.mjs` | lifecycle script | [scripts.md](./scripts.md) | prepack 동기화 동작을 파악할 때 |
+| `forEachSdEntry()` | function | [scripts.md](./scripts.md) | `sd-*` 항목을 탐색할 때 |
+| `collectSdEntries()` | function | [scripts.md](./scripts.md) | `sd-*` 항목 목록을 배열로 수집할 때 |
+
+## Hooks
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `sd-check-bash.py` | PreToolUse hook | [hooks.md](./hooks.md) | 금지 명령어 차단 동작을 파악할 때 |
+| `sd-check-write.py` | PreToolUse hook | [hooks.md](./hooks.md) | Write 도구의 사전 검증 동작을 파악할 때 |
+| `sd-check-forbidden-files.py` | PreToolUse hook | [hooks.md](./hooks.md) | 보호 파일 수정 차단 동작을 파악할 때 |
+| `sd-cache-read-hash.py` | PostToolUse hook | [hooks.md](./hooks.md) | Read 후 해시 캐싱 동작을 파악할 때 |
+| `sd-subagent-start.sh` | SubagentStart hook | [hooks.md](./hooks.md) | subagent에 CLAUDE.md를 주입하는 동작을 파악할 때 |
+| `sd-statusline.py` | statusLine hook | [hooks.md](./hooks.md) | 상태바 표시 내용과 캐시 구조를 파악할 때 |
+
+## Assets
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `claude/skills/` | asset directory | [assets.md](./assets.md) | 배포되는 스킬 목록과 구조를 파악할 때 |
+| `claude/rules/` | asset directory | [assets.md](./assets.md) | 규칙 파일 내용을 파악할 때 |
+| `claude/references/` | asset directory | [assets.md](./assets.md) | 공유 참조 문서를 파악할 때 |

package/claude/references/sd-simplysm-v14/sd-claude/assets.md

@@ -1,5 +1,7 @@
 # Asset Structure
 
+> **읽어야 하는 상황**: 배포 에셋(스킬, 규칙, 참조 문서)의 구조, 스킬 목록, 소스 오브 트루스 흐름을 파악할 때.
+
 `claude/` 디렉토리는 배포 에셋으로, `postinstall` 시 소비 프로젝트의 `.claude/`에 복사된다. `sd-*` 접두어를 가진 항목만 관리 대상이다.
 
 ## 디렉토리 구조

package/claude/references/sd-simplysm-v14/sd-claude/cli.md

@@ -1,5 +1,7 @@
 # CLI Commands
 
+> **읽어야 하는 상황**: Claude Code 계정을 저장하거나 멀티 계정 간 전환할 때.
+
 `sd-claude`는 `package.json`의 `bin`에 등록된 CLI 도구다. 엔트리포인트는 `scripts/cli.mjs`이다.
 
 ## `sd-claude auth save`
@@ -80,4 +82,4 @@
 - 다른 계정: 마지막 저장/전환 시점의 데이터 사용 (← 저장 시점 표시)
 - 사용량 정보 없음: `[사용량 정보 없음]` 표시
 
-남은 시간 형식: `Xd Yh` (일+시간), `Xh Ym` (시간+분), `Xm` (분), `0m` (만료)
+남은 시간 형식: `XdYh` (일+시간), `XhYm` (시간+분), `Xm` (분), `리셋됨` (만료)