@simplysm/sd-claude 14.0.76 → 14.0.78

package/claude/settings.json

@@ -1,4 +1,5 @@
 {
+  "outputStyle": "sd-tone",
   "hooks": {
     "PreToolUse": [
       {

package/claude/skills/sd-commit/SKILL.md

@@ -1,17 +1,40 @@
 ---
 name: sd-commit
 description: 워크스페이스의 모든 변경을 단일 커밋으로 묶는 스킬. Use when 여러 변경 사항을 한 번에 커밋해야 할 때
+model: haiku
 ---
 
 # 총괄 커밋
 
 system prompt 의 "Committing changes with git" 절차를 따르되, 아래만 적용한다.
 
-- 모든 git 호출(`status`/`diff`/`log`/`add`/`commit`)은 prefix `$env:SDGIT='1'; git ...` (PowerShell) 또는 `SDGIT=1 git ...` (Bash) 로 호출. (Pre-tool 훅의 전역 git 조회 차단 우회 마커. add/commit 도 일관성으로 동일 prefix.)
-- Staging은 `git add -A` 사용. 본 스킬 호출 = 사용자가 -A 위험(민감 파일 staging) 인지·동의한 것으로 간주.
-- 메시지는 사용자 응답 언어와 일치.
-- 변경이 여러 갈래면:
-  - 제목: 갈래들을 `및`/`,` 로 한 줄 병합
-  - 본문(빈 줄 후): 갈래별 헤더 `[<type>]: <갈래 요약>` + 변경 항목 불릿(`-`). 갈래 간 빈 줄로 분리.
-  - `<type>`: conventional commits (`fix`/`feat`/`refactor`/`docs`/`chore`/`test`/`build`/`ci`/`style`/`perf`)
-- 푸시는 수행하지 않음.
+## git 호출 prefix
+
+- 대상: 모든 git 호출 (`status`·`diff`·`log`·`add`·`commit`)
+- 목적: Pre-tool 훅의 전역 git 조회 차단 우회 마커. `add`·`commit` 도 일관성으로 동일 prefix.
+- **도구별 prefix** — 사용 도구에 맞는 문법 1개만 선택:
+  - Bash 도구 → `SDGIT=1 git ...`
+  - PowerShell 도구 → `$env:SDGIT='1'; git ...`
+- 금지:
+  - Bash 도구에 `$env:...` 사용 — PowerShell 문법
+  - PowerShell 도구에 `SDGIT=1 git ...` 사용 — bash inline env 문법, PowerShell 파서 에러
+
+## staging
+
+- `git add -A` 사용
+- 본 스킬 호출 = 사용자가 `-A` 위험(민감 파일 staging) 인지·동의
+
+## 커밋 메시지
+
+- 언어: 사용자 응답 언어와 일치
+- 단일 갈래: 제목 1줄
+- 복수 갈래:
+  - 제목: 갈래를 `및`·`,` 로 한 줄 병합
+  - 본문 (빈 줄 후): 갈래별로 아래 블록 반복, 블록 간 빈 줄 분리
+    - 헤더: `[<type>]: <갈래 요약>`
+    - 변경 항목 bullet (`-`)
+  - `<type>`: conventional commits — `fix`·`feat`·`refactor`·`docs`·`chore`·`test`·`build`·`ci`·`style`·`perf`
+
+## 푸시
+
+- 수행 X

package/claude/skills/sd-docs/SKILL.md

@@ -27,27 +27,32 @@ effort: "low"
 
 `public 리스트` 의 패키지 수만큼 `general-purpose` subagent 호출을 **단일 메시지 안에서 병렬**로 보낸다. 각 호출 프롬프트는 [references/subagent-prompt.md](references/subagent-prompt.md) 의 양식을 그대로 사용하고, `<PACKAGE_NAME>` 과 `<PACKAGE_DIR>` 만 치환한다.
 
-각 subagent 의 산출:
+각 subagent 의 산출 (풀 재작성 모드 — 기존 파일 참고 없이 처음부터 작성):
 
-- `apis/<패키지명>/README.md` 신규 작성 또는 코드 변경 반영 갱신.
-- 필요 시 `apis/<패키지명>/<군명>.md` 추가/갱신.
-- 결과 보고 1단락 (산출/갱신 파일 목록, 분할 발생 여부, 한 줄 트리거 요약).
+- `apis/<패키지명>/README.md` 재작성.
+- 필요 시 `apis/<패키지명>/<군명>.md` 재작성. 코드에서 사라진 군의 파일은 삭제.
+- 결과 보고 1단락 (산출 파일 목록, 분할 발생 여부, 한 줄 트리거 요약).
 
-### 3. 상위 README 의 "패키지 인덱스" 섹션 갱신
+**범위 한정**: subagent 는 `apis/<패키지명>/` 자리만 다룬다. 상위 `.claude/references/sd-simplysm14/README.md` 는 건드리지 않는다 (메인 에이전트가 §3 에서 처리).
 
-모든 subagent 완료 후 `.claude/references/sd-simplysm14/README.md` 의 "패키지 인덱스" 섹션을 통째로 재구성한다.
+### 3. 상위 README 의 "패키지 인덱스" 섹션 갱신 (파일 보존 + 섹션 내 항목만 갱신)
 
+`.claude/references/sd-simplysm14/README.md` 는 **풀 재작성 대상 아님**. 파일 본문·다른 섹션은 그대로 보존, "패키지 인덱스" 섹션의 항목 리스트만 재구성한다.
+
+모든 subagent 완료 후:
+
+- **갱신 대상**: "패키지 인덱스" 섹션 본문(항목 리스트)만.
+- **건드리지 않음**: 섹션 머리(`## 패키지 인덱스`), 다른 모든 섹션, 파일 상단/하단 텍스트.
 - **항목 형식**: `- **<패키지명>** — <한 줄 트리거 요약>. 자세히: [apis/<패키지명>/README.md](./apis/<패키지명>/README.md)`
 - **순서**: 패키지명 알파벳순.
 - **포함**: `public 리스트` 만.
 - **제외**: `private 리스트` 의 패키지, 코드베이스에 더 이상 존재하지 않는 패키지.
-- 섹션 머리(`## 패키지 인덱스`)와 다른 섹션은 건드리지 않는다.
 
 ### 4. 사용자 보고
 
 다음 항목을 짧게 정리해 출력한다.
 
-- 신규 작성된 패키지 목록.
-- 갱신된 패키지 목록.
-- 분할 발생(추가 `.md` 가 생긴) 패키지 목록.
+- 재작성된 패키지 목록 (= `public 리스트` 전체. 풀 재작성 모드 — 매번 모든 패키지 산출).
+- 분할 발생(`<군명>.md` 가 생긴) 패키지 목록.
+- 삭제된 분할 파일 (코드에서 사라진 군, 있다면).
 - 인덱스에서 제거된 항목 (있다면).

package/claude/skills/sd-docs/references/subagent-prompt.md

@@ -34,11 +34,13 @@ entry 의 export 심볼들을 "한 작업 컨텍스트에서 함께 참조될
 
 위를 만족하지 않으면 README 안에 머무른다.
 
-### 4. 기존 문서 확인 (신규/갱신 자동 판단)
+### 4. 풀 재작성 모드 (범위: `apis/<패키지명>/` 자리만)
 
-- `apis/<패키지명>/README.md` 가 이미 존재하면: 기존 내용 읽고 코드 현재 상태와 차이만 메운다. 기존 손편집 표현 가능한 한 보존, 단 코드와 모순되면 코드 진실 우선.
-- 존재하지 않으면: 처음부터 작성.
-- 기존 `<군명>.md` 들도 동일 원칙. 코드에서 사라진 군의 파일은 삭제한다.
+- 기존 `apis/<패키지명>/README.md` 와 분할 `<군명>.md` 가 있어도 **참고하지 않고 처음부터 작성**한다. 코드 + 본 프롬프트 형식 룰(§5·§6·§7) 만을 진실 근거로 삼는다.
+- 기존 파일 내용·표현 보존 시도 금지. 룰 변경(예: 식별자 풀이 의무) 이 자동 반영되도록 매 호출마다 패키지별 산출물(README + 분할 `<군명>.md`)을 다시 만든다.
+- 결과적으로 코드가 안 바뀐 패키지도 표현이 달라질 수 있다 — 정상.
+- 코드에서 사라진 군의 분할 파일은 삭제한다.
+- **범위 밖**: 상위 `.claude/references/sd-simplysm14/README.md` 는 절대 건드리지 않는다 (메인 에이전트가 인덱스 섹션 항목만 갱신, subagent 와 무관).
 
 ### 5. README.md 형식
 
@@ -58,7 +60,22 @@ H1 은 `# @simplysm/<short-name>` 형식으로 고정한다 (예: `# @simplysm/f
 
 ## <인라인 군 이름 1>
 
-각 심볼별 짧은 시그니처 + 즉시 사용 가능한 사용법 (3~6줄). 본질적으로 큰 군이라 분할된 경우 이 섹션은 없고, 위 인덱스에서 `자세히:` 링크로 안내한다.
+각 심볼별 짧은 시그니처 + 옵션/prop/필드/enum literal 1줄 풀이 + 즉시 사용 가능한 사용법. 본질적으로 큰 군이라 분할된 경우 이 섹션은 없고, 위 인덱스에서 `자세히:` 링크로 안내한다.
+
+**식별자 풀이 의무**: 시그니처에 나오는 옵션·prop·필드·enum literal 각각에 1줄 풀이를 단다. 풀이 = `<무엇을 함>` + (enum/boolean 이면) `<값별 동작 차이>` + `<언제 쓰는지 단서 1조각>`. 이름만 나열은 금지.
+
+예 (나쁨/좋음):
+
+```
+[나쁨]
+inputs: selectMode, autoSelect: "click"|"focus", useAutoSort, focusMode: "row"|"cell"
+
+[좋음]
+- selectMode: "single"|"multi" — 행 선택 모드. 미지정 시 선택 비활성. 다중 선택 화면이면 "multi".
+- autoSelect: "click"|"focus" — 자동 선택 트리거. "click" = 클릭 시 선택, "focus" = 키보드 포커스 이동만으로도 선택. 키보드 위주 화면이면 "focus".
+- useAutoSort: boolean — 클라이언트 정렬. true 면 sorts 변경 시 items 를 sd-sheet 가 직접 정렬. 서버측 정렬(페이징 포함)이면 false 로 두고 외부에서 items 재조회.
+- focusMode: "row"|"cell" — 키보드 포커스 단위. "row" = 행 전체 이동, "cell" = 셀 단위 이동. 셀 편집·복사 화면이면 "cell".
+```
 
 ## <인라인 군 이름 2>
 ...
@@ -77,7 +94,7 @@ H1 은 `# @simplysm/<short-name>` 형식으로 고정한다 (예: `# @simplysm/f
 
 ## <심볼>
 
-시그니처, 사용 예, 주의사항.
+시그니처, 옵션/prop/필드/enum literal 1줄 풀이(위 §5 "식별자 풀이 의무" 동일 적용), 사용 예, 주의사항.
 
 ## <심볼>
 ...
@@ -86,9 +103,10 @@ H1 은 `# @simplysm/<short-name>` 형식으로 고정한다 (예: `# @simplysm/f
 ### 7. 작성 원칙
 
 - 산출물 소비자는 Claude 에이전트다. 사람 가독성보다 에이전트가 즉시 따를 수 있는 간결·명확성이 우선.
-- 코드에서 드러나지 않는 동작은 적지 않는다.
+- **코드 본문에 드러난 동작은 JSDoc 없어도 적는다**. 옵션·prop·필드·enum literal 의 동작을 본문(분기·기본값·사용처)에서 추론해 풀이. 단, 본문에서 확인 불가한 외부 추측·미검증 동작은 금지.
+- **식별자만 나열 금지** — 위 §5·§6 "식별자 풀이 의무" 강제. 이름 콤마 나열로 끝내지 않는다. 자명해 보여도 enum literal 의 값별 동작, boolean 의 토글 효과, 함수형 prop 의 호출 시점은 반드시 풀이.
 - 사용 예는 실제 호출 코드 형태로 1~3줄, 군마다 1개 정도.
-- 분량을 늘리기 위한 부연·중복·꾸밈 금지.
+- 분량을 늘리기 위한 부연·중복·꾸밈 금지. 단, 식별자 풀이는 "분량 늘리기" 가 아니라 필수 정보로 취급 — 풀이 생략을 통한 분량 절약 금지.
 
 ### 8. 산출 보고
 

package/claude/skills/sd-impl/SKILL.md

@@ -164,7 +164,7 @@ spec.md 단위(§4.x 화면 또는 §5.x 자동 처리) 1개를 현재 코드베
 ## 운용
 
 - 결정 근거: `sd-base-rules.md` "결정 근거" 적용.
-- **사용자 보고 어휘**: 코드 식별자(변수명·SQL 함수명·타입 키워드 등) 노출 금지. 도메인 어휘로 풀어 보고. (`sd-base-rules.md` "산출물 소비자 도메인 어휘" 적용)
+- **사용자 보고 어휘**: 코드 식별자(변수명·SQL 함수명·타입 키워드 등) 노출 금지. 도메인 어휘로 풀어 보고. (output-style `sd-tone` "산출물 소비자 도메인 어휘" 적용)
 - **spec.md 동기화**: sd-impl 이 직접 손대는 spec 변경은 다음 2건뿐. 헤더 OPEN·구조 변경은 2단계 규칙대로 종료 후 sd-spec.
   - 본문 인라인 `[OPEN]` 해소 시 마커를 결정 내용으로 교체 (2단계).
   - 9단계 완료 시 §4.x/§5.x 헤더 `[확정: …]` 를 `[확정: …, 구현: 날짜]` 로 확장.

package/claude/skills/sd-skill/references/skill-authoring.md

@@ -54,7 +54,7 @@ description 은 에이전트의 라우팅 진입점이다. 에이전트가 descr
 
 다음의 경우에 별도 파일로 분리하라:
 
-- SKILL.md 분량이 에이전트가 한 자리에서 워크플로 흐름을 인식하기 어려울 만큼 디테일이 누적된 경우 (가이드값: 100줄. 절대 임계 아님. 흐름이 응집되어 있다면 초과 허용)
+- SKILL.md 분량이 에이전트가 한 자리에서 워크플로 흐름을 인식하기 어려울 만큼 디테일이 누적된 경우
 - 명백히 다른 도메인을 다루는 경우
 - 거의 사용되지 않는 고급 기능
 

package/claude/skills/sd-spec/SKILL.md

@@ -116,10 +116,13 @@ Requirement Source 의 모든 요구를 일괄 분류 → 채팅으로만 제시
 
 **Re-Read**: spec-authoring.md §2 (BPMN·흐름 설명 bullet·관련 섹션 포함) + §3, example-spec.md §2.1 + §3.1.
 
-분할된 단위 순서대로 한 항목씩.
+분할된 단위 순서대로 한 항목씩. 합의 단위는 sd-base-rules "임의안 분량·단위" 가드 적용 — 단번에 yes/no 판단 가능한 최소 단위로.
 
-- **§2.x 업무 프로세스**: BPMN (사용자에겐 ASCII, 확정 후 mermaid 로 문서 저장) + 흐름 설명 bullet + 관련 섹션 (화면·자동 처리) 한꺼번에.
-- **§3.x 기타 요구사항**: 본문 전체 한꺼번에.
+- **§2.x 업무 프로세스**: 위→아래 1건씩.
+  1. BPMN (사용자에겐 ASCII, 확정 후 mermaid 로 문서 저장)
+  2. 흐름 설명 bullet
+  3. 관련 섹션 (화면·자동 처리)
+- **§3.x 기타 요구사항**: 본문 짧으면 전체 1건. 길어지면 요구 의도 → 관련 섹션 분리.
 
 ### 5단계: §4/§5 헤더 분할
 
@@ -139,20 +142,26 @@ Requirement Source 의 모든 요구를 일괄 분류 → 채팅으로만 제시
 - ❌ 나쁜 예: 다른 화면 §4.A 에 "취소 요청" 컬럼·`[취소]` 버튼이 있었다는 이유로 §4.B 에도 그대로 복사 (§4.B 요구사항엔 취소 기능 없음)
 - ✅ 좋은 예: §4.B 의 §2.x/§3.x 본문·관련 섹션·사용자 발언에서 "취소" 언급 없음 확인 → 취소 관련 컬럼·버튼·동작 모두 제외
 
-확정된 구체 단위 순서대로 한 항목씩.
+확정된 구체 단위 순서대로 한 항목씩. 합의 단위는 sd-base-rules "임의안 분량·단위" 가드 적용 — 단번에 yes/no 판단 가능한 최소 단위로. 신규 작성·정정·골격 신설 무관 동일 적용.
 
-- **§4.x 화면** — 합의 단위 크므로 사용자가 단번에 yes/no 판단할 수 있는 가장 작은 단위로 분리해 묻는다. spec-authoring §4.x 표준 구조 절 단위로 위→아래, 각 확정 후 다음:
-  1. 헤더 인덱스(Actor·관련 섹션) + 기능 개요 — 한 묶음
-  2. 와이어프레임 — 1건
-  3. 항목 — 영역(좌/우 등) → 하위 요소(필터·시트 컬럼·입력/상세 폼 등) 단위로 쪼개 묻기. 각 영역의 각 하위 요소별 1건.
-  4. 동작 — 1건
-  5. 도메인 규칙·로직(해당 시)
-  6. 양식 매핑(해당 시)
+- **§4.x 화면** — spec-authoring §4.x 표준 구조 절 단위로 위→아래, 각 확정 후 다음:
+  1. 헤더 인덱스(Actor·관련 섹션) — 1건 (본문 짧으면 기능 개요와 묶기 가능)
+  2. 기능 개요 — 1건
+  3. 와이어프레임 — 1건
+  4. 항목 — 영역(좌/우 등) → 하위 요소(필터·시트 컬럼·입력/상세 폼 등) 단위로 쪼개 묻기. 각 영역의 각 하위 요소별 1건.
+  5. 동작 — 1건
+  6. 도메인 규칙·로직 (해당 시) — 규칙별 1건
+  7. 양식 매핑 (해당 시) — 양식별 1건
 
   화면 패턴은 example-spec 의 §4.1~§4.6 라인 직접 참조 (위 Re-Read 기 명시).
-- **§5.x 자동 처리** (스케줄러/이벤트 백그라운드):
+- **§5.x 자동 처리** (스케줄러/이벤트 백그라운드) — 위→아래 1건씩:
   1. Flowchart (사용자에겐 ASCII, 확정 후 mermaid 로 문서 저장)
-  2. 목적 / 트리거 / 처리 / 예외 처리 / 관련 화면 한꺼번에
+  2. 목적 (본문 짧으면 트리거와 묶기 가능)
+  3. 트리거
+  4. 처리
+  5. 예외 처리
+  6. 양식 매핑 (해당 시) — 양식별 1건
+  7. 관련 섹션
 
 이 단계에서 새 도메인 어휘·시스템 규격은 §6 공통 정의, 새 엔티티는 §7 도메인 모델, 외부 시스템 호출은 §8 외부 인터페이스 에 추가 (운용 "다른 섹션 변경·추가 발생 시" 적용).
 

package/claude/skills/sd-spec/references/spec-authoring.md

@@ -193,7 +193,7 @@ list·detail 동일. 새 버튼은 해당 그룹 끝에 추가.
 
 ### 와이어프레임 (텍스트)
 
-ASCII 그림 공통 규칙은 `sd-base-rules.md` 의 "ASCII 그림" 절 참조.
+ASCII 그림 공통 규칙은 output-style `sd-tone` 의 "ASCII 그림" 절 참조.
 
 **원칙**: 영역 배치·구획만 잡는다. 디테일(필드·시트 컬럼·실제 값·아이콘 placeholder·fixed 경계·비활성 행 등 시각 표현)은 와이어에 X — 항목 표·동작 절·도메인 규칙 절이 단일 출처.
 

package/claude/skills/sd-unpack/SKILL.md

@@ -26,47 +26,171 @@ Windows + MS Office 필요 (docx/pptx/xlsx 변환). Python 패키지 의존은 `
 
 동일 입력 재호출 시 기존 결과 폴더는 사전 삭제 후 재생성 (이전 산출 잔존물 섞이지 않게).
 
-시각은 PNG, 텍스트/구조는 MD/JSON 으로 분리해 출력한다.
+시각은 PNG, 텍스트/구조는 JSONL/JSON/MD 로 분리해 출력한다.
 
 ```
 meeting_eml/
-  README.md            ← 진입점. 본문 요약·헤더·첨부 목록·손실 영역
+  README.md            ← 진입점. 헤더·첨부 목록·손실 영역
   _source.eml          ← 원본
-  body.md              ← 본문 (있으면)
-  body.html
-  headers.json
+  body.md              ← 본문 평문 (HTML→평문 추출 포함)
+  body.html            ← 원본 HTML (있을 때)
+  headers.json         ← 헤더 (envelope 추적 키 포함)
+  images.rels.json     ← CID↔첨부 파일명 매핑 (인라인 이미지 있을 때)
   attachments/
-    report_pptx/             ← 컨테이너 첨부는 재귀 풀이
+    report_pptx/             ← 컨테이너 첨부 재귀 풀이
       README.md
       _source.pptx
       slides/
-        01_표지.png          ← 슬라이드 통째 렌더링
-        01_표지.md           ← 슬라이드 텍스트
-        01_표지.notes.md     ← 노트 (있을 때만)
+        01_<title>.png       ← 슬라이드 통째 렌더링
+        01_<title>.jsonl     ← 한 줄=한 노드 (시각 순서 정렬)
       charts/
-        chart_001.data.json  ← 차트 raw 데이터
-      attachments/
-        embedded_xlsx/
-          README.md
-          _source.xlsx
-          sheets/
-            01_Sheet1.png    ← 시트 통째 렌더링
-            01_Sheet1.md     ← 시트 표
-            01_Sheet1.formulas.json
+        slide15_chart03.data.json
+      images/
+    embedded_xlsx/
+      README.md
+      _source.xlsx
+      workbook.meta.json     ← defined names 등 (있을 때)
+      sheets/
+        01_Sheet1.png
+        01_Sheet1.jsonl
 ```
 
 형식별 산출물 매트릭스:
 
-| 형식 | 시각 (PNG) | 텍스트/구조 | 그 외 |
+| 형식 | 시각 (PNG) | 텍스트/구조 (JSONL) | 그 외 |
 |---|---|---|---|
-| pptx/ppt | `slides/<idx>_<title>.png` (슬라이드별) | `slides/<idx>_<title>.md` + `.notes.md` (있을 때) | `charts/*.data.json`, `attachments/`, `macros/` |
-| docx/doc | `pages/<NNN>.png` (페이지별) | `pages/<NNN>.md` | `images/`, `attachments/`, `macros/` |
-| xlsx/xlsb/xls | `sheets/<idx>_<name>.png` (시트별) | `sheets/<idx>_<name>.md` + `.formulas.json` | `charts/*.data.json`, `images/<sheet>_<cell>`, `attachments/`, `macros/` |
-| pdf | `pages/<NNN>.png` (페이지별) | `pages/<NNN>.md` | `attachments/` (PDF 임베드) |
-| eml/msg | — | `body.md` / `body.html` / `headers.json` | `attachments/` (컨테이너면 재귀) |
+| pptx/ppt | `slides/<idx>_<title>.png` | `slides/<idx>_<title>.jsonl` (슬라이드별 노드) | `charts/*.data.json`, `images/`, `attachments/`, `macros/` |
+| docx/doc | `pages/<NNN>.png` (시각 검증용) | `content.jsonl` (단일 시퀀스), `pages.meta.json` (PNG↔노드 매핑) | `images/`, `attachments/`, `macros/` |
+| xlsx/xlsb/xls | `sheets/<idx>_<name>.png` | `sheets/<idx>_<name>.jsonl` (값·수식·시트 메타 통합), `workbook.meta.json` | `charts/*.data.json`, `images/<sheet>_<cell>`, `attachments/`, `macros/` |
+| pdf | `pages/<NNN>.png` | `pages/<NNN>.jsonl` (블록 bbox + 표 셀 단위) | `images/p<NNN>_b<bid>.<ext>`, `attachments/` (PDF 임베드) |
+| eml/msg | — | `body.md` (평문 본문), `headers.json`, `images.rels.json` | `body.html` (원본), `attachments/` (컨테이너면 재귀) |
+
+`attachments/` 안 컨테이너 첨부는 같은 패턴으로 `<basename>_<ext>/` 폴더로 재귀 풀이.
+
+## JSONL 공통 규약
+
+모든 jsonl 출력은 **한 줄 = 한 노드 (또는 한 행/셀)**. 빈 키 생략. JSON 네이티브 타입 보존. datetime → ISO 8601 문자열.
+
+조회 패턴:
+- 좌표·인덱스 직격 grep (`"r":11`·`"slide":5`·`"node":42`)
+- 키 grep (`"type":"heading"`·`"_f"` 수식 행만)
+- Read offset = 행/노드 인덱스 1:1 (빈 노드도 한 줄 유지)
+
+## xlsx jsonl 규약
+
+시트별 `.jsonl`. 좌표 명시로 위치 셈 오차 차단.
+
+- 첫 줄: `{"_meta":{"dims":[행수,열수], "merges":["A1:C1",...], "frozen":"A4", "hyperlinks":{"D5":"http://..."}, "comments":{"E3":"메모"}, "number_formats":{"H4":"#,##0", "E1":"yyyy-mm-dd"}}}`
+  - 비어있는 메타 키는 생략
+  - `number_formats`: General(기본) 외 셀의 표시 형식 (통화·날짜·% 등)
+- 데이터 줄: `{"r":11, "A":"P001", "I":7800, "J":12.5, "_f":{"I":"=SUM(...)", "J":"=I11*1.5"}}`
+  - `r`: 1-based 행번호 (Excel 동일)
+  - 열문자 키 (`A`·`B`·...·`AA`·...): 셀 값. 빈 셀은 키 생략
+  - `_f`: 같은 행 수식 맵 `{열문자: 수식문자열}`. 수식 없는 행은 키 생략
+- 빈 행도 `{"r":N}` 한 줄 유지 → Read offset = 행번호 (오프바이원 차단)
+- 값 타입: JSON 네이티브 (`int`·`float`·`bool`·`str`), datetime 은 ISO 8601 문자열
+
+워크북 단위 메타 (시트 외) 는 `workbook.meta.json`:
+- `defined_names`: `{"이름":["'Sheet1'!$A$1:$C$10", ...]}` (다중 destination 시 list 다수 항목)
+
+## pptx jsonl 규약
+
+슬라이드별 `slides/<idx>_<title>.jsonl`. 원본 XML 순서 (shape_idx 순) 그대로. 시각 순서는 `pos` 좌표 기반으로 Claude 가 필요시 정렬.
+
+- 첫 줄: `{"_meta":{"slide":N, "title":"슬라이드 제목 또는 빈 문자열", "size":[w,h], "shapes":S}}`
+  - `size`: 슬라이드 폭/높이 (EMU 단위, python-pptx 원본)
+  - `shapes`: 노드 수
+- 노드 줄: `{"slide":N, "type":"<type>", "pos":[x,y,w,h], "shape_idx":S, ...추가 키}`
+  - `slide`: 1-based 슬라이드 번호
+  - `type`: 노드 종류 (아래)
+  - `pos`: [x,y,w,h] EMU 좌표 (914400 EMU = 1 inch)
+  - `shape_idx`: 원본 XML shape index (0-based)
+
+노드 type:
+- `title`: 슬라이드 제목 placeholder. 키 `text`·`para_idx`
+- `para`: 일반 문단. 키 `text`·`para_idx`
+- `bullet`: 글머리 항목 (paragraph.level > 0). 키 `text`·`para_idx`·`level`
+- `table_cell`: 표 셀. 키 `table_idx`·`row`·`col` (1-based)·`text`
+  - 셀 안 multi-paragraph 는 `\n` join
+- `image`: 그림. 키 `ref` (`images/...` 상대경로)
+- `chart`: 차트. 키 `ref` (`charts/...` 상대경로)
+- `shape`: 도형/SmartArt/그룹. 키 `subtype`
+
+paragraph 안 hyperlink 가 있으면 `hyperlinks`: `[{"text":"...", "url":"..."}, ...]` 추가 키 (run 단위).
+
+같은 표·차트의 노드들은 `shape_idx` 가 동일.
+
+## docx jsonl 규약
+
+문서 단일 시퀀스 `content.jsonl`. 페이지 단위 폐기 (Word 렌더 산물). 원본 = python-docx 의 문단/표/이미지 시퀀스.
 
-`attachments/` 안 컨테이너 첨부는 같은 패턴으로 `<basename>_<ext>/` 폴더로 재귀 풀이된다.
+- 첫 줄: `{"_meta":{"paragraphs":P, "tables":T, "images":I}}`
+- 노드 줄: `{"node":N, "type":"<type>", ...추가 키}`
+  - `node`: 0-based 시퀀스 인덱스 (Read offset = node)
+
+노드 type:
+- `heading`: 키 `text`·`level` (1·2·3·...) — docx Heading 스타일 기반만 (휴리스틱 추정 X)
+- `para`: 키 `text` (빈 paragraph 도 노드로 보존, text="")
+- `bullet`: 키 `text`·`level` (0-based ilvl)
+- `table_cell`: 키 `table_idx`·`row`·`col` (1-based)·`text`. 머지 시 `colspan` 추가 (gridSpan>1 일 때만). vMerge='continue' cell 은 skip (origin 만)
+- `image`: 키 `ref` (`images/...` 상대경로)
+
+paragraph 안 hyperlink 가 있으면 `hyperlinks`: `[{"text":"...", "url":"..."}, ...]` 추가 키.
+
+페이지 매핑 별도 `pages.meta.json`:
+- `{"001":{"text":"<페이지 평문>"}, "002":{...}, ...}` (PNG 페이지 ↔ fitz 추출 raw text)
+- PNG 는 fitz 페이지 분할 그대로 (시각 검증용)
+- 노드 인덱스 자동 매핑은 미적용 (fitz·python-docx 텍스트 분할 차이로 오매핑 위험) — Claude 가 페이지 text 와 content.jsonl 노드 text 를 직접 grep 비교
+
+## pdf jsonl 규약
+
+페이지별 `pages/<NNN>.jsonl`. PDF 페이지는 원본 단위.
+
+- 첫 줄: `{"_meta":{"page":N, "size":[w,h], "blocks":B, "tables":T, "table_cells":C}}`
+- 노드 줄:
+  - `text_block`: `{"page":N, "block":B, "type":"text_block", "bbox":[x0,y0,x1,y1], "text":"..."}`
+  - `image_block`: `{"page":N, "block":B, "type":"image_block", "bbox":[...], "ref":"images/p001_b03.png"}`
+  - `table_cell`: `{"page":N, "type":"table_cell", "table_idx":T, "table_bbox":[...], "row":R, "col":C, "text":"..."}`
+- 모든 블록 보존 (표 영역과 겹쳐도 skip 안 함) — find_tables 정확도 100% 가정 시 정보 손실 위험 회피. text_block·image_block·table_cell 노드가 동일 영역에 중복 출력될 수 있음. Claude 가 양쪽 비교 판단
+- bbox 는 PDF 기준 좌표 (left-top, pt 단위, 소수점 2자리)
+
+heading 추출은 미적용 (PDF 는 style 정보 없음). 필요 시 본문 grep 으로 패턴 검출.
+
+## 인라인 이미지 매핑 (eml/msg)
+
+본문 안 `<img cid:...>` 가 첨부의 어느 파일인지 추적.
+
+- `images.rels.json`: `{"<cid>":"attachments/image001.png", ...}` (HTML 본문 안 cid → 첨부 파일명)
+- HTML→평문 변환본 안 원래 `<img>` 위치에 `![image001.png](attachments/image001.png)` placeholder 삽입
+  - text/plain 만 있을 때 → `body.md` 자체가 변환본 → placeholder 포함
+  - text/plain·HTML 둘 다 있을 때 → `body.md` 는 plain (placeholder 없음), `body.from_html.md` 가 변환본 (placeholder 포함)
+- 인라인 이미지 없으면 `images.rels.json` 미생성
+
+## eml/msg 본문 규약
+
+본문 흐름 정확성(text/plain 우선) + 인라인 이미지 위치 단서(HTML→평문 변환본) 둘 다 보존:
+
+- `body.md`: 항상 별도 파일 (인라인 cutoff 폐기)
+  - text/plain 있으면 우선 — 발신자가 의도한 평문, 변환 잡음 없음
+  - 없으면 text/html → 평문 추출
+- `body.from_html.md`: text/plain·HTML 둘 다 있을 때만 별도 생성
+  - HTML→평문 변환 (이미지 위치 placeholder 포함)
+  - body.md 가 plain 이라 잃은 위치 정보를 보완
+- `body.html`: 원본 HTML (있을 때)
+- `headers.json`: 모든 메일 헤더 원본 보존 (envelope + `X-Mailer`·`Authentication-Results` 등 모두). 동일 키 다수면 list 누적
+  - README 헤더 섹션에는 표준 envelope 키만 표기 (전체는 headers.json 직접 조회)
+
+## xlsb 클린업
+
+- legacy → xlsx 변환 시 `_converted.xlsx` 는 임시 폴더에서만 처리 (산출 폴더에 미잔존)
+- VBA 매크로 파일 첫 줄에 시트 객체명↔raw 시트명 매핑 코멘트 추가
+  - 예: `Sheet1.vba` 첫 줄 `' (object: Sheet1, sheet: "BOA")`
 
 ## 산출물 사용
 
-후속 스킬(sd-spec 등)은 결과 폴더의 `README.md` 한 번 Read 로 본문 요약·헤더·첨부 목록·손실 영역을 모두 파악할 수 있다. 컨테이너 첨부는 자체 `README.md` 를 가지므로 재귀적으로 같은 방식으로 들어간다.
+후속 스킬(sd-spec 등)은 결과 폴더의 `README.md` 한 번 Read 로 본문 위치·헤더·첨부 목록·손실 영역을 모두 파악할 수 있다. 컨테이너 첨부는 자체 `README.md` 를 가지므로 재귀적으로 같은 방식으로 들어간다.
+
+각 형식별 jsonl 의 grep 패턴:
+- xlsx: `"r":<행>` · `"_f"` (수식 행) · 열문자 키
+- pptx: `"slide":<N>` · `"type":"<type>"` · `"shape_idx":<S>`
+- docx: `"node":<N>` · `"type":"heading"` · `"table_idx":<T>`

package/claude/skills/sd-unpack/scripts/handlers/_common.py

@@ -170,6 +170,17 @@ def now_iso() -> str:
     return datetime.now().isoformat(timespec="seconds")
 
 
+def format_size(num_bytes: int) -> str:
+    """파일 크기 human-readable. 분석 진입 비용 예측용."""
+    if num_bytes < 1024:
+        return f"{num_bytes} B"
+    if num_bytes < 1024 * 1024:
+        return f"{num_bytes / 1024:.1f} KB"
+    if num_bytes < 1024 * 1024 * 1024:
+        return f"{num_bytes / (1024 * 1024):.1f} MB"
+    return f"{num_bytes / (1024 * 1024 * 1024):.1f} GB"
+
+
 def write_readme(
     out_dir: Path,
     *,
@@ -180,6 +191,7 @@ def write_readme(
     body_inline: Optional[str] = None,
     body_file_link: Optional[str] = None,
     body_html_link: Optional[str] = None,
+    body_from_html_link: Optional[str] = None,
     headers: Optional[dict] = None,
     sections: Optional[dict] = None,
     attachments: Optional[list] = None,
@@ -202,7 +214,7 @@ def write_readme(
             lines.append(f"- {w}")
         lines.append("")
 
-    if body_inline or body_file_link or body_html_link:
+    if body_inline or body_file_link or body_html_link or body_from_html_link:
         lines.append("## 본문")
         lines.append("")
         if body_inline:
@@ -211,8 +223,11 @@ def write_readme(
         elif body_file_link:
             lines.append(f"→ [{body_file_link}]({body_file_link})")
             lines.append("")
+        if body_from_html_link:
+            lines.append(f"→ [{body_from_html_link}]({body_from_html_link}) (HTML→평문, 인라인 이미지 위치 placeholder 포함)")
+            lines.append("")
         if body_html_link:
-            lines.append(f"→ [{body_html_link}]({body_html_link})")
+            lines.append(f"→ [{body_html_link}]({body_html_link}) (원본 HTML)")
             lines.append("")
 
     if headers: