@simplysm/sd-claude 14.0.53 → 14.0.55

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

@@ -1,5 +1,7 @@
 # Hooks
 
+> **읽어야 하는 상황**: 금지 명령어 차단, 파일 보호, Write 검증, 상태바 등 Claude Code 훅의 동작을 파악할 때.
+
 `claude/` 디렉토리의 훅 스크립트 (총 6개). `postinstall`에 의해 `.claude/`에 설치되고, `settings.json`에 자동 등록되어 Claude Code 세션에서 실행된다.
 
 ## `sd-subagent-start.sh`
@@ -20,19 +22,21 @@ fi
 
 ## `sd-check-write.py`
 
-PreToolUse 훅 (matcher: `Write`). 기존 파일에 Write 도구를 사용하려 하면 차단하고 Edit 도구 사용을 안내한다.
+PreToolUse 훅 (matcher: `Write`). 대상 파일이 존재할 때, 이전에 Read로 캐시된 해시와 현재 파일 해시를 비교하여 파일이 Read 없이 Write되거나 Read 이후 내용이 변경된 경우 차단한다. `sd-cache-read-hash.py`와 연동하여 동작한다.
 
 ```python
-# stdin으로 tool_input JSON을 받아 file_path를 검사
-# 파일이 이미 존재하면 stderr에 메시지 출력 후 exit(2)
+# stdin으로 tool_input JSON을 받아 file_path, session_id를 사용
+# .tmp/read_hash/{session_id}/{path_hash}에 저장된 캐시 해시와 현재 파일 해시를 비교
+# 불일치 시 stderr에 메시지 출력 후 exit(2)
 ```
 
-입력: stdin JSON (`tool_input.file_path`)
+입력: stdin JSON (`tool_input.file_path`, `session_id`)
 
 | 조건 | 동작 |
 |------|------|
-| 파일이 이미 존재 | stderr에 안내 메시지 출력, exit code 2 (차단) |
-| 파일이 존재하지 않음 | exit code 0 (허용) |
+| 파일이 존재하지 않음 | exit code 0 (허용 — 신규 파일) |
+| 파일이 존재하고 캐시 해시가 현재 해시와 일치 | exit code 0 (허용) |
+| 파일이 존재하고 캐시 해시가 없거나 불일치 | stderr에 "Read first" 안내 출력, exit code 2 (차단) |
 
 ## `sd-check-bash.py`
 
@@ -118,7 +122,7 @@ statusLine 훅. Claude Code 상태바에 `폴더 | 모델 | 컨텍스트% | 5h
 | Function | Description |
 |----------|-------------|
 | `format_model(model_id)` | 모델 ID를 `Name X.Y` 형식으로 변환 (예: `claude-opus-4-6` → `Opus 4.6`) |
-| `format_remaining(reset_epoch)` | 리셋까지 남은 시간을 `Xd Yh` / `Xh Ym` / `Xm` 형식으로 변환. 만료 시 `0m` 반환 |
+| `format_remaining(reset_epoch)` | 리셋까지 남은 시간을 `XdYh` / `XhYm` / `Xm` 형식으로 변환. 만료 시 `0m` 반환 |
 | `format_rate_limit(rate_limit)` | rate limit을 `X%(남은시간)` 형식으로 변환 |
 | `read_cache()` | 캐시 파일을 읽어 딕셔너리로 반환 |
 | `should_fetch(cache)` | 캐시가 없거나 180초 이상 경과했으면 `True` |

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

@@ -1,5 +1,7 @@
 # Scripts (Internal)
 
+> **읽어야 하는 상황**: postinstall 에셋 설치, prepack 동기화, `sd-*` 항목 탐색 유틸리티의 동작을 파악할 때.
+
 `scripts/` 디렉토리의 Node.js `.mjs` 스크립트. CLI와 라이프사이클 훅으로 사용된다.
 
 ## `postinstall.mjs`

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

@@ -1,6 +1,6 @@
 # @simplysm/sd-cli
 
-Simplysm 모노레포용 빌드/개발/배포 CLI 도구. `sd.config.ts` 설정 타입과 Angular AOT Vite 플러그인(`sdAngularPlugin`)을 export한다.
+> Simplysm 모노레포용 빌드/개발/배포 CLI 도구. `sd.config.ts` 설정 타입, TypeScript AOT 컴파일러(`SdTsCompiler`), Angular AOT Vite 플러그인(`sdAngularPlugin`)을 export한다. Node.js 20+ 환경에서 실행된다.
 
 ## Installation
 
@@ -8,131 +8,60 @@ Simplysm 모노레포용 빌드/개발/배포 CLI 도구. `sd.config.ts` 설정
 npm install @simplysm/sd-cli
 ```
 
-## 하려는 작업 → 먼저 읽을 파일
-
-| 작업 | 먼저 읽을 파일 |
-|------|----------------|
-| `sd.config.ts` 작성 | [SdConfig](./config/sd-config.md), [SdPackageConfig](./config/sd-package-config.md) |
-| 클라이언트 패키지 설정 | [SdClientPackageConfig](./config/sd-client-package-config.md) |
-| 서버 패키지 설정 | [SdServerPackageConfig](./config/sd-server-package-config.md) |
-| 배포 설정 (npm/FTP/SFTP) | [SdPublishConfig](./config/sd-publish-config.md) |
-| Capacitor 앱 설정 | [SdCapacitorConfig](./config/sd-capacitor-config.md) |
-| Electron 앱 설정 | [SdElectronConfig](./config/sd-electron-config.md) |
-| 프로그래매틱 TypeScript 컴파일 | [SdTsCompiler](./ts-compiler/sd-ts-compiler.md) |
-| Vitest Angular 테스트 | [sdAngularPlugin](./angular-vite-plugin/sd-angular-plugin.md) |
-
-## API Overview
-
-### Config
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`SdConfig`](./config/sd-config.md) | interface | `sd.config.ts` 작성 시 최상위 설정 타입이 필요할 때 |
-| [`SdPackageConfig`](./config/sd-package-config.md) | type | 패키지 target에 따라 분기해야 할 때 (`target` 필드 discriminated union) |
-| [`SdBuildPackageConfig`](./config/sd-build-package-config.md) | interface | `node`/`browser`/`neutral` 라이브러리 패키지를 설정할 때 |
-| [`SdClientPackageConfig`](./config/sd-client-package-config.md) | interface | `client` 타겟 프론트엔드 패키지를 설정할 때 |
-| [`SdServerPackageConfig`](./config/sd-server-package-config.md) | interface | `server` 타겟 Fastify 서버 패키지를 설정할 때 |
-| [`SdScriptsPackageConfig`](./config/sd-scripts-package-config.md) | interface | 빌드 없이 watch 훅만 실행하는 스크립트 패키지를 설정할 때 |
-| [`BuildTarget`](./config/build-target.md) | type | 라이브러리 패키지의 빌드 플랫폼을 지정할 때 (`"node"` \| `"browser"` \| `"neutral"`) |
-| [`SdPublishConfig`](./config/sd-publish-config.md) | type | 패키지 배포 방식을 설정할 때 (npm / 로컬 디렉토리 / FTP·SFTP) |
-| [`SdPostPublishScriptConfig`](./config/sd-post-publish-script-config.md) | interface | 배포 후 스크립트를 실행할 때 |
-| [`SdCapacitorConfig`](./config/sd-capacitor-config.md) | interface | 클라이언트 패키지에 Capacitor 모바일 앱 설정을 추가할 때 |
-| [`SdElectronConfig`](./config/sd-electron-config.md) | interface | 클라이언트 패키지에 Electron 데스크톱 앱 설정을 추가할 때 |
-| [`SdPwaConfig`](./config/sd-pwa-config.md) | interface | PWA manifest를 설정할 때 |
-| [`SdBrowserSupportConfig`](./config/sd-browser-support-config.md) | interface | 클라이언트 패키지의 브라우저 호환성(browserslist, PostCSS)을 설정할 때 |
-| [`SdWatchHookConfig`](./config/sd-watch-hook-config.md) | interface | watch 모드에서 파일 변경 시 명령어 훅을 실행할 때 |
-| [`NpmConfig`](./config/npm-config.md) | interface | `package.json` 구조를 타입으로 참조해야 할 때 |
-
-### TypeScript Compiler
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`SdTsCompiler`](./ts-compiler/sd-ts-compiler.md) | class | Angular/TS 패키지를 프로그래매틱하게 AOT 컴파일할 때 |
-
-### Angular Vite Plugin
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`sdAngularPlugin`](./angular-vite-plugin/sd-angular-plugin.md) | function | Vitest에서 Angular 컴포넌트 테스트 시 AOT 컴파일이 필요할 때 |
-
-## Usage Examples
-
-### SdTsCompiler를 사용한 TypeScript 컴파일
-
-```typescript
-import { SdTsCompiler } from "@simplysm/sd-cli";
-
-const compiler = new SdTsCompiler({
-  pkgDir: "/workspace/packages/my-lib",
-  cwd: "/workspace",
-  output: { js: true, dts: true },
-  lint: true,
-  globalScss: true,
-});
-
-// 초기 컴파일
-const result = await compiler.compileAsync();
-
-if (result.errors) {
-  console.error("Compilation errors:", result.errors);
-  process.exit(1);
-}
-
-console.log(`Compiled ${result.affectedFiles?.size ?? "all"} files`);
-```
+## 하려는 작업 → 읽을 파일
 
-### watch 모드에서 증분 컴파일
+### 프로젝트 설정
 
