@simplysm/sd-claude 14.0.53 → 14.0.55

package/claude/references/sd-simplysm-v14/service-client/features/event-client.md

@@ -1,6 +1,6 @@
 # `EventClient`
 
-서버 이벤트 구독/발행 관리 인터페이스. 재연결 시 자동 재구독된다. 팩토리 함수 `createEventClient`로 생성한다.
+> **읽어야 하는 상황**: 서버에서 발행하는 실시간 이벤트를 구독하거나 다른 클라이언트에 이벤트를 발행할 때. 일반적으로 `ServiceClient.getEvent()`를 통해 간접 사용하며, 직접 생성은 커스텀 전송 계층 구현 시에만 필요하다.
 
 ## When to use
 

package/claude/references/sd-simplysm-v14/service-client/features/file-client.md

@@ -1,6 +1,6 @@
 # `FileClient`
 
-파일 업로드(POST `/upload`)/다운로드(GET) 인터페이스. 팩토리 함수 `createFileClient`로 생성한다.
+> **읽어야 하는 상황**: 서버에 파일을 업로드하거나 서버에서 파일을 다운로드할 때. 일반적으로 `ServiceClient.uploadFile()`/`downloadFileBuffer()`를 통해 간접 사용하며, 직접 생성은 인증 없이 다운로드만 수행하거나 커스텀 URL 구성이 필요할 때에만 사용한다.
 
 ## When to use
 

package/claude/references/sd-simplysm-v14/service-client/features/orm-client-connector.md

@@ -1,6 +1,6 @@
 # `OrmClientConnector`
 
-`DbContext` 트랜잭션 연결을 원격 서버에서 실행하는 헬퍼 인터페이스. 팩토리 함수 `createOrmClientConnector`로 생성한다.
+> **읽어야 하는 상황**: 클라이언트에서 `DbContext`를 통해 원격 DB 트랜잭션을 실행할 때. 서버 측 직접 DB 접근은 `@simplysm/orm-node` 참조. executor를 수동 제어할 때는 [`OrmClientDbContextExecutor`](./orm-client-db-context-executor.md) 참조.
 
 ## When to use
 

package/claude/references/sd-simplysm-v14/service-client/features/orm-client-db-context-executor.md

@@ -1,6 +1,6 @@
 # `OrmClientDbContextExecutor`
 
-`DbContextExecutor` 인터페이스 구현체. `DbContext`의 쿼리 실행을 서버 `OrmService`에 원격 호출한다.
+> **읽어야 하는 상황**: `DbContext`에 주입할 원격 executor가 필요할 때 (커스텀 연결 로직 구현 시). 일반적으로 [`OrmClientConnector`](./orm-client-connector.md)를 통해 간접 사용한다.
 
 ## When to use
 

package/claude/references/sd-simplysm-v14/service-client/main/service-client.md

@@ -1,6 +1,6 @@
 # `ServiceClient`
 
-WebSocket 기반 서비스 클라이언트의 최상위 파사드 클래스. 내부적으로 `SocketProvider`, `ClientProtocolWrapper`, `ServiceTransport`, `EventClient`, `FileClient`를 조합한다.
+> **읽어야 하는 상황**: 서버에 WebSocket으로 연결하여 RPC 호출, 이벤트 구독, 파일 전송, ORM 원격 실행을 수행할 때. 이벤트 구독만 필요하면 [`EventClient`](../features/event-client.md), ORM 원격 실행만 필요하면 [`OrmClientConnector`](../features/orm-client-connector.md) 참조.
 
 ## When to use
 

package/claude/references/sd-simplysm-v14/service-client/protocol/client-protocol-wrapper.md

@@ -1,6 +1,6 @@
 # `ClientProtocolWrapper`
 
-메시지 인코딩/디코딩 인터페이스. 데이터 크기가 30KB 이상이면 Web Worker로 처리를 오프로드한다. 팩토리 함수 `createClientProtocolWrapper`로 생성한다.
+> **읽어야 하는 상황**: 메시지 인코딩/디코딩을 직접 제어하거나 Worker 오프로드 동작을 커스터마이징할 때. 일반적으로 `ServiceClient`가 내부적으로 생성·관리한다.
 
 ## When to use
 

