deel-local-cli 1.15.1 → 1.17.1

package/README.ko.md

@@ -20,7 +20,7 @@
 
 [![Node.js CI](https://img.shields.io/github/actions/workflow/status/jysvai/deel-local-cli/test.yml?branch=main&logo=github&logoColor=white&label=Node.js%20CI)](https://github.com/jysvai/deel-local-cli/actions/workflows/test.yml)
 [![CodeQL](https://img.shields.io/github/actions/workflow/status/jysvai/deel-local-cli/codeql.yml?branch=main&logo=github&logoColor=white&label=CodeQL)](https://github.com/jysvai/deel-local-cli/actions/workflows/codeql.yml)
-[![tests](https://img.shields.io/badge/tests-7%2C152%20passing-1a7f37?logo=checkmarx&logoColor=white)](docs/ko/develop.md)
+[![tests](https://img.shields.io/badge/tests-7%2C844%20passing-1a7f37?logo=checkmarx&logoColor=white)](docs/ko/develop.md)
 
 [![dependencies](https://img.shields.io/badge/dependencies-0-1a7f37)](https://www.npmjs.com/package/deel-local-cli?activeTab=dependencies)
 [![ESM](https://img.shields.io/badge/ESM-Node%2020%2B-5FA04E?logo=javascript&logoColor=white)](package.json)
@@ -73,6 +73,7 @@
 - [자동 압축](#자동-압축)
 - [대화 이어하기](#대화-이어하기)
 - [밖에서 도구 붙이기 (MCP)](#밖에서-도구-붙이기-mcp)
+- [사내 규칙을 직접 걸기 (훅)](#사내-규칙을-직접-걸기-훅)
 - [에디터 안에서 쓰기 (ACP)](#에디터-안에서-쓰기-acp)
 - [비밀이 새지 않게](#비밀이-새지-않게)
 - [안전망](#안전망)
@@ -89,12 +90,12 @@
 | [모델 다루기](docs/ko/models.md) | 급과 창 크기 · 국산 모델 이름표 · 켤 때 프로젝트 읽기 |
 | [화면과 조작](docs/ko/interface.md) | 입력칸 · 작업 모드 · 쉬움과 개발자 · 무엇을 묻고 무엇을 그냥 하나 |
 | [도구 자세히](docs/ko/tools.md) | `Outline` · `Verify` · `Task` · `Jobs` · `Append` · `Def`/`Refs` · 편집 매칭 |
-| [한글 문서와 엑셀](docs/ko/documents.md) | hwpx·docx·pptx·**PDF** · 인코딩 · 엑셀 → CSV |
-| [늘려 쓰기](docs/ko/extend.md) | 스킬 · 플러그인 · MCP · ACP |
+| [한글 문서와 엑셀](docs/ko/documents.md) | hwpx·docx·pptx·**PDF** · **hwpx 새로 만들기** · 인코딩 · 엑셀 → CSV |
+| [늘려 쓰기](docs/ko/extend.md) | 스킬 · 플러그인 · MCP · 에이전트 · 훅 · ACP |
 | [속도와 씀씀이](docs/ko/tuning.md) | 단계별 추론 강도 · 프리픽스 캐시 · 컨텍스트 길이 |
 | [안전망과 사내 반입](docs/ko/safety.md) | 되돌리기 · 작업 범위 · 감사기록 · 심사 서류 |
 | [설정](docs/ko/config.md) · [개발](docs/ko/develop.md) | 환경변수 · 실행 옵션 · 검사 돌리기 · 폴더 구조 |
-| [릴리스 노트](docs/ko/releases.md) | [1.15.x](docs/ko/releases/1.15.md) · [1.14.x](docs/ko/releases/1.14.md) · [1.13.x](docs/ko/releases/1.13.md) · [1.12.x](docs/ko/releases/1.12.md) · [1.10.x](docs/ko/releases/1.10.md) · [1.9.x](docs/ko/releases/1.9.md) · [그 앞](docs/ko/releases.md) |
+| [릴리스 노트](docs/ko/releases.md) | [1.16.x](docs/ko/releases/1.16.md) · [1.15.x](docs/ko/releases/1.15.md) · [1.14.x](docs/ko/releases/1.14.md) · [1.13.x](docs/ko/releases/1.13.md) · [1.12.x](docs/ko/releases/1.12.md) · [1.10.x](docs/ko/releases/1.10.md) · [1.9.x](docs/ko/releases/1.9.md) · [그 앞](docs/ko/releases.md) |
 
 ---
 
@@ -267,7 +268,7 @@ deel --offline
 무엇이 어디로 갈 수 있는지는 켤 때 화면 맨 위에 늘 적혀 있습니다.
 
 ```
- deel 1.15.1  ⌂ 이 안
+ deel 1.17.1  ⌂ 이 안
  보냄    이 컴퓨터 안 127.0.0.1:11434  ← 여기 말고는 어디로도 안 갑니다
 ```
 
@@ -482,7 +483,7 @@ LM Studio 는 `/api/v0/models`, llama.cpp 는 `/props`. 못 알아보면 `(추
 | `/mode <모드>` | 승인 정책 — 얼마나 물어보나 (`auto` · `confirm` · `strict`) |
 | `/work [모드]` | 작업 모드 — 무슨 일을 하는 중인가 |
 | `/auto` | 다시 맡기기 — 말을 보고 알맞은 모드로 저절로 옮겨 갑니다 |
-| `/code` `/plan` `/architect` `/debug` `/ask` `/orchestrator` | 작업 모드 바로 바꾸기 (그때부터 고정) |
+| `/code` `/plan` `/architect` `/debug` `/inspect` `/ask` `/orchestrator` | 작업 모드 바로 바꾸기 (그때부터 고정) |
 | `/level [수준]` | 화면에 무엇을 내놓을지 (`쉬움` · `개발자`) |
 | `/motion [기본\|기사\|동물\|사무실\|끔]` | 일하는 동안 뭐가 도나 — 그 자리에서 바뀌고 설정에 남습니다 |
 | `/undo [턴수]` | 파일 변경 되돌리기 |
@@ -498,6 +499,8 @@ LM Studio 는 `/api/v0/models`, llama.cpp 는 `/props`. 못 알아보면 `(추
 | `/recall <말>` | 지난 대화에서 **내용으로** 찾기 |
 | `/memory` | 대화가 끝나도 남는 기억 — 보기·적기·지우기 |
 | `/mcp` | 밖에서 붙인 도구(MCP) 서버 보기 |
+| `/hooks` | 적어 둔 훅 보기 (어디서 읽었고 언제 도는지) |
+| `/agents` | 이름 붙인 하위 작업 보기 |
 | `/init` | `DEEL.md` 규칙 파일 만들기 |
 | `/exit` | 끝내기 |
 
@@ -525,6 +528,11 @@ LM Studio 는 `/api/v0/models`, llama.cpp 는 `/props`. 못 알아보면 `(추
 
 ## 작업 모드
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jysvai/deel-local-cli/main/docs/assets/shot-work-ko-dark.svg">
+  <img alt="deel 작업 모드 목록 — 모드마다 파일을 바꿀 수 있는지, 생각 강도, 최대 걸음 수" src="https://raw.githubusercontent.com/jysvai/deel-local-cli/main/docs/assets/shot-work-ko-light.svg" width="900">
+</picture>
+
 무슨 일을 하는 중인지에 따라 **줄 수 있는 도구와 추론 설정이 같이 바뀝니다.**
 `Shift+Tab` 으로 차례로 돌리거나, 이름을 그대로 치면 됩니다.
 
@@ -534,9 +542,13 @@ LM Studio 는 `/api/v0/models`, llama.cpp 는 `/props`. 못 알아보면 `(추
 | `/code` ◆ 코드 | 고치고 만든다 | 예 | 보통 (`save`) |
 | `/plan` ☰ 계획 | 먼저 계획만 세운다 | **아니오** | 깊게 (`deep`·high) |
 | `/architect` ◈ 설계 | 구조를 짠다 | **아니오** | 깊게 (`deep`·high) |
-| `/debug` ◉ 디버그 | 원인을 찾는다 | 예 | 깊게 · 단계 많이 (32) |
-| `/ask` ◇ 묻기 | 설명만 한다 | **아니오** | 얕게 (`low`) |
-| `/orchestrator` ❋ 총괄 | 큰 일을 쪼개서 | 예 | 단계 아주 많이 (40) |
+| `/debug` ◉ 디버그 | 원인을 찾는다 | 예 | 깊게 · 걸음 많이 |
+| `/inspect` ◍ 점검 | 결함을 찾는다 — 근거를 대고, 안 고친다 | **아니오** | 깊게 (`deep`·high) · 걸음 많이 |
+| `/ask` ◇ 묻기 | 설명만 한다 | **아니오** | 얕게 (`low`) — 다만 시킨 것이 여럿이면 안 낮춥니다 |
+| `/orchestrator` ❋ 총괄 | 큰 일을 쪼개서 | 예 | 걸음 아주 많이 |
+
+걸음 수는 **모델 창 크기를 따라갑니다** — 128k 짜리에서 디버그는 250걸음, 묻기는 12걸음입니다.
+작은 모델에 400걸음을 주면 창이 넘쳐 앞엣말을 잊은 채로 도는 것뿐입니다.
 
 읽기만 하는 모드에서는 `Write`·`Edit`·`Bash` 를 **모델에게 아예 보내지 않습니다.**
 "고치지 마세요" 라고 부탁하지 않습니다 — 모델은 부탁을 잊습니다. 없는 도구는 못 씁니다.
@@ -544,7 +556,7 @@ LM Studio 는 `/api/v0/models`, llama.cpp 는 `/props`. 못 알아보면 `(추
 `/mode` 와 헷갈리지 마세요. 둘은 다른 축입니다.
 
 - `/mode` — **얼마나 물어보나** (auto · confirm · strict)
-- `/work` — **무슨 일을 하는 중인가** (위 일곱 가지)
+- `/work` — **무슨 일을 하는 중인가** (위 여덟 가지)
 
 `/think` 나 `/mode` 를 직접 고른 적이 있으면 그 선택이 우선합니다.
 모드가 사람이 고른 값을 덮어쓰지 않습니다.
@@ -587,7 +599,7 @@ LM Studio 는 `/api/v0/models`, llama.cpp 는 `/props`. 못 알아보면 `(추
 | 도구 | 하는 일 |
 |---|---|
 | `Read` | 파일 읽기 (줄 번호 · `offset`/`limit` 지원 · **엑셀은 CSV 로, hwpx·docx·pptx·PDF 는 글로 바꿔서**) |
-| `Write` | 파일 쓰기·덮어쓰기 (**여러 개는 `files` 배열로 한 번에**) |
+| `Write` | 파일 쓰기·덮어쓰기 (**여러 개는 `files` 배열로 한 번에** · **없는 `.hwpx` 는 한글 문서로 새로 만듦**) |
 | `Append` | 파일 끝에 이어 붙이기 — **큰 파일을 나눠 쓰는 자리** |
 | `Edit` | 정확한 문자열 바꾸기 (`replace_all` · **여러 군데는 `edits` 배열로 한 번에**) |
 | `Move` | 파일·폴더 옮기기·이름 바꾸기 — **구조를 바꾸는 자리** (`moves` 배열로 한 번에 · 되돌리기에 잡힘) |
@@ -623,18 +635,53 @@ Claude Code 에 없는 것은 아홉입니다 — `Append` · `Move` · `Ask` ·
 
 **CP949 로 저장된 파일은 CP949 로 되돌려 씁니다.** 인코딩을 바꾸지 않습니다.
 엑셀(`.xlsx`)은 CSV 로, 한글·워드·파워포인트(`.hwpx`/`.docx`/`.pptx`)와
-**PDF** 는 글로 바꿔서 읽습니다 — 전부 읽기 전용입니다.
+**PDF** 는 글로 바꿔서 읽습니다 — 고치기는 안 됩니다.
+
+**다만 없던 한글 문서를 새로 만드는 것은 됩니다.** `Write` 로 아직 없는
+`.hwpx` 를 쓰면 규격(OWPML)대로 진짜 hwpx 를 만듭니다 — `#` 은 제목으로, `-` 는
+글머리표로 들어갑니다. 「보고서 써 줘」 가 `.md` 하나로 끝나고 사람이 그걸
+한글에 다시 붙여넣던 자리입니다. 표는 글줄로 펴고, **한글이 이 파일을 여는지는
+여기서 확인하지 못했다**고 문서에 그대로 적어 뒀습니다.
 
 PDF 는 **못 읽은 쪽을 못 읽었다고 말합니다.** 스캔본·암호·글꼴 표가 없는 쪽은
 빈 글로 넘기지 않고 그 자리에 까닭을 적습니다 — 빈 글은 「그런 내용이 없다」로
 읽히기 때문입니다.
 
+문서를 **마크다운 한 장으로** 뽑아 두려면 `deel doc2md` 입니다. 표가
+`| 이름 | 값 |` 꼴로 살아 있는 채로 나오기 때문에, 평평한 글보다 모델이 훨씬
+덜 헷갈립니다.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jysvai/deel-local-cli/main/docs/assets/shot-doc2md-dark.svg">
+  <img alt="deel doc2md 로 docx 를 마크다운으로 — 표가 마크다운 표로 그대로 남는다" src="https://raw.githubusercontent.com/jysvai/deel-local-cli/main/docs/assets/shot-doc2md-light.svg" width="820">
+</picture>
+
+```bash
+deel doc2md 보고서.pptx              # 표준출력으로
+deel doc2md 스펙.pdf --out 스펙.md   # 파일로
+```
+
+**Figma 시안(`.fig`)도 읽습니다.** 「이 시안대로 만들어 줘」 하고 건네받은
+파일이 「이진 파일이라 못 읽습니다」 로 끝나던 자리입니다. 안에는 그림만이
+아니라 **틀 이름 · 글 · 크기 · 겹친 차례**가 다 글자로 들어 있습니다.
+
+```
+- FRAME · 로그인 화면 375×812
+  - TEXT · 제목 "다시 오신 것을 환영합니다"
+  - FRAME · 입력칸 335×48
+    - TEXT · 라벨 "이메일"
+```
+
+색·그림자·글꼴은 안 냅니다 — 그리고 **안 낸다고 먼저 말합니다.** 요즘 `.fig`
+는 zstd 로 눌려 있어 Node 22.15 이상이 필요하고, 낮은 판에서는 「깨진 파일」 이
+아니라 **여기서 못 푼다**고 말합니다.
+
 옛 형식(`.ppt`·`.doc`·`.xls`·`.rtf`)은 **이 PC 에 깔린 LibreOffice 를 빌려서**
 읽습니다 — `rg` 를 빌려 쓰는 것과 같은 원칙으로, 아무것도 설치하지 않습니다.
 없으면 **없다고 못 박고 끝냅니다**(무엇이 없어서 못 하는지, 무엇을 하면 되는지,
 그리고 「다시 열지 말라」까지). 끄려면 `DEEL_CONVERT=off`.
 
-> **자세히** — 인코딩 · 엑셀 · hwpx/docx/pptx · PDF · 변환기 빌려 쓰기
+> **자세히** — 인코딩 · 엑셀 · hwpx/docx/pptx · **hwpx 새로 만들기** · PDF · `doc2md` · 변환기 빌려 쓰기
 >
 > **[한글 문서와 엑셀 읽기 →](docs/ko/documents.md#한글-문서와-엑셀)**
 
@@ -883,6 +930,37 @@ JSON-RPC 2.0 을 주고받는 것이 전부라, `child_process` 와 `JSON` 이
 
 ---
 
+## 사내 규칙을 직접 걸기 (훅)
+
+사내마다 지켜야 하는 것이 다릅니다. 어떤 팀은 `git push` 를 절대 못 하게 해야 하고,
+어떤 팀은 파일을 고칠 때마다 사내 포맷터를 돌려야 합니다. 그걸 전부 프로그램 안에
+넣으면 팀마다 포크를 뜨게 되고, 포크를 뜨면 우리가 고치는 것이 그 팀에 안 갑니다.
+그래서 **자리만 내줍니다.**
+
+`.deel/hooks.json` 에 적습니다. Claude Code 의 `hooks` 모양도 그대로 받습니다:
+
+```json
+{ "hooks": [ { "때": "도구전", "도구": "Bash", "명령": "python .deel/gate.py" } ] }
+```
+
+넘길 것은 전부 **stdin 으로 JSON 한 줄**이고, 답은 **종료 코드**입니다 — `0` 통과,
+`2` 막음. 걸 수 있는 자리는 `도구전`(막을 수 있음) · `말전`(막을 수 있음) ·
+`도구후` · `턴끝` 넷입니다. `/hooks` 로 무엇이 걸렸는지 봅니다.
+
+**고장 나면 막습니다.** 흔한 규격은 「2번만 막고 나머지 실패는 지나간다」 인데, 그러면
+훅 파일의 오타 하나가 그 문을 조용히 열어 둡니다 — 화면에는 「훅 3개」 라고 뜬 채로.
+문지기가 쓰러져 있으면 문은 잠긴 것이 아닙니다.
+
+**프로젝트 파일은 믿는 폴더에서만 읽습니다.** 없으면 `git clone` 한 번이 곧 남의 명령이
+내 PC 에서 도는 것이 됩니다. `deel --no-hooks` 로 이번 판만, `DEEL_HOOKS=off` 로 아예
+끕니다.
+
+> **자세히** — 이것도 남의 프로그램입니다 · 고장 나면 막습니다
+>
+> **[늘려 쓰기 읽기 →](docs/ko/extend.md#사내-규칙을-직접-걸기-훅)**
+
+---
+
 ## 에디터 안에서 쓰기 (ACP)
 
 터미널을 하나 더 띄우게 하는 도구는 두 주쯤 뒤에 안 씁니다. 개발자는 하루 종일
@@ -898,6 +976,23 @@ deel acp
 에디터가 이걸 자식 프로세스로 띄우고, 표준입출력으로 줄 단위 JSON-RPC 2.0 을
 주고받습니다. 사람이 직접 칠 명령은 아닙니다.
 
+**Zed 라면 이렇게 적습니다.** 에이전트 패널의 `Settings → External Agents →
+Add Custom Agent` 를 눌러도 되고, `settings.json` 에 바로 적어도 됩니다.
+
+```json
+{
+  "agent_servers": {
+    "deel": { "type": "custom", "command": "npx", "args": ["-y", "deel-local-cli", "acp"], "env": {} }
+  }
+}
+```
+
+그리고 에이전트 패널에서 **deel** 을 고릅니다. 아직 `deel setup` 을 안 했다면
+deel 이 「연결이 없다」 고 에디터에게 **규격대로**(ACP 의 `AuthRequired`) 말하고,
+같이 보내 둔 ``Run `deel setup` in a terminal`` 이 뜹니다 — 빨간 글씨만 보고
+버그인지 설정 문제인지 헤매지 않게 하려는 것입니다. 터미널에서 한 번 마치면
+그 다음부터는 바로 대화가 열립니다.
+
 **붙으면 이렇게 됩니다.**
 
 | 에디터 쪽 | deel 쪽 |
@@ -906,7 +1001,7 @@ deel acp
 | 도구 목록 (아이콘·상태) | `Read` 는 읽기, `Edit` 는 고치기, `Bash` 는 실행 — **갈래를 붙여** 보냅니다 |
 | 파일 링크 | 고친 파일의 **절대 경로**. 눌러서 그 자리로 갑니다 |
 | 승인 창 | deel 의 안전망이 그대로 에디터 창으로 뜹니다 (`이번만` · `앞으로 묻지 않기` · `안 함`) |
-| 모드 고르개 | deel 의 작업 모드 7개 (`종합` · `코드` · `계획` · `설계` · `디버그` · `묻기` · `총괄`) |
+| 모드 고르개 | deel 의 작업 모드 8개 (`종합` · `코드` · `계획` · `설계` · `디버그` · `점검` · `묻기` · `총괄`) |
 | 멈춤 단추 | 도중에 닿습니다 — 답을 기다리는 중에도 |
 | 지난 대화 | 껐다 켜도 그대로 열립니다. 터미널과 **같은 자리**에 남아서, 에디터에서 하던 것을 `deel --resume` 으로 이어받는 것도 됩니다 |
 
@@ -1033,7 +1128,7 @@ zip 안에는 **사람이 읽을 것 한 장, 기계가 읽을 것 두 장**이
 | 파일 | 무엇 |
 |---|---|
 | `반입심사서.txt` | 의존성 · 설치 스크립트 · **소스를 훑어 찾은 네트워크·외부 명령 호출 자리 전부**(파일:줄) · 나가는 길 세 갈래 · 파일별 SHA-256 |
-| `sbom.cdx.json` | **SBOM (CycloneDX 1.5).** 스캐너에 그대로 넣습니다. 파일마다 부품 하나에 SHA-256, 의존성은 **빈 배열로 명시** — 안 적어 낸 것과 없는 것은 다릅니다 |
+| `sbom.cdx.json` | **SBOM (CycloneDX 1.7).** 스캐너에 그대로 넣습니다. 파일마다 부품 하나에 SHA-256 과 라이선스, 의존성은 **빈 배열로 명시** — 안 적어 낸 것과 없는 것은 다릅니다. CISA 2026 최소 요소(해시 알고리즘 · 부품 라이선스 · 만든 도구 · 만든 맥락) 네 칸이 다 차 있습니다 |
 | `심사명세.json` | 통신 목록(갈래마다 언제·어디로·무엇이·막는법·소스 자리) · **감사기록 사양**(칸 이름과 뜻, 안 남기는 것) · 파일 해시 |
 
 ```bash
@@ -1041,6 +1136,7 @@ deel audit                    # 사람이 읽는 심사서만 보기
 deel sbom                     # 기계가 읽는 두 장을 표준출력으로 (deel sbom | jq)
 deel sbom --out 심사.json     # 파일로
 deel sbom --only sbom         # SBOM 한 장만
+deel stats                    # 이 폴더에서 실제로 무엇을 했나 (.deel/audit.jsonl 요약)
 ```
 
 셋 다 손으로 적지 않고 코드가 소스를 훑어서 만듭니다 — 손으로 적으면 언젠가
@@ -1073,11 +1169,13 @@ deel sbom --only sbom         # SBOM 한 장만
 | `인증서 문제` | `set NODE_EXTRA_CA_CERTS=C:\경로\사내CA.pem` |
 | 프록시를 거쳐야 함 | `set HTTPS_PROXY=http://프록시:포트` (인증은 `http://user:pw@프록시:포트`). 첫 화면과 `/status` 에 `프록시 …` 가 뜨면 거치는 것. 안 거칠 곳은 `NO_PROXY=.corp.com,10.1.2.3`, 아예 끄려면 설정에 `"proxy": "none"` |
 | 프록시가 407 을 줌 | 프록시 주소에 `user:pw@` 를 넣으세요. NTLM · Negotiate 만 받는 프록시는 못 씁니다 — 담당자에게 Basic 이나 인증 없는 주소를 문의 |
+| 게이트웨이가 **내 인증서**를 요구함 (mTLS) | 프로필에 `"인증서": { "cert": "...", "key": "..." }` — `.pfx` 한 덩이도 됩니다. 암호는 `DEEL_CERT_PASS`. 프록시 뒤에서도 됩니다. [설정 →](docs/ko/config.md#게이트웨이가-우리-인증서를-요구할-때-mtls) |
 | 401 / 403 | 키가 틀렸거나 인증 헤더 형식이 다름 (4가지를 자동 시도합니다) |
 | `허용되지 않은 주소입니다` | 자물쇠가 막은 것. 정상입니다 — `/model` 로 연결을 고르세요 |
 | 도구 호출이 안 먹음 | `deel diagnose` 로 판정을 보세요. 작은 모델(1B~3B)은 자주 못 합니다 |
 | 대답이 비어 있음 | 스트리밍을 무시하는 서버입니다. 한 번은 저절로 다시 부르고, 그래도 비면 이 대화에서는 스트리밍을 끕니다 |
 | 큰 파일이 중간에 끊김 | `/out` 으로 지금 상한을 보고 올리세요. 상한을 몰라 16,384 로 서 있을 수 있습니다 |
+| `60초 동안 아무것도 안 와서 끊었습니다` | 답을 통째로 모았다가 한 번에 주는 게이트웨이입니다. 프로필에 `"잠잠": 180000` (밀리초). 받은 데까지는 화면에 남습니다 |
 | `HTTP 400` 만 뜸 | 서버가 보낸 문장을 그대로 보여 줍니다. 길이 문제면 숫자를 읽어 저절로 맞춥니다 |
 | `429` · `503` 이 뜸 | 게이트웨이가 잠깐 막은 것입니다. 세 번까지 저절로 기다렸다 다시 부릅니다(`Retry-After` 를 지킵니다). 그래도 계속 뜨면 할당량을 보세요 |
 | `deel scan` 이 0곳 | 로컬 서버가 꺼져 있거나 다른 포트 — `--ports` 로 지정 |
@@ -1087,7 +1185,7 @@ deel sbom --only sbom         # SBOM 한 장만
 ## 개발
 
 ```bash
-npm test          전체 검증 (7,152항목 — 몇몇은 터미널에 따라 갈립니다)
+npm test          전체 검증 (7,844항목 — 몇몇은 터미널에 따라 갈립니다)
 npm run coverage  검사가 소스의 어디를 밟았는지
 npm run verify    반입·통신 검증만
 npm run bench     편집 성공률 측정
@@ -1144,7 +1242,7 @@ zip 은 진짜 `unzip` 으로, tar 는 진짜 `tar` 가 만든 것을 읽혀 교
 | `exitcode` · `doorparity` | 7 · 7 | 화면에 적은 종료코드 표가 진짜인가 · 문 **네 개**가 같은 것을 주는가 |
 | `no-bundle` | 21 | 배포 묶음에 남의 것이 안 섞였는가 · 검사 파일 위생 |
 | `edit-bench` | 20건 | 편집 성공률 |
-| `mutate` | 어긋 11개 | **검사가 정말 지키는가** — 지켜야 할 줄을 일부러 어긋내고 빨개지는지 본다 |
+| `mutate` | 어긋 12개 | **검사가 정말 지키는가** — 지켜야 할 줄을 일부러 어긋내고 빨개지는지 본다 |
 
 > **자세히** — 어디를 밟았는지 · 폴더 구조
 >
@@ -1156,6 +1254,9 @@ zip 은 진짜 `unzip` 으로, tar 는 진짜 `tar` 가 만든 것을 읽혀 교
 
 | 판 | 무엇이 바뀌었나 |
 |---|---|
+| [1.17.1](docs/ko/releases/1.17.md#1171) | 내 PC 에서만 초록이던 것 둘 — 지운 폴더에 쓰기 · 소스에 박힌 날 NUL |
+| **[1.17.0](docs/ko/releases/1.17.md#1170)** | 사내에 들여놓을 때 막히던 자리들 · 믿는 폴더 · mTLS · `doctor` · 훅 · 서브에이전트 · hwpx 쓰기 |
+| **[1.16.0](docs/ko/releases/1.16.md#1160)** | 깊이 봐 달라는 말을 얕게 받던 자리 · 게이트웨이 캐시 · `doc2md` · Figma `.fig` |
 | **[1.15.1](docs/ko/releases/1.15.md#1151)** | 에디터에 우리가 어떻게 인증받는지 말합니다 — ACP 레지스트리 등재 조건 |
 | **[1.15.0](docs/ko/releases/1.15.md#1150)** | 같은 것을 두 번 하지 않습니다 — 프리픽스 캐시를 깨던 조용히 비싼 아홉 자리 |
 | **[1.14.0](docs/ko/releases/1.14.md#1140)** | 적어 둔 것이 참인지 기계가 대신 봅니다 — 초록불과 「깨면 잡힌다」 는 다릅니다 |

package/README.md

@@ -20,7 +20,7 @@ Vendor APIs connect too — **only when you say so**
 
 [![Node.js CI](https://img.shields.io/github/actions/workflow/status/jysvai/deel-local-cli/test.yml?branch=main&logo=github&logoColor=white&label=Node.js%20CI)](https://github.com/jysvai/deel-local-cli/actions/workflows/test.yml)
 [![CodeQL](https://img.shields.io/github/actions/workflow/status/jysvai/deel-local-cli/codeql.yml?branch=main&logo=github&logoColor=white&label=CodeQL)](https://github.com/jysvai/deel-local-cli/actions/workflows/codeql.yml)
-[![tests](https://img.shields.io/badge/tests-7%2C152%20passing-1a7f37?logo=checkmarx&logoColor=white)](docs/en/develop.md)
+[![tests](https://img.shields.io/badge/tests-7%2C844%20passing-1a7f37?logo=checkmarx&logoColor=white)](docs/en/develop.md)
 
 [![dependencies](https://img.shields.io/badge/dependencies-0-1a7f37)](https://www.npmjs.com/package/deel-local-cli?activeTab=dependencies)
 [![ESM](https://img.shields.io/badge/ESM-Node%2020%2B-5FA04E?logo=javascript&logoColor=white)](package.json)
@@ -96,6 +96,7 @@ No account, no sign-up, no telemetry. If you already run Ollama or LM Studio,
 - [Auto-compaction](#auto-compaction)
 - [Resuming a conversation](#resuming-a-conversation)
 - [Attaching tools from outside (MCP)](#attaching-tools-from-outside-mcp)
+- [Your own rules, enforced (hooks)](#your-own-rules-enforced-hooks)
 - [Inside your editor (ACP)](#inside-your-editor-acp)
 - [Keeping secrets out of the conversation](#keeping-secrets-out-of-the-conversation)
 - [Safety](#safety)
@@ -114,12 +115,12 @@ This page is the **summary**. Each section links to the detail behind it.
 | [Models](docs/en/models.md) | Grade and window size · Korean-model presets · project detection |
 | [The screen](docs/en/interface.md) | The input box · work modes · simple vs developer · what it asks about |
 | [Tools in depth](docs/en/tools.md) | `Outline` · `Verify` · `Task` · `Jobs` · `Append` · `Def`/`Refs` · edit matching |
-| [Korean documents and Excel](docs/en/documents.md) | hwpx/docx/pptx/**PDF** · encoding · Excel → CSV |
-| [Extending](docs/en/extend.md) | Skills · plugins · MCP · ACP |
+| [Korean documents and Excel](docs/en/documents.md) | hwpx/docx/pptx/**PDF** · **creating an hwpx** · encoding · Excel → CSV |
+| [Extending](docs/en/extend.md) | Skills · plugins · MCP · subagents · hooks · ACP |
 | [Speed and spend](docs/en/tuning.md) | Per-stage effort · the prefix cache · context length |
 | [Safety and corporate review](docs/en/safety.md) | Undo · working scope · audit log · the review package |
 | [Configuration](docs/en/config.md) · [Development](docs/en/develop.md) | Env vars · run flags · running the tests · folder layout |
-| [Release notes](docs/en/releases.md) | [1.15.x](docs/en/releases/1.15.md) · [1.14.x](docs/en/releases/1.14.md) · [1.13.x](docs/en/releases/1.13.md) · [1.12.x](docs/en/releases/1.12.md) · [1.10.x](docs/en/releases/1.10.md) · [1.9.x](docs/en/releases/1.9.md) · [older](docs/en/releases.md) |
+| [Release notes](docs/en/releases.md) | [1.16.x](docs/en/releases/1.16.md) · [1.15.x](docs/en/releases/1.15.md) · [1.14.x](docs/en/releases/1.14.md) · [1.13.x](docs/en/releases/1.13.md) · [1.12.x](docs/en/releases/1.12.md) · [1.10.x](docs/en/releases/1.10.md) · [1.9.x](docs/en/releases/1.9.md) · [older](docs/en/releases.md) |
 
 ---
 
@@ -338,7 +339,7 @@ deel --offline
 The destination is printed at the top of every session:
 
 ```
- deel 1.15.1  ⌂ inside
+ deel 1.17.1  ⌂ inside
  Sends to this machine 127.0.0.1:11434  ← nowhere else
 ```
 
@@ -545,7 +546,7 @@ Names follow Claude Code / Codex conventions.
 | `/mode <mode>` | Approval policy — how much it asks (`auto` · `confirm` · `strict`) |
 | `/work [mode]` | Work mode — what kind of work you are doing |
 | `/auto` | Hand the wheel back — it picks the mode from what you type |
-| `/code` `/plan` `/architect` `/debug` `/ask` `/orchestrator` | Switch work mode directly (pins it) |
+| `/code` `/plan` `/architect` `/debug` `/inspect` `/ask` `/orchestrator` | Switch work mode directly (pins it) |
 | `/level [level]` | How much to show (`simple` · `developer`) |
 | `/motion [plain\|knight\|animal\|office\|off]` | What animates while it works — takes effect at once, and is saved |
 | `/undo [turns]` | Revert file changes |
@@ -561,6 +562,8 @@ Names follow Claude Code / Codex conventions.
 | `/recall <text>` | Search past conversations **by content** |
 | `/memory` | What persists across sessions — view, add, delete |
 | `/mcp` | Externally attached tools (MCP servers) |
+| `/hooks` | Configured hooks — where they came from, when they run |
+| `/agents` | Named subagent definitions |
 | `/init` | Create a `DEEL.md` rules file |
 | `/exit` | Quit |
 
@@ -591,6 +594,11 @@ Korean IME composition, paste, `Ctrl+A/E` and backspace all keep working.
 
 ## Work modes
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jysvai/deel-local-cli/main/docs/assets/shot-work-en-dark.svg">
+  <img alt="deel work modes: whether each can edit files, its reasoning depth, and its step ceiling" src="https://raw.githubusercontent.com/jysvai/deel-local-cli/main/docs/assets/shot-work-en-light.svg" width="900">
+</picture>
+
 What you are working on changes **which tools the model is given and how hard it thinks.**
 Cycle with `Shift+Tab`, or type the name.
 
@@ -600,9 +608,13 @@ Cycle with `Shift+Tab`, or type the name.
 | `/code` ◆ Code | Writing and fixing | Yes | Normal (`save`) |
 | `/plan` ☰ Plan | Planning first | **No** | Deep (`deep`·high) |
 | `/architect` ◈ Architect | Shaping structure | **No** | Deep (`deep`·high) |
-| `/debug` ◉ Debug | Finding causes | Yes | Deep, more steps (32) |
-| `/ask` ◇ Ask | Explaining only | **No** | Shallow (`low`) |
-| `/orchestrator` ❋ Orchestrator | Breaking up large work | Yes | Many steps (40) |
+| `/debug` ◉ Debug | Finding causes | Yes | Deep, many steps |
+| `/inspect` ◍ Inspect | Auditing for defects — with evidence, changing nothing | **No** | Deep (`deep`/high), many steps |
+| `/ask` ◇ Ask | Explaining only | **No** | Shallow (`low`) — not lowered when the ask has several parts |
+| `/orchestrator` ❋ Orchestrator | Breaking up large work | Yes | Very many steps |
+
+The step ceiling **follows the model's window** — on a 128k model debug gets 250 steps and ask gets 12.
+Hand a small model 400 steps and it just runs on past the point where its window folded.
 
 In read-only modes, `Write`, `Edit` and `Bash` are **never sent to the model at all.**
 It is not asked politely not to edit — models forget requests. A tool that isn't there can't be used.
@@ -610,7 +622,7 @@ It is not asked politely not to edit — models forget requests. A tool that isn
 Don't confuse this with `/mode`. They are separate axes:
 
 - `/mode` — **how much it asks you** (auto · confirm · strict)
-- `/work` — **what kind of work you are doing** (the seven above)
+- `/work` — **what kind of work you are doing** (the eight above)
 
 If you have explicitly set `/think` or `/mode`, your choice wins. A work mode never
 overrides something a person chose.
@@ -653,7 +665,7 @@ Names and arguments match Claude Code, so skills written for that convention wor
 | Tool | What it does |
 |---|---|
 | `Read` | Read a file (line numbers, `offset`/`limit`, **Excel as CSV, hwpx/docx/pptx and PDF as text**) |
-| `Write` | Write / overwrite a file (**several at once via the `files` array**) |
+| `Write` | Write / overwrite a file (**several at once via the `files` array**, **a `.hwpx` that does not exist yet becomes a real Hancom document**) |
 | `Append` | Append to the end of a file — **how large files get written in pieces** |
 | `Edit` | Replace an exact string (`replace_all`; **several sites at once via the `edits` array**) |
 | `Move` | Move / rename files and folders — **how you restructure** (`moves` array; covered by undo) |
@@ -689,12 +701,49 @@ their cost; here is why.
 **A file saved as CP949 is written back as CP949.** The encoding is never changed.
 Excel (`.xlsx`) is read as CSV — read-only.
 
+**Creating a Korean document that did not exist does work, though.** `Write` on a
+`.hwpx` path that is not there yet produces a real hwpx to spec (OWPML) — `#`
+becomes a heading, `-` becomes a bullet. That is the spot where "write me the
+report" used to end at one `.md` a person then pasted into Hancom Office. Tables
+are flattened to text, and the docs say plainly that **whether Hancom Office opens
+the file was not verified here.**
+
+To keep a document as **one Markdown file**, use `deel doc2md`. Tables survive as
+real `| name | value |` tables, so a model has far less to guess at than it does
+with flattened text.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jysvai/deel-local-cli/main/docs/assets/shot-doc2md-dark.svg">
+  <img alt="deel doc2md turning a docx into Markdown — the table stays a table" src="https://raw.githubusercontent.com/jysvai/deel-local-cli/main/docs/assets/shot-doc2md-light.svg" width="820">
+</picture>
+
+```bash
+deel doc2md report.pptx            # to stdout
+deel doc2md spec.pdf --out spec.md # to a file
+```
+
+**Figma designs (`.fig`) are read too.** Handing over a design with "build this"
+used to end at "binary file, cannot be read". What is inside is not only
+pictures — **frame names, text, sizes and stacking order** are all there as
+characters.
+
+```
+- FRAME · Login screen 375×812
+  - TEXT · Title "Welcome back"
+  - FRAME · Field 335×48
+    - TEXT · Label "Email"
+```
+
+No colours, shadows or fonts — and it **says so up front**. Recent `.fig` files
+are zstd-compressed, which needs Node 22.15 or newer; on an older one it says
+**this Node cannot unpack it**, not "corrupt file".
+
 Old formats (`.ppt`, `.doc`, `.xls`, `.rtf`) are read by **borrowing the LibreOffice already
 on this machine** — the same terms on which deel borrows `rg`, and nothing is ever installed.
 With no converter it **says so definitively and stops**: what is missing, what you can do about
 it, and not to open the file again. Turn it off with `DEEL_CONVERT=off`.
 
-> **More** — Encoding · Excel · borrowing a converter
+> **More** — Encoding · Excel · **creating an hwpx** · `doc2md` · borrowing a converter
 >
 > **[Korean documents and Excel read →](docs/en/documents.md#korean-text-and-excel)**
 
@@ -962,6 +1011,37 @@ The model sees it as `mcp__wiki__search`. `/mcp` shows what is attached.
 
 ---
 
+## Your own rules, enforced (hooks)
+
+Every company guards something different — one team must never let `git push` run,
+another needs its formatter after every edit. Putting all of it inside the program means
+every team forks, and from then on our fixes stop reaching them. So we give you
+**the place** instead.
+
+Write it in `.deel/hooks.json`. Claude Code's `hooks` shape is accepted as-is:
+
+```json
+{ "hooks": [ { "때": "도구전", "도구": "Bash", "명령": "python .deel/gate.py" } ] }
+```
+
+Everything is handed over as **one line of JSON on stdin**, and the answer is the
+**exit code** — `0` passes, `2` blocks. Four events: `PreToolUse` (can block),
+`UserPromptSubmit` (can block), `PostToolUse`, `Stop`. `/hooks` shows what is armed.
+
+**A broken hook blocks.** The common convention lets every failure but exit 2 pass
+through, so one typo in the hook file leaves the gate quietly open — while the screen
+still says "3 hooks." A gate with nobody at it is not a locked gate.
+
+**The project file is read only in a trusted folder.** Without that, one `git clone`
+is enough to run someone else's commands on your machine. `deel --no-hooks` for one
+run, `DEEL_HOOKS=off` for good.
+
+> **More** — This is somebody else's program too · A broken hook blocks
+>
+> **[Extending read →](docs/en/extend.md#your-own-rules-enforced-hooks)**
+
+---
+
 ## Inside your editor (ACP)
 
 A tool that makes you open one more terminal window stops being used after about two weeks.
@@ -977,6 +1057,23 @@ deel acp
 The editor spawns that as a child process and exchanges newline-delimited JSON-RPC 2.0 over
 stdio. It is not a command you type yourself.
 
+**In Zed, concretely.** Either use `Settings → External Agents → Add Custom Agent` in the
+agent panel, or put this straight into `settings.json`:
+
+```json
+{
+  "agent_servers": {
+    "deel": { "type": "custom", "command": "npx", "args": ["-y", "deel-local-cli", "acp"], "env": {} }
+  }
+}
+```
+
+Then pick **deel** in the agent panel. If you have not run `deel setup` yet, deel tells the
+editor so **the way the spec says to** (ACP's `AuthRequired`), along with the method it sent
+at connect time — ``Run `deel setup` in a terminal``. That is there so a first run is not a
+red error message you cannot tell from a bug. Finish it once in a terminal and the editor
+opens straight into a conversation from then on.
+
 **What you get once it is attached:**
 
 | In the editor | From deel |
@@ -985,7 +1082,7 @@ stdio. It is not a command you type yourself.
 | Tool list with icons and status | `Read` is a read, `Edit` is an edit, `Bash` is an execution — **the kind is sent**, not just a name |
 | Clickable file links | The **absolute path** of every file touched |
 | Approval dialog | deel's safety rails, rendered as the editor's own prompt (`allow once` · `always allow` · `reject`) |
-| Mode picker | deel's seven work modes (auto · code · plan · architect · debug · ask · orchestrator) |
+| Mode picker | deel's eight work modes (auto · code · plan · architect · debug · inspect · ask · orchestrator) |
 | Stop button | Reaches the turn mid-flight, even while waiting on the model |
 | Past conversations | Still there after a restart. They live in the **same place** as the terminal's, so a session started in the editor can be picked up with `deel --resume` |
 
@@ -1101,7 +1198,7 @@ audit-log spec to write SIEM ingestion rules.
 | File | What |
 |---|---|
 | `import-review.txt` | Dependencies · install scripts · **every network and process-spawn call site found by scanning the source** (file:line) · the three outbound lanes · SHA-256 per file |
-| `sbom.cdx.json` | **SBOM (CycloneDX 1.5).** Feed it straight to a scanner. One component per file with SHA-256; dependencies stated as an **explicit empty array** — "not declared" and "none" are different claims |
+| `sbom.cdx.json` | **SBOM (CycloneDX 1.7).** Feed it straight to a scanner. One component per file with SHA-256 and a license; dependencies stated as an **explicit empty array** — "not declared" and "none" are different claims. All four CISA 2026 minimum elements (hash algorithm, component license, generating tool, generation context) are filled in |
 | `audit-spec.json` | Egress list (per lane: when, where, what, how it's stopped, and the source location) · **audit-log spec** (field names and meanings, plus what is never recorded) · file hashes |
 
 ```bash
@@ -1109,6 +1206,7 @@ deel audit                    # the human-readable sheet only
 deel sbom                     # the two machine-readable ones, on stdout (deel sbom | jq)
 deel sbom --out review.json   # to a file
 deel sbom --only sbom         # just the SBOM
+deel stats                    # what this folder actually did (summarises .deel/audit.jsonl)
 ```
 
 With the screen language set to English these three, and the `deel pack` archive itself,
@@ -1144,11 +1242,13 @@ Stored in `~/.deel/config.json`. A `.deel/config.json` in the project folder tak
 | certificate error | `set NODE_EXTRA_CA_CERTS=C:\path\corp-ca.pem` |
 | behind a proxy | `set HTTPS_PROXY=http://proxy:port` (with auth: `http://user:pw@proxy:port`). If the first screen and `/status` show `proxy …`, it is in use. Exclude hosts with `NO_PROXY=.corp.com,10.1.2.3`; turn it off entirely with `"proxy": "none"` in the config |
 | the proxy answers 407 | Put `user:pw@` into the proxy address. Proxies that only accept NTLM · Negotiate are not supported — ask the admin for Basic or an unauthenticated address |
+| the gateway asks for **your** certificate (mTLS) | Put `"clientCert": { "certFile": "...", "keyFile": "..." }` in the profile — a `.pfx` bundle works too. Passphrase via `DEEL_CERT_PASS`. Works behind a proxy. [Config →](docs/en/config.md#when-the-gateway-asks-for-our-certificate-mtls) |
 | 401 / 403 | Wrong key or auth header style (four are tried automatically) |
 | `address not permitted` | The lock did its job — pick a connection with `/model` |
 | Tool calls don't work | Run `deel diagnose`. Small models (1B–3B) often can't |
 | Empty replies | The server ignores streaming. deel retries once, then turns streaming off for the session |
 | Large files cut off mid-write | Check `/out` and raise it — the cap may be sitting at the 16,384 default because it could not be discovered |
+| `Nothing arrived for 60s` | The gateway buffers the whole answer and sends it at once. Set `"streamIdleMs": 180000` in the profile. What did arrive stays on screen |
 | Only `HTTP 400` shows | The server's own message is shown verbatim. If it is a length problem the number is read and applied automatically |
 | `429` · `503` shows | The gateway pushed back for a moment. deel waits and calls again, up to three times (honouring `Retry-After`). If it keeps happening, check your quota |
 | `deel scan` finds nothing | Server is off or on another port — use `--ports` |
@@ -1158,7 +1258,7 @@ Stored in `~/.deel/config.json`. A `.deel/config.json` in the project folder tak
 ## Development
 
 ```bash
-npm test          Full suite (7,152 checks; a few are TTY-dependent)
+npm test          Full suite (7,844 checks; a few are TTY-dependent)
 npm run coverage  Which lines the tests actually execute
 npm run verify    Import + network checks only
 npm run bench     Edit success rate
@@ -1201,7 +1301,7 @@ so one run tells you everything.
 | `exitcode` · `doorparity` | 7 · 7 | The printed exit-code table is real · all **four** doors hand out the same thing |
 | `no-bundle` | 21 | Nothing foreign in the published package; test-file hygiene |
 | `edit-bench` | 20 cases | Edit success rate |
-| `mutate` | 11 mutants | **Whether the tests actually guard** — break the line on purpose, check it turns red |
+| `mutate` | 12 mutants | **Whether the tests actually guard** — break the line on purpose, check it turns red |
 
 > **More** — Coverage · Layout
 >
@@ -1213,6 +1313,9 @@ so one run tells you everything.
 
 | Version | What changed |
 |---|---|
+| [1.17.1](docs/en/releases/1.17.md#1171) | Two things only green on one machine — writing into a deleted directory · raw NUL in the source |
+| **[1.17.0](docs/en/releases/1.17.md#1170)** | What blocked it from getting inside a company · trusted folders · mTLS · `doctor` · hooks · subagents · writing hwpx |
+| **[1.16.0](docs/en/releases/1.16.md#1160)** | A deep request no longer lands in a shallow mode · gateway cache · `doc2md` · Figma `.fig` |
 | **[1.15.1](docs/en/releases/1.15.md#1151)** | Telling the editor how we get authenticated — ACP Registry listing requirement |
 | **[1.15.0](docs/en/releases/1.15.md#1150)** | Stop doing the same thing twice — nine quietly expensive places that broke the prefix cache |
 | **[1.14.0](docs/en/releases/1.14.md#1140)** | A machine now checks that what we wrote down is true — green does not mean guarded |