-```typescript
-import { SdTsCompiler } from "@simplysm/sd-cli";
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| `sd.config.ts` 파일을 처음 작성하거나 최상위 설정을 수정할 때 | [sd-config.md](./config/sd-config.md) |
+| 패키지의 빌드 타겟을 결정하거나 타겟별 설정 차이를 확인할 때 | [sd-package-config.md](./config/sd-package-config.md) |
+| `node`/`browser`/`neutral` 라이브러리 패키지를 설정할 때 | [sd-build-package-config.md](./config/sd-build-package-config.md) |
+| 빌드 타겟 플랫폼 값(`"node"` / `"browser"` / `"neutral"`)을 참조할 때 | [build-target.md](./config/build-target.md) |
 
-const compiler = new SdTsCompiler({
-  pkgDir: "/workspace/packages/my-lib",
-  cwd: "/workspace",
-  output: { js: true, dts: true },
-});
+### 프론트엔드 / 서버 / 스크립트 패키지
 
-// 초기 컴파일
-let result = await compiler.compileAsync();
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 프론트엔드 클라이언트 패키지를 설정할 때 | [sd-client-package-config.md](./config/sd-client-package-config.md) |
+| Fastify 서버 패키지를 설정할 때 | [sd-server-package-config.md](./config/sd-server-package-config.md) |
+| 빌드 없이 watch 훅만 실행하는 스크립트 패키지를 설정할 때 | [sd-scripts-package-config.md](./config/sd-scripts-package-config.md) |
 
-// 파일 변경 감지 시 증분 컴파일
-const changedFiles = new Set(["/workspace/packages/my-lib/src/foo.ts"]);
-result = await compiler.compileAsync(changedFiles);
+### 배포
 
-// SCSS 의존성이 변경된 TS 파일 찾기
-const affectedByScss = compiler.findAffectedByScss("/workspace/packages/my-lib/scss/variables.scss");
-```
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| npm/로컬 디렉토리/FTP/SFTP 배포 방식을 설정할 때 | [sd-publish-config.md](./config/sd-publish-config.md) |
+| 배포 완료 후 스크립트를 실행할 때 | [sd-post-publish-script-config.md](./config/sd-post-publish-script-config.md) |
 
-### sd.config.ts 작성
-
-```typescript
-import type { SdConfigFn } from "@simplysm/sd-cli";
-
-const config: SdConfigFn = (params) => ({
-  packages: {
-    "core-common": { target: "neutral" },
-    "core-node": { target: "node" },
-    "my-client": {
-      target: "client",
-      server: "my-server",
-    },
-    "my-server": {
-      target: "server",
-      publish: { type: "npm" },
-    },
-  },
-});
-
-export default config;
-```
+### 네이티브 앱
 
-### Vite에서 Angular AOT 플러그인 사용
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| Capacitor 모바일 앱(Android)을 설정할 때 | [sd-capacitor-config.md](./config/sd-capacitor-config.md) |
+| Electron 데스크톱 앱을 설정할 때 | [sd-electron-config.md](./config/sd-electron-config.md) |
 
-```typescript
-import { defineConfig } from "vite";
-import { sdAngularPlugin } from "@simplysm/sd-cli";
+### 브라우저 호환성 / PWA
 
-export default defineConfig({
-  plugins: [sdAngularPlugin({ pkg: "my-client" })],
-});
-```
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| browserslist/PostCSS/레거시 모듈 지원을 설정할 때 | [sd-browser-support-config.md](./config/sd-browser-support-config.md) |
+| PWA manifest를 설정할 때 | [sd-pwa-config.md](./config/sd-pwa-config.md) |
+
+### watch 훅 / 유틸리티 타입
+
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| watch 모드에서 파일 변경 시 명령어를 실행하는 훅을 설정할 때 | [sd-watch-hook-config.md](./config/sd-watch-hook-config.md) |
+| `package.json` 구조를 타입으로 참조할 때 | [npm-config.md](./config/npm-config.md) |
+
+### 프로그래매틱 컴파일
+
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| Angular/TS 패키지를 프로그래매틱하게 AOT 컴파일할 때 | [sd-ts-compiler.md](./ts-compiler/sd-ts-compiler.md) |
+| Vitest에서 Angular 컴포넌트 테스트 시 AOT 컴파일이 필요할 때 | [sd-angular-plugin.md](./angular-vite-plugin/sd-angular-plugin.md) |
+
+---
+
+> API 이름으로 검색: [_api-index.md](./_api-index.md)

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