package/claude/references/sd-simplysm-v14/service-client/transport/service-transport.md

@@ -1,6 +1,6 @@
 # `ServiceTransport`
 
-요청-응답 매핑, progress 중계, 서버 이벤트 디스패치를 담당하는 인터페이스. 팩토리 함수 `createServiceTransport`로 생성한다.
+> **읽어야 하는 상황**: 요청-응답 매핑과 progress 중계를 직접 제어하는 커스텀 계층을 구현할 때. 일반적으로 `ServiceClient`가 내부적으로 생성·관리한다.
 
 ## When to use
 

package/claude/references/sd-simplysm-v14/service-client/transport/socket-provider.md

@@ -1,6 +1,6 @@
 # `SocketProvider`
 
-WebSocket 연결, 재연결, 하트비트를 관리하는 인터페이스. 팩토리 함수 `createSocketProvider`로 생성한다.
+> **읽어야 하는 상황**: WebSocket 연결/재연결/하트비트를 직접 제어하는 커스텀 전송 계층을 구현할 때. 일반적으로 `ServiceClient`가 내부적으로 생성·관리한다.
 
 ## When to use
 

package/claude/references/sd-simplysm-v14/service-client/types/blob-input.md

@@ -1,6 +1,6 @@
-# BlobInput
+# `BlobInput`
 
-Blob constructor가 허용하는 데이터 타입. DOM `BlobPart`를 대체하여 Node.js / 브라우저 양쪽에서 typecheck가 통과하도록 한다.
+> **읽어야 하는 상황**: 파일 업로드 시 데이터 타입(`Blob`, `Uint8Array`, `ArrayBuffer`, `string`)을 지정할 때. `FileClient.upload()`의 `{ name, data }` 객체에서 `data` 필드 타입으로 사용된다.
 
 ```typescript
 export type BlobInput = Blob | Uint8Array<ArrayBuffer> | ArrayBuffer | string;

package/claude/references/sd-simplysm-v14/service-client/types/browser-worker.md

@@ -1,6 +1,6 @@
-# BrowserWorker
+# `BrowserWorker`
 
-Web Worker 최소 인터페이스. DOM lib 없이도 타입체크가 통과하도록 하는 추상 타입이다.
+> **읽어야 하는 상황**: Worker 인터페이스의 cross-env 타입 호환이 필요할 때. `ClientProtocolWrapper`가 내부적으로 사용하며, 직접 사용은 드물다.
 
 ```typescript
 export interface BrowserWorker {

package/claude/references/sd-simplysm-v14/service-client/types/file-collection.md

@@ -1,6 +1,6 @@
-# FileCollection
+# `FileCollection`
 
-File 컬렉션 인터페이스. DOM `FileList`를 대체하며 브라우저 `FileList`와 구조적으로 호환된다.
+> **읽어야 하는 상황**: DOM `FileList` 호환 타입이 필요할 때. `FileClient.upload()` 및 `ServiceClient.uploadFile()`의 `files` 파라미터에서 사용된다.
 
 ```typescript
 export interface FileCollection {

package/claude/references/sd-simplysm-v14/service-client/types/service-connection-options.md

@@ -1,6 +1,6 @@
-# ServiceConnectionOptions
+# `ServiceConnectionOptions`
 
-서비스 서버에 연결할 때 사용하는 옵션 인터페이스.
+> **읽어야 하는 상황**: `ServiceClient` 생성자에 전달할 연결 옵션(호스트, 포트, SSL, 재연결 횟수)을 구성할 때.
 
 ```typescript
 export interface ServiceConnectionOptions {

package/claude/references/sd-simplysm-v14/service-client/types/service-progress.md

@@ -1,6 +1,6 @@
-# ServiceProgress
+# `ServiceProgress`
 
-요청/응답/서버 단계별 progress 콜백을 담는 컨테이너 인터페이스.
+> **읽어야 하는 상황**: 요청/응답/서버 처리 진행률을 모니터링할 때. `ServiceClient.send()`의 `progress` 파라미터로 전달한다.
 
 ```typescript
 export interface ServiceProgress {

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

@@ -18,144 +18,51 @@ import type { ServiceMethods } from "@simplysm/service-server";
 npm install @simplysm/service-common
 ```
 
-## 하려는 작업 → 먼저 읽을 파일
-
-| 작업 | 먼저 읽을 파일 |
-|------|----------------|
-| WebSocket 메시지 인코딩/디코딩 | [create-service-protocol.md](./protocol/create-service-protocol.md) |
-| 프로토콜 상수 확인 (크기 제한, 청킹 등) | [protocol-config.md](./protocol/protocol-config.md) |
-| 타입 안전 이벤트 정의 | [define-event.md](./events/define-event.md) |
-| 메뉴 트리·권한 구조 정의 | [app-structure-item.md](./app-structure/app-structure-item.md) |
-| 모듈 기반 권한 필터링 | [get-flat-permissions.md](./app-structure/get-flat-permissions.md) |
-| ORM 서비스 타입 계약 확인 | [orm-service.md](./service-types/orm-service.md) |
-| 메시지 타입 구조 파악 | [service-message.md](./protocol/service-message.md) |
-
-## API Overview
-
-### Protocol
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`PROTOCOL_CONFIG`](./protocol/protocol-config.md) | const | 프로토콜 크기 제한·청킹 임계값 등 설정 상수를 참조할 때 |
-| [`ServiceMessage`](./protocol/service-message.md) | type | 양방향 메시지의 전체 유니언과 방향별 하위 유니언을 참조할 때 |
-| [`ServiceProgressMessage`](./protocol/service-progress-message.md) | interface | 청크 수신 진행 상태를 처리할 때 |
-| [`ServiceErrorMessage`](./protocol/service-error-message.md) | interface | 서버 에러 응답을 처리할 때 |
-| [`ServiceAuthMessage`](./protocol/service-auth-message.md) | interface | 클라이언트 인증 토큰을 전송할 때 |
-| [`ServiceRequestMessage`](./protocol/service-request-message.md) | interface | 서비스 메서드를 호출할 때 |
-| [`ServiceResponseMessage`](./protocol/service-response-message.md) | interface | 서비스 메서드 응답을 처리할 때 |
-| [`ServiceAddEventListenerMessage`](./protocol/service-add-event-listener-message.md) | interface | 이벤트 리스너를 등록할 때 |
-| [`ServiceRemoveEventListenerMessage`](./protocol/service-remove-event-listener-message.md) | interface | 이벤트 리스너를 제거할 때 |
-| [`ServiceGetEventListenerInfosMessage`](./protocol/service-get-event-listener-infos-message.md) | interface | 등록된 이벤트 리스너 정보를 조회할 때 |
-| [`ServiceEmitEventMessage`](./protocol/service-emit-event-message.md) | interface | 클라이언트에서 이벤트를 발생시킬 때 |
-| [`ServiceEventMessage`](./protocol/service-event-message.md) | interface | 서버에서 수신된 이벤트 알림을 처리할 때 |
-| [`createServiceProtocol`](./protocol/create-service-protocol.md) | function | WebSocket 메시지를 인코딩/디코딩할 때 (자동 청킹·재조립 포함) |
-
-### Service Types
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`OrmService`](./service-types/orm-service.md) | interface | DB 연결·트랜잭션·쿼리 실행의 서버-클라이언트 타입 계약을 정의할 때 |
-| [`AutoUpdateService`](./service-types/auto-update-service.md) | interface | 클라이언트 자동 업데이트 버전 조회 타입 계약을 정의할 때 |
-| [`AppStructureService`](./service-types/app-structure-service.md) | interface | 앱 구조 항목을 서버에서 조회하는 타입 계약을 정의할 때 |
-
-### Types
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`ServiceUploadResult`](./types/service-upload-result.md) | interface | 파일 업로드 결과를 타입으로 사용할 때 |
-
-### App Structure
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`AppStructureItem`](./app-structure/app-structure-item.md) | type | 앱 메뉴 트리·권한 구조를 정의할 때 |
-| [`isUsableModules`](./app-structure/is-usable-modules.md) | function | 단일 항목의 모듈 접근 가능 여부를 판단할 때 |
-| [`isUsableModulesChain`](./app-structure/is-usable-modules-chain.md) | function | 트리 경로 전체의 모듈 접근 가능 여부를 판단할 때 |
-| [`getFlatPermissions`](./app-structure/get-flat-permissions.md) | function | 앱 구조 트리를 플래트닝하여 권한 목록을 얻을 때 |
-
-### Events
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`defineEvent`](./events/define-event.md) | function | 서버-클라이언트 간 타입 안전 이벤트를 정의할 때 |
-
-## Usage Examples
-
-### 프로토콜 인코딩/디코딩
+## 하려는 작업 → 읽을 파일
 