@@ -0,0 +1,49 @@
+# API Index — @simplysm/sd-cli
+
+> API 이름을 알고 있을 때 해당 문서를 찾는 인덱스.
+> 작업 기반으로 찾으려면 [README.md](./README.md) 참조.
+
+## Config
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `SdConfig` | interface | [sd-config.md](./config/sd-config.md) | `sd.config.ts` 최상위 설정 타입이 필요할 때 |
+| `SdConfigFn` | type | [sd-config.md](./config/sd-config.md) | `sd.config.ts`의 default export 함수 타입이 필요할 때 |
+| `SdConfigParams` | interface | [sd-config.md](./config/sd-config.md) | `sd.config.ts` 함수 매개변수 타입이 필요할 때 |
+| `SdPackageConfig` | type | [sd-package-config.md](./config/sd-package-config.md) | 패키지 target별 설정 discriminated union이 필요할 때 |
+| `SdBuildPackageConfig` | interface | [sd-build-package-config.md](./config/sd-build-package-config.md) | `node`/`browser`/`neutral` 패키지 설정이 필요할 때 |
+| `BuildTarget` | type | [build-target.md](./config/build-target.md) | 빌드 플랫폼 값을 참조할 때 |
+| `SdClientPackageConfig` | interface | [sd-client-package-config.md](./config/sd-client-package-config.md) | `client` 타겟 설정이 필요할 때 |
+| `SdServerPackageConfig` | interface | [sd-server-package-config.md](./config/sd-server-package-config.md) | `server` 타겟 설정이 필요할 때 |
+| `SdScriptsPackageConfig` | interface | [sd-scripts-package-config.md](./config/sd-scripts-package-config.md) | `scripts` 타겟 설정이 필요할 때 |
+| `SdPublishConfig` | type | [sd-publish-config.md](./config/sd-publish-config.md) | 배포 설정 discriminated union이 필요할 때 |
+| `SdNpmPublishConfig` | interface | [sd-publish-config.md](./config/sd-publish-config.md) | npm 배포 설정이 필요할 때 |
+| `SdLocalDirectoryPublishConfig` | interface | [sd-publish-config.md](./config/sd-publish-config.md) | 로컬 디렉토리 배포 설정이 필요할 때 |
+| `SdStoragePublishConfig` | interface | [sd-publish-config.md](./config/sd-publish-config.md) | FTP/SFTP 배포 설정이 필요할 때 |
+| `SdPostPublishScriptConfig` | interface | [sd-post-publish-script-config.md](./config/sd-post-publish-script-config.md) | 배포 후 스크립트 설정이 필요할 때 |
+| `SdCapacitorConfig` | interface | [sd-capacitor-config.md](./config/sd-capacitor-config.md) | Capacitor 앱 설정이 필요할 때 |
+| `SdCapacitorAndroidConfig` | interface | [sd-capacitor-config.md](./config/sd-capacitor-config.md) | Capacitor Android 설정이 필요할 때 |
+| `SdCapacitorSignConfig` | interface | [sd-capacitor-config.md](./config/sd-capacitor-config.md) | APK/AAB 서명 설정이 필요할 때 |
+| `SdCapacitorPermission` | interface | [sd-capacitor-config.md](./config/sd-capacitor-config.md) | Android 권한 설정이 필요할 때 |
+| `SdCapacitorIntentFilter` | interface | [sd-capacitor-config.md](./config/sd-capacitor-config.md) | Android Intent Filter 설정이 필요할 때 |
+| `SdElectronConfig` | interface | [sd-electron-config.md](./config/sd-electron-config.md) | Electron 앱 설정이 필요할 때 |
+| `SdPwaConfig` | interface | [sd-pwa-config.md](./config/sd-pwa-config.md) | PWA 설정이 필요할 때 |
+| `SdPwaManifestConfig` | interface | [sd-pwa-config.md](./config/sd-pwa-config.md) | PWA manifest 설정이 필요할 때 |
+| `SdBrowserSupportConfig` | interface | [sd-browser-support-config.md](./config/sd-browser-support-config.md) | 브라우저 호환성 설정이 필요할 때 |
+| `SdWatchHookConfig` | interface | [sd-watch-hook-config.md](./config/sd-watch-hook-config.md) | watch 훅 설정이 필요할 때 |
+| `NpmConfig` | interface | [npm-config.md](./config/npm-config.md) | `package.json` 타입이 필요할 때 |
+
+## TypeScript Compiler
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `SdTsCompiler` | class | [sd-ts-compiler.md](./ts-compiler/sd-ts-compiler.md) | Angular/TS 패키지를 프로그래매틱하게 AOT 컴파일할 때 |
+| `ISdTsCompilerOptions` | interface | [sd-ts-compiler.md](./ts-compiler/sd-ts-compiler.md) | `SdTsCompiler` 생성 옵션이 필요할 때 |
+| `ISdTsCompilerResult` | interface | [sd-ts-compiler.md](./ts-compiler/sd-ts-compiler.md) | `compileAsync()` 반환 타입이 필요할 때 |
+
+## Angular Vite Plugin
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `sdAngularPlugin` | function | [sd-angular-plugin.md](./angular-vite-plugin/sd-angular-plugin.md) | Vitest에서 Angular AOT 컴파일이 필요할 때 |
+| `SdAngularPluginOptions` | interface | [sd-angular-plugin.md](./angular-vite-plugin/sd-angular-plugin.md) | `sdAngularPlugin` 옵션 타입이 필요할 때 |

package/claude/references/sd-simplysm-v14/sd-cli/angular-vite-plugin/sd-angular-plugin.md

@@ -1,4 +1,6 @@
-# sdAngularPlugin
+# `sdAngularPlugin`
+
+> **읽어야 하는 상황**: Vitest에서 Angular 컴포넌트/서비스를 포함한 패키지를 테스트할 때 AOT 컴파일이 필요한 경우. 프로덕션 빌드나 Non-Angular 테스트에는 불필요하다.
 
 Angular AOT 컴파일을 수행하는 Vite 플러그인. Vitest 환경에서 Angular 컴포넌트를 포함한 TypeScript 패키지를 컴파일할 때 사용한다.
 