-```typescript
-import { createServiceProtocol } from "@simplysm/service-common";
-
-const protocol = createServiceProtocol();
-
-// 메시지 인코딩 (3MB 초과 시 자동 청킹)
-const { chunks, totalSize } = protocol.encode(uuid, {
-  name: "OrmService.connect",
-  body: [{ configName: "default" }],
-});
-
-// 메시지 디코딩 (청크 자동 재조립)
-for (const chunk of chunks) {
-  const result = protocol.decode(chunk);
-  if (result.type === "complete") {
-    // result.message: 재조립된 메시지
-  }
-}
-
-// 사용 후 반드시 해제
-protocol.dispose();
-```
+### 통신 프로토콜
 
-### 타입 안전 이벤트 정의
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| WebSocket 메시지를 인코딩/디코딩 (자동 청킹·재조립 포함) | [create-service-protocol.md](./protocol/create-service-protocol.md) |
+| 프로토콜 크기 제한·청킹 임계값 등 설정 상수를 참조 | [protocol-config.md](./protocol/protocol-config.md) |
+| 메시지 타입 구조(유니언, 방향별 분류)를 파악 | [service-message.md](./protocol/service-message.md) |
 
-```typescript
-import { defineEvent } from "@simplysm/service-common";
+### 이벤트
 
-// 서버에서 이벤트 정의 + 타입 export
-export const OrderUpdated = defineEvent<{ orderId: number }, { status: string }>("OrderUpdated");
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 서버-클라이언트 간 타입 안전 이벤트를 정의 | [define-event.md](./events/define-event.md) |
 
-// 서버에서 이벤트 발생 (제네릭 타입 파라미터 + 문자열 이름 패턴)
-await server.emitEvent<typeof OrderUpdated>("OrderUpdated", (info) => info.orderId === 123, { status: "shipped" });
+### 앱 구조·권한
 
-// 클라이언트에서 구독 (import type으로 타입만 가져옴)
-import type { OrderUpdated } from "@server-package";
-await client.addListener<typeof OrderUpdated>("OrderUpdated", { orderId: 123 }, async (data) => {
-  // data.status는 string으로 타입 추론됨
-});
-```
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 앱 메뉴 트리·권한 구조를 정의 | [app-structure-item.md](./app-structure/app-structure-item.md) |
+| 앱 구조 트리를 플래트닝하여 권한 목록을 산출 | [get-flat-permissions.md](./app-structure/get-flat-permissions.md) |
+| 단일 항목의 모듈 접근 가능 여부를 판단 | [is-usable-modules.md](./app-structure/is-usable-modules.md) |
+| 트리 경로 전체의 모듈 접근 가능 여부를 판단 | [is-usable-modules-chain.md](./app-structure/is-usable-modules-chain.md) |
 
-### 앱 구조 권한 플래트닝
+### 서비스 타입 계약
 
-```typescript
-import { getFlatPermissions, isUsableModules } from "@simplysm/service-common";
-import type { AppStructureItem } from "@simplysm/service-common";
-
-const items: AppStructureItem<string>[] = [
-  {
-    code: "admin",
-    title: "관리",
-    children: [
-      { code: "user", title: "사용자", perms: ["use", "edit"] },
-    ],
-  },
-  {
-    code: "report",
-    title: "리포트",
-    modules: ["moduleA"],
-    perms: ["use"],
-  },
-];
-
-// 활성 모듈 기준으로 권한 플래트닝
-const perms = getFlatPermissions(items, ["moduleA"]);
-// [{ codeChain: ["admin", "user", "use"], ... }, { codeChain: ["admin", "user", "edit"], ... }, ...]
-
-// 개별 모듈 접근 가능 여부 확인
-const canAccess = isUsableModules(["moduleA", "moduleB"], undefined, ["moduleA"]); // true (OR 조건)
-```
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| DB 연결·트랜잭션·쿼리 실행의 서버-클라이언트 타입 계약을 확인 | [orm-service.md](./service-types/orm-service.md) |
+| 클라이언트 자동 업데이트 버전 조회 타입 계약을 확인 | [auto-update-service.md](./service-types/auto-update-service.md) |
+| 앱 구조 항목을 서버에서 조회하는 타입 계약을 확인 | [app-structure-service.md](./service-types/app-structure-service.md) |
+
+### 공통 타입
+
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 파일 업로드 결과 타입을 사용 | [service-upload-result.md](./types/service-upload-result.md) |
 
 ## 이 패키지를 쓰지 말아야 할 때
 
 - 서버 로직 구현 (서비스 메서드 등록, WebSocket 핸들링) → `@simplysm/service-server`
 - 클라이언트에서 서버 호출 (RPC, 이벤트 구독) → `@simplysm/service-client`
 - v14 소비앱에서 타입만 필요할 때 → 서버 패키지에서 직접 `import type`
+
+---
+
+> API 이름으로 검색: [_api-index.md](./_api-index.md)

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

@@ -0,0 +1,51 @@
+# API Index — @simplysm/service-common
+
+> API 이름을 알고 있을 때 해당 문서를 찾는 인덱스.
+> 작업 기반으로 찾으려면 [README.md](./README.md) 참조.
+
+## Protocol
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `createServiceProtocol` | function | [create-service-protocol.md](./protocol/create-service-protocol.md) | WebSocket 메시지를 인코딩/디코딩할 때 |
+| `PROTOCOL_CONFIG` | const | [protocol-config.md](./protocol/protocol-config.md) | 프로토콜 크기 제한·청킹 임계값 등 설정 상수를 참조할 때 |
+| `ServiceMessage` | type | [service-message.md](./protocol/service-message.md) | 양방향 메시지의 전체 유니언과 방향별 하위 유니언을 참조할 때 |
+| `ServiceProgressMessage` | interface | [service-progress-message.md](./protocol/service-progress-message.md) | 청크 수신 진행 상태를 처리할 때 |
+| `ServiceErrorMessage` | interface | [service-error-message.md](./protocol/service-error-message.md) | 서버 에러 응답을 처리할 때 |
+| `ServiceAuthMessage` | interface | [service-auth-message.md](./protocol/service-auth-message.md) | 클라이언트 인증 토큰을 전송할 때 |
+| `ServiceRequestMessage` | interface | [service-request-message.md](./protocol/service-request-message.md) | 서비스 메서드를 호출할 때 |
+| `ServiceResponseMessage` | interface | [service-response-message.md](./protocol/service-response-message.md) | 서비스 메서드 응답을 처리할 때 |
+| `ServiceAddEventListenerMessage` | interface | [service-add-event-listener-message.md](./protocol/service-add-event-listener-message.md) | 이벤트 리스너를 등록할 때 |
+| `ServiceRemoveEventListenerMessage` | interface | [service-remove-event-listener-message.md](./protocol/service-remove-event-listener-message.md) | 이벤트 리스너를 제거할 때 |
+| `ServiceGetEventListenerInfosMessage` | interface | [service-get-event-listener-infos-message.md](./protocol/service-get-event-listener-infos-message.md) | 등록된 이벤트 리스너 정보를 조회할 때 |
+| `ServiceEmitEventMessage` | interface | [service-emit-event-message.md](./protocol/service-emit-event-message.md) | 클라이언트에서 이벤트를 발생시킬 때 |
+| `ServiceEventMessage` | interface | [service-event-message.md](./protocol/service-event-message.md) | 서버에서 수신된 이벤트 알림을 처리할 때 |
+
+## Events
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `defineEvent` | function | [define-event.md](./events/define-event.md) | 서버-클라이언트 간 타입 안전 이벤트를 정의할 때 |
+
+## App Structure
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `AppStructureItem` | type | [app-structure-item.md](./app-structure/app-structure-item.md) | 앱 메뉴 트리·권한 구조를 정의할 때 |
+| `getFlatPermissions` | function | [get-flat-permissions.md](./app-structure/get-flat-permissions.md) | 앱 구조 트리를 플래트닝하여 권한 목록을 얻을 때 |
+| `isUsableModules` | function | [is-usable-modules.md](./app-structure/is-usable-modules.md) | 단일 항목의 모듈 접근 가능 여부를 판단할 때 |
+| `isUsableModulesChain` | function | [is-usable-modules-chain.md](./app-structure/is-usable-modules-chain.md) | 트리 경로 전체의 모듈 접근 가능 여부를 판단할 때 |
+
+## Service Types
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `OrmService` | interface | [orm-service.md](./service-types/orm-service.md) | DB 연결·트랜잭션·쿼리 실행의 서버-클라이언트 타입 계약을 확인할 때 |
+| `AutoUpdateService` | interface | [auto-update-service.md](./service-types/auto-update-service.md) | 클라이언트 자동 업데이트 버전 조회 타입 계약을 확인할 때 |
+| `AppStructureService` | interface | [app-structure-service.md](./service-types/app-structure-service.md) | 앱 구조 항목을 서버에서 조회하는 타입 계약을 확인할 때 |
+
+## Types
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `ServiceUploadResult` | interface | [service-upload-result.md](./types/service-upload-result.md) | 파일 업로드 결과를 타입으로 사용할 때 |