package/claude/references/sd-simplysm-v14/sd-cli/config/build-target.md

@@ -1,4 +1,6 @@
-# BuildTarget
+# `BuildTarget`
+
+> **읽어야 하는 상황**: 라이브러리 패키지의 빌드 플랫폼 값(`"node"` / `"browser"` / `"neutral"`)을 참조하거나 타입을 지정할 때.
 
 esbuild로 빌드되는 라이브러리 패키지의 타겟 플랫폼을 나타내는 타입.
 

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

@@ -1,4 +1,6 @@
-# NpmConfig
+# `NpmConfig`
+
+> **읽어야 하는 상황**: `package.json` 구조를 타입으로 참조해야 할 때 (의존성 탐색, 버전 조회 등).
 
 npm `package.json` 구조를 나타내는 인터페이스. 패키지 의존성 탐색, 버전 조회 등 내부 유틸리티에서 사용한다.
 

package/claude/references/sd-simplysm-v14/sd-cli/config/sd-browser-support-config.md

@@ -1,4 +1,6 @@
-# SdBrowserSupportConfig
+# `SdBrowserSupportConfig`
+
+> **읽어야 하는 상황**: 클라이언트 패키지의 브라우저 호환성(browserslist, PostCSS 플러그인, 레거시 모듈)을 설정할 때.
 
 클라이언트 패키지의 브라우저 지원 설정. [`SdClientPackageConfig`](./sd-client-package-config.md)의 `browserSupport` 필드에 사용한다.
 

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

@@ -1,6 +1,8 @@
-# SdBuildPackageConfig
+# `SdBuildPackageConfig`
 