package/claude/references/sd-simplysm-v14/service-common/app-structure/app-structure-item.md

@@ -1,4 +1,6 @@
-# AppStructureItem
+# `AppStructureItem`
+
+> **읽어야 하는 상황**: 앱 메뉴 트리와 권한 구조를 정의할 때. 권한 플래트닝은 [`getFlatPermissions`](./get-flat-permissions.md), 모듈 접근 판단은 [`isUsableModules`](./is-usable-modules.md) 참조.
 
 앱 구조 항목 유니언 타입. `children` 필드 유무로 그룹(`AppStructureGroupItem`)과 리프(`AppStructureLeafItem`)를 구분한다.
 

package/claude/references/sd-simplysm-v14/service-common/app-structure/get-flat-permissions.md

@@ -1,4 +1,10 @@
-# getFlatPermissions
+# `getFlatPermissions`
+
+> **읽어야 하는 상황**: 앱 구조 트리를 플래트닝하여 사용자별 권한 목록을 산출할 때. 트리 구조 정의는 [`AppStructureItem`](./app-structure-item.md) 참조.
+
+## When to use
+
+- 재귀 메뉴 트리에서 모듈 조건을 필터링하며 모든 권한을 플랫 배열로 추출할 때
 
 앱 구조 트리를 BFS로 순회하며 모듈 조건을 필터링하여 [`FlatPermission`](./app-structure-item.md)`[]`으로 플래트닝한다.
 

package/claude/references/sd-simplysm-v14/service-common/app-structure/is-usable-modules-chain.md

@@ -1,4 +1,6 @@
-# isUsableModulesChain
+# `isUsableModulesChain`
+
+> **읽어야 하는 상황**: 트리 경로의 각 레벨에서 모듈 조건을 모두 만족하는지 판단할 때. 개별 항목 판단은 [`isUsableModules`](./is-usable-modules.md) 참조.
 
 모듈 체인 전체의 접근 가능 여부를 판단한다. 트리의 각 레벨에서 모듈 조건을 모두 만족해야 한다.
 

package/claude/references/sd-simplysm-v14/service-common/app-structure/is-usable-modules.md

@@ -1,4 +1,6 @@
-# isUsableModules
+# `isUsableModules`
+
+> **읽어야 하는 상황**: 단일 앱 구조 항목이 사용자의 모듈 목록으로 접근 가능한지 판단할 때. 트리 경로 전체의 판단은 [`isUsableModulesChain`](./is-usable-modules-chain.md) 참조.
 
 단일 항목의 모듈 접근 가능 여부를 판단한다.
 

package/claude/references/sd-simplysm-v14/service-common/events/define-event.md

@@ -1,4 +1,10 @@
-# defineEvent
+# `defineEvent`
+
+> **읽어야 하는 상황**: 서버-클라이언트 간 타입 안전 이벤트를 정의할 때. 이벤트 구독·발생 API는 `@simplysm/service-server`와 `@simplysm/service-client`에서 제공한다.
+
+## When to use
+
+- 서버에서 이벤트를 정의하고, 클라이언트에서 `import type`으로 타입 안전하게 구독할 때
 
 타입 안전한 서비스 이벤트를 정의하는 팩토리 함수.
 

package/claude/references/sd-simplysm-v14/service-common/protocol/create-service-protocol.md

@@ -1,4 +1,11 @@
-# createServiceProtocol
+# `createServiceProtocol`
+
+> **읽어야 하는 상황**: WebSocket 메시지를 바이너리로 인코딩/디코딩하고, 대용량 메시지의 자동 청킹·재조립이 필요할 때. 프로토콜 설정 상수만 참조하려면 [`PROTOCOL_CONFIG`](./protocol-config.md) 참조.
+
+## When to use
+
+- 서비스 클라이언트·서버 간 WebSocket 통신에서 메시지를 바이너리 프레임으로 변환할 때
+- 3MB 초과 메시지를 300KB 청크로 자동 분할·재조립이 필요할 때
 
 ServiceProtocol 인스턴스를 생성하는 팩토리 함수.
 

package/claude/references/sd-simplysm-v14/service-common/protocol/protocol-config.md

@@ -1,4 +1,6 @@
-# PROTOCOL_CONFIG
+# `PROTOCOL_CONFIG`
+
+> **읽어야 하는 상황**: 프로토콜의 크기 제한, 청킹 임계값, GC 주기 등 설정 상수를 참조할 때. 인코딩/디코딩 API는 [`createServiceProtocol`](./create-service-protocol.md) 참조.
 
 서비스 프로토콜 설정 상수.
 

package/claude/references/sd-simplysm-v14/service-common/protocol/service-add-event-listener-message.md

@@ -1,4 +1,6 @@
-# ServiceAddEventListenerMessage
+# `ServiceAddEventListenerMessage`
+
+> **읽어야 하는 상황**: 이벤트 리스너를 등록하는 메시지 구조를 파악할 때.
 
 클라이언트가 보내는 이벤트 리스너 추가 메시지.
 

package/claude/references/sd-simplysm-v14/service-common/protocol/service-auth-message.md

@@ -1,4 +1,6 @@
-# ServiceAuthMessage
+# `ServiceAuthMessage`
+
+> **읽어야 하는 상황**: 클라이언트 인증 토큰을 전송할 때.
 
 클라이언트가 보내는 인증 메시지.
 

package/claude/references/sd-simplysm-v14/service-common/protocol/service-emit-event-message.md

@@ -1,4 +1,6 @@
-# ServiceEmitEventMessage
+# `ServiceEmitEventMessage`
+
+> **읽어야 하는 상황**: 클라이언트에서 이벤트를 발생시키는 메시지 구조를 파악할 때.
 
 클라이언트가 보내는 이벤트 발생 메시지.
 

package/claude/references/sd-simplysm-v14/service-common/protocol/service-error-message.md

@@ -1,4 +1,6 @@
-# ServiceErrorMessage
+# `ServiceErrorMessage`
+
+> **읽어야 하는 상황**: 서버 에러 응답을 처리할 때.
 
 서버가 보내는 에러 알림 메시지.
 

package/claude/references/sd-simplysm-v14/service-common/protocol/service-event-message.md

@@ -1,4 +1,6 @@
-# ServiceEventMessage
+# `ServiceEventMessage`
+
+> **읽어야 하는 상황**: 서버에서 수신된 이벤트 알림을 처리할 때.
 
 서버가 보내는 이벤트 알림 메시지.
 

package/claude/references/sd-simplysm-v14/service-common/protocol/service-get-event-listener-infos-message.md

@@ -1,4 +1,6 @@
-# ServiceGetEventListenerInfosMessage
+# `ServiceGetEventListenerInfosMessage`
+
+> **읽어야 하는 상황**: 등록된 이벤트 리스너 정보를 조회하는 메시지 구조를 파악할 때.
 
 클라이언트가 보내는 이벤트 리스너 정보 목록 요청 메시지.
 