-`node` / `browser` / `neutral` 타겟 라이브러리 패키지 설정. esbuild + tsc로 빌드된다.
+> **읽어야 하는 상황**: `node`/`browser`/`neutral` 타겟 라이브러리 패키지를 설정할 때. 프론트엔드는 [`SdClientPackageConfig`](./sd-client-package-config.md), 서버는 [`SdServerPackageConfig`](./sd-server-package-config.md) 참조.
+
+esbuild + tsc로 빌드된다.
 
 ```typescript
 export interface SdBuildPackageConfig {

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

@@ -1,4 +1,6 @@
-# SdCapacitorConfig
+# `SdCapacitorConfig`
+
+> **읽어야 하는 상황**: 클라이언트 패키지에 Capacitor 모바일 앱(Android) 설정을 추가할 때. Electron 데스크톱 앱은 [`SdElectronConfig`](./sd-electron-config.md) 참조.
 
 Capacitor 모바일 앱 설정. [`SdClientPackageConfig`](./sd-client-package-config.md)의 `capacitor` 필드에 사용한다.
 

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

@@ -1,6 +1,8 @@
-# SdClientPackageConfig
+# `SdClientPackageConfig`
 
-`client` 타겟 패키지 설정. esbuild 기반으로 빌드되며 개발 시 Vite dev server를 사용한다.
+> **읽어야 하는 상황**: 프론트엔드 클라이언트 패키지를 설정할 때 (서버 연결, Capacitor/Electron, 브라우저 호환성, PWA 등). 라이브러리 패키지는 [`SdBuildPackageConfig`](./sd-build-package-config.md) 참조.
+
+esbuild 기반으로 빌드되며 개발 시 Vite dev server를 사용한다.
 
 ```typescript
 export interface SdClientPackageConfig {

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

@@ -1,6 +1,8 @@
-# SdConfig
+# `SdConfig`
 
-`sd.config.ts` 설정 타입. `sd.config.ts`는 반드시 [`SdConfigFn`](#sdconfigfn) 형식의 함수를 default export해야 한다.
+> **읽어야 하는 상황**: `sd.config.ts` 파일을 처음 작성하거나 최상위 설정 구조(`packages`, `replaceDeps`, `postPublish`)를 수정할 때. 개별 패키지 설정은 [`SdPackageConfig`](./sd-package-config.md) 참조.
+
+`sd.config.ts`는 반드시 [`SdConfigFn`](#sdconfigfn) 형식의 함수를 default export해야 한다.
 
 ## When to use
 

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

@@ -1,4 +1,6 @@
-# SdElectronConfig
+# `SdElectronConfig`
+
+> **읽어야 하는 상황**: 클라이언트 패키지에 Electron 데스크톱 앱 설정을 추가할 때. 모바일 앱은 [`SdCapacitorConfig`](./sd-capacitor-config.md) 참조.
 
 Electron 데스크톱 앱 설정. [`SdClientPackageConfig`](./sd-client-package-config.md)의 `electron` 필드에 사용한다.
 

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

@@ -1,4 +1,6 @@
-# SdPackageConfig
+# `SdPackageConfig`
+
+> **읽어야 하는 상황**: 패키지의 빌드 타겟을 결정하거나 `target` 값에 따른 설정 분기를 확인할 때. 각 타겟별 상세 설정은 아래 링크 참조.
 
 `sd.config.ts`의 패키지별 설정. `target` 필드로 분기하는 discriminated union이다.
 

package/claude/references/sd-simplysm-v14/sd-cli/config/sd-post-publish-script-config.md

@@ -1,4 +1,6 @@
-# SdPostPublishScriptConfig
+# `SdPostPublishScriptConfig`
+
+> **읽어야 하는 상황**: 배포 완료 후 자동으로 실행할 스크립트를 설정할 때.
 
 배포 완료 후 실행할 스크립트 설정. [`SdConfig`](./sd-config.md)의 `postPublish` 배열 항목으로 사용한다.
 

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

@@ -1,4 +1,6 @@
-# SdPublishConfig
+# `SdPublishConfig`
+
+> **읽어야 하는 상황**: 패키지 배포 방식(npm / 로컬 디렉토리 / FTP·FTPS·SFTP)을 설정할 때.
 
 패키지 배포 설정. `type` 필드로 분기하는 discriminated union이다.
 

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

@@ -1,4 +1,6 @@
-# SdPwaConfig
+# `SdPwaConfig`
+
+> **읽어야 하는 상황**: PWA manifest(앱 이름, 아이콘, 디스플레이 모드 등)를 설정할 때.
 
 PWA(Progressive Web App) 설정. [`SdClientPackageConfig`](./sd-client-package-config.md)의 `pwa` 필드에 사용한다.
 

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

@@ -1,6 +1,8 @@
-# SdScriptsPackageConfig
+# `SdScriptsPackageConfig`
 
-`scripts` 타겟 패키지 설정. 빌드 엔진이 없으며, `watch` 훅이 설정된 경우에만 watch/typecheck 대상에 포함된다.
+> **읽어야 하는 상황**: 빌드 없이 watch 훅만 실행하는 스크립트 패키지를 설정할 때. 빌드가 필요한 패키지는 [`SdBuildPackageConfig`](./sd-build-package-config.md) 참조.
+
+빌드 엔진이 없으며, `watch` 훅이 설정된 경우에만 watch/typecheck 대상에 포함된다.
 
 ```typescript
 export interface SdScriptsPackageConfig {

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

@@ -1,6 +1,8 @@
-# SdServerPackageConfig
+# `SdServerPackageConfig`
 
-`server` 타겟 패키지 설정. esbuild로 단일 번들 빌드되며 Fastify 서버로 실행된다.
+> **읽어야 하는 상황**: Fastify 서버 패키지를 설정할 때 (externals, PM2, 패키지 매니저 등). 프론트엔드는 [`SdClientPackageConfig`](./sd-client-package-config.md) 참조.
+
+esbuild로 단일 번들 빌드되며 Fastify 서버로 실행된다.
 
 ```typescript
 export interface SdServerPackageConfig {

package/claude/references/sd-simplysm-v14/sd-cli/config/sd-watch-hook-config.md

@@ -1,4 +1,6 @@
-# SdWatchHookConfig
+# `SdWatchHookConfig`
+
+> **읽어야 하는 상황**: watch 모드에서 특정 파일 변경 시 자동으로 명령어를 실행하는 훅을 설정할 때.
 
 watch 모드에서 파일 변경을 감지하고 명령어를 실행하는 훅 설정. [`SdBuildPackageConfig`](./sd-build-package-config.md) 및 [`SdScriptsPackageConfig`](./sd-scripts-package-config.md)의 `watch` 필드에 사용한다.
 

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

@@ -1,4 +1,6 @@
-# SdTsCompiler
+# `SdTsCompiler`
+
+> **읽어야 하는 상황**: Angular/TS 패키지를 프로그래매틱하게 AOT 컴파일하거나 증분 빌드 파이프라인을 구현할 때. CLI 명령어로 빌드한다면 `pnpm build`/`pnpm watch`를 사용하며 이 API는 불필요하다.
 
 TypeScript AOT 컴파일러. Angular 패키지(`angularCompilerOptions`가 `tsconfig.json`에 있는 경우)와 일반 TypeScript 패키지를 모두 지원한다. 증분 빌드, lint 통합, SCSS 컴파일을 관리한다.
 

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

@@ -14,61 +14,52 @@ Node.js 환경에서 사용 시:
 npm install ws
 ```
 
-## 하려는 작업 → 먼저 읽을 파일
+## 하려는 작업 → 읽을 파일
 
-| 작업 | 먼저 읽을 파일 |
-|------|----------------|
-| 서버 연결 및 RPC 호출 | [ServiceClient](./main/service-client.md) |
-| 실시간 이벤트 구독/발행 | [EventClient](./features/event-client.md) |
-| 파일 업로드/다운로드 | [FileClient](./features/file-client.md) |
-| ORM 원격 트랜잭션 실행 | [OrmClientConnector](./features/orm-client-connector.md) |
-| progress 모니터링 | [ServiceProgress](./types/service-progress.md) |
-| 연결 옵션 설정 | [ServiceConnectionOptions](./types/service-connection-options.md) |
+### 서버 연결·통신
 
-## API Overview
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 서버에 WebSocket으로 연결하고 RPC 호출할 때 | [ServiceClient](./main/service-client.md) |
+| 연결 옵션(호스트, 포트, SSL, 재연결 횟수)을 구성할 때 | [ServiceConnectionOptions](./types/service-connection-options.md) |
+| 요청/응답/서버 처리 진행률을 모니터링할 때 | [ServiceProgress](./types/service-progress.md) |
 
-### Main
+### 실시간 이벤트
 
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`ServiceClient`](./main/service-client.md) | class | 서버에 연결하여 RPC, 이벤트, 파일, ORM 기능을 통합 사용할 때 |
-| [`ServiceProxy<T>`](./main/service-client.md) | type | `getService<T>()`의 반환 타입으로, 서비스 메서드를 Promise로 래핑할 때 |
-| [`createServiceClient()`](./main/service-client.md) | function | `new ServiceClient()` 대신 팩토리 함수로 인스턴스를 생성할 때 |
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 서버 이벤트를 구독하거나 다른 클라이언트에 이벤트를 발행할 때 | [EventClient](./features/event-client.md) |
 
-### Transport
+### 파일 전송
 
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`SocketProvider`](./transport/socket-provider.md) | interface | WebSocket 연결/재연결/하트비트를 직접 제어할 때 (일반적으로 `ServiceClient`가 내부 사용) |
-| [`ServiceTransport`](./transport/service-transport.md) | interface | 요청-응답 매핑과 progress 중계를 직접 제어할 때 (일반적으로 `ServiceClient`가 내부 사용) |
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 서버에 파일을 업로드하거나 다운로드할 때 | [FileClient](./features/file-client.md) |
+| 업로드 데이터 타입(Blob, Uint8Array, string 등)을 지정할 때 | [BlobInput](./types/blob-input.md) |
+| DOM FileList 호환 타입이 필요할 때 | [FileCollection](./types/file-collection.md) |
 
-### Protocol
+### ORM 원격 실행
 
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`ClientProtocolWrapper`](./protocol/client-protocol-wrapper.md) | interface | 메시지 인코딩/디코딩을 직접 제어하거나 Worker 오프로드 동작을 이해할 때 (일반적으로 `ServiceClient`가 내부 사용) |
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 클라이언트에서 DbContext 트랜잭션을 원격 실행할 때 | [OrmClientConnector](./features/orm-client-connector.md) |
+| DbContextExecutor 원격 구현체를 수동 제어할 때 | [OrmClientDbContextExecutor](./features/orm-client-db-context-executor.md) |
 
-### Features
+### 내부 전송 계층 (고급)
 
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`EventClient`](./features/event-client.md) | interface | 서버 이벤트를 구독/발행할 때 (`ServiceClient.getEvent()` 경유 권장) |
-| [`FileClient`](./features/file-client.md) | interface | 파일 업로드/다운로드를 직접 제어할 때 (`ServiceClient.uploadFile()`/`downloadFileBuffer()` 경유 권장) |
-| [`OrmClientConnector`](./features/orm-client-connector.md) | interface | `DbContext` 트랜잭션을 원격 서버에서 실행할 때 |
-| [`OrmClientDbContextExecutor`](./features/orm-client-db-context-executor.md) | class | `DbContextExecutor` 원격 구현체가 필요할 때 (`OrmClientConnector` 경유 권장) |
-
-### Types
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`ServiceConnectionOptions`](./types/service-connection-options.md) | interface | `ServiceClient` 생성자에 전달할 연결 옵션을 구성할 때 |
-| [`ServiceProgress`](./types/service-progress.md) | interface | 요청/응답/서버 처리 progress를 모니터링할 때 |
-| [`BlobInput`](./types/blob-input.md) | type | 파일 업로드 시 데이터 타입을 지정할 때 |
-| [`FileCollection`](./types/file-collection.md) | interface | DOM `FileList` 호환 타입이 필요할 때 |
-| [`BrowserWorker`](./types/browser-worker.md) | interface | Worker 인터페이스의 cross-env 타입 호환이 필요할 때 |
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| WebSocket 연결/재연결/하트비트를 직접 제어할 때 | [SocketProvider](./transport/socket-provider.md) |
+| 요청-응답 매핑과 progress 중계를 직접 제어할 때 | [ServiceTransport](./transport/service-transport.md) |
+| 메시지 인코딩/디코딩 또는 Worker 오프로드를 제어할 때 | [ClientProtocolWrapper](./protocol/client-protocol-wrapper.md) |
+| Worker 인터페이스의 cross-env 타입 호환이 필요할 때 | [BrowserWorker](./types/browser-worker.md) |
 
 ## 이 패키지를 쓰지 말아야 할 때
 
 - 서버 측 로직 구현 → [`@simplysm/service-server`](../service-server/README.md)
 - 서버-클라이언트 공유 프로토콜/타입 정의 → [`@simplysm/service-common`](../service-common/README.md)
 - ORM 스키마 정의나 쿼리빌더 → [`@simplysm/orm-common`](../orm-common/README.md)
+
+---
+
+> API 이름으로 검색: [_api-index.md](./_api-index.md)

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

@@ -0,0 +1,58 @@
+# API Index — @simplysm/service-client
+
+> API 이름을 알고 있을 때 해당 문서를 찾는 인덱스.
+> 작업 기반으로 찾으려면 [README.md](./README.md) 참조.
+
+## Main
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `ServiceClient` | class | [service-client.md](./main/service-client.md) | 서버에 연결하여 RPC, 이벤트, 파일, ORM 기능을 통합 사용할 때 |
+| `ServiceProxy<T>` | type | [service-client.md](./main/service-client.md) | `getService<T>()`의 반환 타입으로, 서비스 메서드를 Promise로 래핑할 때 |
+| `createServiceClient()` | function | [service-client.md](./main/service-client.md) | `new ServiceClient()` 대신 팩토리 함수로 인스턴스를 생성할 때 |
+
+## Transport
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `SocketProvider` | interface | [socket-provider.md](./transport/socket-provider.md) | WebSocket 연결/재연결/하트비트를 직접 제어할 때 |
+| `SocketProviderEvents` | interface | [socket-provider.md](./transport/socket-provider.md) | SocketProvider 이벤트 타입 맵이 필요할 때 |
+| `createSocketProvider()` | function | [socket-provider.md](./transport/socket-provider.md) | SocketProvider 인스턴스를 생성할 때 |
+| `ServiceTransport` | interface | [service-transport.md](./transport/service-transport.md) | 요청-응답 매핑과 progress 중계를 직접 제어할 때 |
+| `ServiceTransportEvents` | interface | [service-transport.md](./transport/service-transport.md) | ServiceTransport 이벤트 타입 맵이 필요할 때 |
+| `createServiceTransport()` | function | [service-transport.md](./transport/service-transport.md) | ServiceTransport 인스턴스를 생성할 때 |
+
+## Protocol
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `ClientProtocolWrapper` | interface | [client-protocol-wrapper.md](./protocol/client-protocol-wrapper.md) | 메시지 인코딩/디코딩을 직접 제어할 때 |
+| `createClientProtocolWrapper()` | function | [client-protocol-wrapper.md](./protocol/client-protocol-wrapper.md) | ClientProtocolWrapper 인스턴스를 생성할 때 |
+
+## Features
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `EventClient` | interface | [event-client.md](./features/event-client.md) | 서버 이벤트를 구독/발행할 때 |
+| `ClientEventProxy<T>` | interface | [event-client.md](./features/event-client.md) | `getEvent()`가 반환하는 이벤트 프록시 타입이 필요할 때 |
+| `createEventClient()` | function | [event-client.md](./features/event-client.md) | EventClient 인스턴스를 생성할 때 |
+| `FileClient` | interface | [file-client.md](./features/file-client.md) | 파일 업로드/다운로드를 직접 제어할 때 |
+| `createFileClient()` | function | [file-client.md](./features/file-client.md) | FileClient 인스턴스를 생성할 때 |
+| `OrmClientConnector` | interface | [orm-client-connector.md](./features/orm-client-connector.md) | DbContext 트랜잭션을 원격 실행할 때 |
+| `OrmConnectOptions<T>` | interface | [orm-client-connector.md](./features/orm-client-connector.md) | ORM 원격 연결 옵션을 구성할 때 |
+| `createOrmClientConnector()` | function | [orm-client-connector.md](./features/orm-client-connector.md) | OrmClientConnector 인스턴스를 생성할 때 |
+| `OrmClientDbContextExecutor` | class | [orm-client-db-context-executor.md](./features/orm-client-db-context-executor.md) | DbContextExecutor 원격 구현체가 필요할 때 |
+
+## Types
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `ServiceConnectionOptions` | interface | [service-connection-options.md](./types/service-connection-options.md) | 서버 연결 옵션을 구성할 때 |
+| `ServiceProgress` | interface | [service-progress.md](./types/service-progress.md) | 요청/응답/서버 progress 콜백을 정의할 때 |
+| `ServiceProgressState` | interface | [service-progress.md](./types/service-progress.md) | progress 콜백 데이터 타입이 필요할 때 |
+| `BlobInput` | type | [blob-input.md](./types/blob-input.md) | 파일 업로드 데이터 타입을 지정할 때 |
+| `FileCollection` | interface | [file-collection.md](./types/file-collection.md) | DOM FileList 호환 타입이 필요할 때 |
+| `BrowserWorker` | interface | [browser-worker.md](./types/browser-worker.md) | Worker cross-env 타입 호환이 필요할 때 |
+| `isBrowserWorkerSupported()` | function | [browser-worker.md](./types/browser-worker.md) | DOM Worker API 지원 여부를 확인할 때 |
+| `isNodeWorkerSupported()` | function | [browser-worker.md](./types/browser-worker.md) | Node.js worker_threads 지원 여부를 확인할 때 |
+| `isWorkerSupported()` | function | [browser-worker.md](./types/browser-worker.md) | Worker 오프로딩 지원 여부를 확인할 때 |