package/claude/references/sd-simplysm-v14/service-common/protocol/service-message.md

@@ -1,4 +1,6 @@
-# ServiceMessage
+# `ServiceMessage`
+
+> **읽어야 하는 상황**: 양방향 메시지의 전체 유니언 또는 방향별 하위 유니언(`ServiceClientMessage`, `ServiceServerMessage`)의 구조를 파악할 때.
 
 모든 서비스 메시지의 유니언 타입. 클라이언트·서버 양방향 메시지를 모두 포함한다.
 

package/claude/references/sd-simplysm-v14/service-common/protocol/service-progress-message.md

@@ -1,4 +1,6 @@
-# ServiceProgressMessage
+# `ServiceProgressMessage`
+
+> **읽어야 하는 상황**: 청크 수신 진행 상태를 처리할 때.
 
 서버가 보내는 청크 수신 진행 상태 알림 메시지.
 

package/claude/references/sd-simplysm-v14/service-common/protocol/service-remove-event-listener-message.md

@@ -1,4 +1,6 @@
-# ServiceRemoveEventListenerMessage
+# `ServiceRemoveEventListenerMessage`
+
+> **읽어야 하는 상황**: 이벤트 리스너를 제거하는 메시지 구조를 파악할 때.
 
 클라이언트가 보내는 이벤트 리스너 제거 메시지.
 

package/claude/references/sd-simplysm-v14/service-common/protocol/service-request-message.md

@@ -1,4 +1,6 @@
-# ServiceRequestMessage
+# `ServiceRequestMessage`
+
+> **읽어야 하는 상황**: 서비스 메서드를 호출하는 요청 메시지 구조를 파악할 때.
 
 클라이언트가 보내는 서비스 메서드 요청 메시지.
 

package/claude/references/sd-simplysm-v14/service-common/protocol/service-response-message.md

@@ -1,4 +1,6 @@
-# ServiceResponseMessage
+# `ServiceResponseMessage`
+
+> **읽어야 하는 상황**: 서비스 메서드 응답을 처리할 때.
 
 서버가 보내는 서비스 메서드 응답 메시지.
 

package/claude/references/sd-simplysm-v14/service-common/service-types/app-structure-service.md

@@ -1,4 +1,6 @@
-# AppStructureService
+# `AppStructureService`
+
+> **읽어야 하는 상황**: 앱 구조 항목을 서버에서 조회하는 타입 계약을 확인할 때. 앱 구조 타입 정의는 [`AppStructureItem`](../app-structure/app-structure-item.md) 참조.
 
 서버에 등록된 앱 구조 항목을 클라이언트명 기준 맵으로 조회하는 서비스 인터페이스.
 

package/claude/references/sd-simplysm-v14/service-common/service-types/auto-update-service.md

@@ -1,4 +1,6 @@
-# AutoUpdateService
+# `AutoUpdateService`
+
+> **읽어야 하는 상황**: 클라이언트 자동 업데이트 버전 조회의 서버-클라이언트 타입 계약을 확인할 때.
 
 클라이언트 애플리케이션의 최신 버전 정보를 조회하는 서비스 인터페이스.
 

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

@@ -1,4 +1,6 @@
-# OrmService
+# `OrmService`
+
+> **읽어야 하는 상황**: DB 연결·트랜잭션·쿼리 실행의 서버-클라이언트 타입 계약을 확인할 때. 서버 측 구현은 `@simplysm/service-server`, 클라이언트 측 호출은 `@simplysm/service-client` 참조.
 
 데이터베이스 연결, 트랜잭션 관리, 쿼리 실행을 제공하는 서비스 인터페이스. MySQL, MSSQL, PostgreSQL을 지원한다. 이 패키지에는 구현체가 없으며, 서버(`service-server`)와 클라이언트(`service-client`)가 공유하는 타입 계약이다.
 

package/claude/references/sd-simplysm-v14/service-common/types/service-upload-result.md

@@ -1,4 +1,6 @@
-# ServiceUploadResult
+# `ServiceUploadResult`
+
+> **읽어야 하는 상황**: 파일 업로드 결과 타입을 사용할 때.
 
 파일 업로드 결과. 서버에 업로드된 파일의 정보를 포함한다.