npm - deel-local-cli - Versions diffs - 1.4.2 → 1.5.0 - Mend

deel-local-cli 1.4.2 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/README.md CHANGED Viewed

@@ -1,907 +1,988 @@
-<div align="center">
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/hero-ko-dark.svg">
-  <img alt="deel — 이 컴퓨터 안에서만" src="docs/assets/hero-ko-light.svg" width="620">
-</picture>
-### 로컬 모델과 사내 게이트웨이만으로 도는 코딩 에이전트 CLI
-의존성 0개 · Node 20+ · 소스가 나가는 자리는 딱 한 곳
-<br>
-[![npm](https://img.shields.io/npm/v/deel-local-cli?logo=npm&logoColor=white&label=npm&color=cb3837)](https://www.npmjs.com/package/deel-local-cli)
-[![downloads](https://img.shields.io/npm/dt/deel-local-cli?label=downloads&color=1a7f37)](https://www.npmjs.com/package/deel-local-cli)
-[![node](https://img.shields.io/node/v/deel-local-cli?logo=nodedotjs&logoColor=white&label=node&color=5FA04E)](https://nodejs.org)
-[![license](https://img.shields.io/npm/l/deel-local-cli?label=license&color=0969da)](LICENSE)
-[![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-3%2C498%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)
-[![network](https://img.shields.io/badge/network-127.0.0.1%20only-1a7f37?logo=wireguard&logoColor=white)](#데이터가-나가는-길)
-[![telemetry](https://img.shields.io/badge/telemetry-none-1a7f37?logo=ghostery&logoColor=white)](#데이터가-나가는-길)
-**[English](README.en.md)** · [사내 반입 안내](#사내-반입) · [문제 해결](#문제-해결) · [자세한 문서](docs/ko/)
-</div>
----
-```
- ╭──────────────────────────────────────────────────────────────╮
- │ deel  OpenAI 호환 규격                                        │
- │                                                              │
- │ 모델    qwen2.5-coder:7b  (40k 토큰)                          │
- │ 보냄    이 컴퓨터 안 127.0.0.1:11434  ← 여기 말고는 어디로도 안 갑니다  │
- │ 연결    스트리밍 · 도구 · 추론 조절                              │
- │ 폴더    C:\work\myproject                                     │
- │ 승인    ⏵⏵ 자동 승인  — 안 묻고 고칩니다. 되돌리기(/undo)가 안전망입니다 │
- │         Shift+Tab 으로 바꿉니다  ·  Tab 은 치던 / 명령을 채웁니다   │
- │ 이 PC   스킬 337 · 명령 127 · 플러그인 42                       │
- ╰──────────────────────────────────────────────────────────────╯
- /help 명령 목록   /think 추론 강도   Ctrl+C 중단·끝내기
- ▏myproject · qwen2.5-coder:7b ▏ ▰▰▱▱▱▱▱▱▱▱ 22% 28k/128k ▏ ◎ 종합 · ◇ medium·절약 · ⏵⏵ 자동
- ❯ 로그 형식 통일해줘
-  ❊ Grep(console.log)
-    └ 1개 파일 · 1건
-  ◧ Read(src/runner.js)
-    └ 5줄
-  ◈ Edit(src/runner.js)
-    └ 1군데
-  ▌ 로그 호출을 logger 형식으로 통일했습니다. runner.js 한 군데를 고쳤습니다.
-  ── 4.2초 · 도구 3회 · ↑3,900 ↓180
-```
----
-## 목차
-- [왜 만들었나](#왜-만들었나)
-- [빠른 시작](#빠른-시작)
-- [데이터가 나가는 길](#데이터가-나가는-길)
-- [로컬 모델 여러 개 쓰기](#로컬-모델-여러-개-쓰기)
-- [대화 중 명령](#대화-중-명령)
-- [작업 모드](#작업-모드)
-- [쉬움 · 개발자](#쉬움--개발자)
-- [도구](#도구)
-- [한글 문서와 엑셀](#한글-문서와-엑셀)
-- [만든 웹을 그 자리에서 띄웁니다](#만든-웹을-그-자리에서-띄웁니다)
-- [스킬·플러그인](#스킬플러그인)
-- [추론 강도](#추론-강도)
-- [자동 압축](#자동-압축)
-- [대화 이어하기](#대화-이어하기)
-- [밖에서 도구 붙이기 (MCP)](#밖에서-도구-붙이기-mcp)
-- [에디터 안에서 쓰기 (ACP)](#에디터-안에서-쓰기-acp)
-- [비밀이 새지 않게](#비밀이-새지-않게)
-- [안전망](#안전망)
-- [사내 반입](#사내-반입)
-- [설정](#설정)
-- [문제 해결](#문제-해결)
-- [개발](#개발)
-- [릴리스 노트](#릴리스-노트)
-여기는 **요약**입니다. 절마다 붙은 링크를 따라가면 그 안의 이야기가 나옵니다.
-| 자세한 문서 | 무엇이 있나 |
-|---|---|
-| [모델 다루기](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 · 인코딩 · 엑셀 → 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.4.2](docs/ko/releases.md#142) · [1.4.1](docs/ko/releases.md#141) · [1.4.0](docs/ko/releases.md#140) · [1.3.0](docs/ko/releases.md#130) · [1.2.0](docs/ko/releases.md#120) |
----
-## 왜 만들었나
-사내 보안 정책이 **미승인 소프트웨어 반입**을 막으면, 코딩 에이전트 도구는 대부분 쓸 수 없습니다.
-의존성 수백 개가 딸려 오고, 설치할 때 스크립트가 돌고, 어디로 통신하는지 한 줄로 답할 수 없기 때문입니다.
-deel 은 그 심사를 통과하는 것을 목표로 만들었습니다.
-| | deel |
-|---|---|
-| 외부 의존성 | **0개** — Node 내장 기능만 |
-| 설치 스크립트 | **없음** — 압축 풀고 바로 실행 |
-| 소스가 나가는 자리 | **딱 한 곳** — 직접 설정한 주소 |
-| 필요한 것 | Node 20 이상 |
-직접 확인하실 수 있습니다.
-```bash
-npm view deel-local-cli dependencies   # {}
-npm view deel-local-cli scripts        # install/postinstall 없음
-deel audit                             # 심사서 전문 출력
-```
----
-## 빠른 시작
-### 설치
-```bash
-npm install -g deel-local-cli
-```
-설치가 싫으면 소스를 받아 그대로 쓰셔도 됩니다. `npm install` 이 필요 없습니다.
-```bash
-git clone https://github.com/jysvai/deel-local-cli
-node deel-local-cli/bin/deel.js
-```
-> **주의** — 홈 디렉터리(`~`)에서 `npm install` 하지 마세요. 거기에 `node_modules` 가 생기면
-> 이후 모든 npm 명령이 그 폴더를 훑어서 무관한 패키지 경고를 냅니다. `-g` 로 설치하거나 `npx` 를 쓰세요.
-### 연결 정하기
-이 PC 에 떠 있는 로컬 서버를 훑어서 고르는 방법:
-```bash
-deel scan --pick
-```
-주소를 직접 넣는 방법 (사내 게이트웨이는 이쪽):
-```bash
-deel setup
-```
-### 시작
-작업할 폴더에서 `deel` 을 칩니다. **그 폴더가 작업 범위가 되고, 밖의 파일은 읽지도 쓰지도 못합니다.**
-```bash
-cd C:\work\myproject
-deel
-```
----
-## 데이터가 나가는 길
-코딩 에이전트는 소스 코드를 통째로 모델에 보냅니다. **그 주소가 어디인지가 전부입니다.**
-말로 보장하는 대신 코드가 막습니다 — `src/safety/network.js` 가 요청마다 확인하고,
-허용 목록에 없으면 요청을 만들지도 않습니다.
-```
- [A] 모델 게이트웨이 ─── 소스 코드가 나가는 유일한 길
-     setup 에서 정한 한 자리만. 모델을 바꾸면 이전 자리는 닫힙니다.
- [B] 웹 읽기 (WebFetch) ─ 받아 오기만 하는 길
-     GET 만. 본문 0바이트. 사내망·로컬 주소는 거절. 다녀온 곳은 전부 기록.
- [C] 플러그인 받기 ────── /plugin install 을 칠 때만 잠깐
-```
-`--offline` 을 주면 **B 와 C 가 모두 막히고 이 컴퓨터 안으로만** 다닙니다.
-```bash
-deel --offline
-```
-무엇이 어디로 갈 수 있는지는 켤 때 화면 맨 위에 늘 적혀 있습니다.
-```
- 보냄    이 컴퓨터 안 127.0.0.1:11434  ← 여기 말고는 어디로도 안 갑니다
-```
-수집·전송하는 것이 없습니다. 텔레메트리, 사용 통계, 오류 보고 전부 없습니다.
-대화 기록·되돌리기 이력·설정은 작업 폴더의 `.deel/` 안에만 남습니다.
-> 검증: `npm test` 의 network·web 검사 55항목. 허용되지 않은 서버에 실제로 요청이
-> **한 건도 닿지 않는지**까지 진짜 서버를 띄워서 확인합니다.
----
-## 로컬 모델 여러 개 쓰기
-로컬 런타임은 보통 하나만 쓰지 않습니다. Ollama 로 작은 모델을 돌리면서
-LM Studio 로 큰 모델을 띄워 두기도 합니다. `deel scan` 이 알려진 자리 13곳을 동시에 두드려
-전부 찾아냅니다.
-```
-$ deel scan
-── 로컬 모델 서버 훑기 ───────────────────────────────────────────────
-  127.0.0.1 의 알려진 자리 13곳을 두드립니다. 바깥으로는 나가지 않습니다.
-  ✓ 3곳 찾음
-  ◆ Ollama      127.0.0.1:11434   Ollama 규격   36ms
-      · qwen2.5-coder:7b            7B · 4.4GB
-      · llama3.2:1b                 1B · 1.2GB
-  ◆ LM Studio   127.0.0.1:1234     OpenAI 호환    7ms
-      · devstral-small-2507
-  ◆ llama.cpp   127.0.0.1:8080     OpenAI 호환    7ms
-      · gemma-3-4b-it
-  합계  서버 3곳 · 모델 6개
-  추천  Ollama · qwen2.5-coder:7b
-        코딩용 모델 · 도구 호출을 잘하는 계열
-```
-포트로 단정하지 않고 **응답을 보고** 런타임을 구분합니다 — Ollama 는 `/api/version`,
-LM Studio 는 `/api/v0/models`, llama.cpp 는 `/props`. 못 알아보면 `(추정)` 이라고 밝힙니다.
-| 명령 | 하는 일 |
-|---|---|
-| `deel scan` | 찾아서 보여주기만 |
-| `deel scan --pick` | 목록에서 골라 등록 |
-| `deel scan --save` | 찾은 것 전부 등록 |
-| `deel scan --ports 9000,9100` | 기본 자리 말고 더 볼 포트 |
-| `deel scan --host <주소>` | 기본은 `127.0.0.1` |
-| `deel scan --key <키>` | 키가 필요한 로컬 서버일 때 |
-등록한 뒤에는 대화 중 `/model` 로 갈아탑니다. **대화 내용은 그대로 이어집니다.**
-> **자세히** — 걸린 모델에 맞춰 스스로 바뀝니다 · 국산 모델은 겪기 전에 압니다 · 작은 창에서는 고정 몫을 줄입니다 · 켤 때 이 폴더가 무슨 프로젝트인지 읽습니다
->
-> **[모델 다루기 읽기 →](docs/ko/models.md#로컬-모델-여러-개-쓰기)**
----
-## 대화 중 명령
-이름은 Claude Code / Codex 관례에 맞췄습니다.
-| 명령 | 하는 일 |
-|---|---|
-| `/help` | 명령 목록 |
-| `/bell [on|off]` | 다 됐을 때·물어볼 때 종소리와 창 제목 |
-| `/lang [ko|en]` | 화면 말 — 영어권 사람이 쓸 때. 모델이 읽는 글도 같이 따라간다(영어 쪽이 1,400토큰 덜 먹는다). 코드는 그대로 |
-| `/consult <프로필> <질문>` | 다른 모델에게 한 번 물어보기 — 지금 쓰는 것은 안 바꿈 |
-| `/export` | 이 대화를 **보고서 한 장**(HTML)으로 — 시킨 것·바뀐 것·확인한 것. 폐쇄망에서 여는 자기완결 파일 |
-| `/lsp [on\|off]` | 언어 서버 — 무엇이 깔려 있고 `Def`·`Refs` 를 쓸 수 있는지. `off` 는 고친 뒤 진단만 끔 |
-| `/context` | 무엇이 컨텍스트를 먹고 있는지 |
-| `/ctx [auto\|숫자\|자세히]` | 컨텍스트 **길이** — 모델에 맞춰 다시 재거나 직접 지정 |
-| `/out [숫자\|auto]` | 한 번에 받을 **답 길이** 상한 — 큰 파일이 잘리면 여기를 올립니다 |
-| `/grade [작음\|보통\|큼\|auto]` | 모델 **급** — 얼마나 알아서 하나. `/ctx` 와 다른 축입니다 |
-| `/compact` | 앞선 대화를 요약해서 접기 |
-| `/clear` | 대화 비우기 (연결·규칙은 유지) |
-| `/thread [new\|fork\|close\|번호]` | 대화 갈래 — 곁가지를 딴 자리에서. 연결·되돌리기는 같이 씁니다 |
-| `/learned [지우기]` | 쓰면서 저절로 알게 된 것 — 되는 명령·이 모델의 버릇 |
-| `/pin <말>` | 못 박기 — 접거나 요약해도 **안 지워지는** 말 |
-| `/evidence [파일]` | 증거 — 무엇을 바꿨고 무엇이 그걸 증명하나. **안 된 것도** 적습니다 |
-| `/model` | 연결·모델 바꾸기 |
-| `/model 카드` | 이 모델을 겪어 본 결과 — 그래서 deel 이 무엇을 바꿔 뒀는지 |
-| `/think <강도>` | 추론 강도 (`off·low·medium·high·max`) |
-| `/think 배분 <배분>` | 단계별 배분 (`균일·절약·깊게`) |
-| `/think 자세히` | 단계표 — 어느 단계를 어떤 강도·상한으로 도는지 |
-| `/mode <모드>` | 승인 정책 — 얼마나 물어보나 (`auto` · `confirm` · `strict`) |
-| `/work [모드]` | 작업 모드 — 무슨 일을 하는 중인가 |
-| `/auto` | 다시 맡기기 — 말을 보고 알맞은 모드로 저절로 옮겨 갑니다 |
-| `/code` `/plan` `/architect` `/debug` `/ask` `/orchestrator` | 작업 모드 바로 바꾸기 (그때부터 고정) |
-| `/level [수준]` | 화면에 무엇을 내놓을지 (`쉬움` · `개발자`) |
-| `/undo [턴수]` | 파일 변경 되돌리기 |
-| `/diff [파일]` | 이번 대화에서 바뀐 파일 · 바뀐 자리 보기 |
-| `/preview [폴더\|파일\|off]` | 만든 웹을 이 자리에서 띄워 보기 — 브라우저가 같이 열립니다 |
-| `/tools` | 쓸 수 있는 도구 |
-| `/skills [검색어\|all\|off]` | 스킬 보기·검색·골라 올리기 |
-| `/plugin [install\|remove\|pack]` | 플러그인 관리 |
-| `/cost` | 이번 세션 사용량 |
-| `/status` | 연결 상태 |
-| `/scan [save]` | 이 PC 에 떠 있는 로컬 모델 서버 훑기 (`save` 면 바로 등록) |
-| `/sessions` | 이 폴더의 지난 대화 목록 |
-| `/recall <말>` | 지난 대화에서 **내용으로** 찾기 |
-| `/memory` | 대화가 끝나도 남는 기억 — 보기·적기·지우기 |
-| `/mcp` | 밖에서 붙인 도구(MCP) 서버 보기 |
-| `/init` | `DEEL.md` 규칙 파일 만들기 |
-| `/exit` | 끝내기 |
-`/scan` 과 `/sessions` 는 나가지 않고도 씁니다. 로컬 서버를 새로 켰거나 모델을
-바꿔 올렸을 때 `/scan save` → `/model` 두 번이면 대화를 이어둔 채로 갈아탑니다.
-**치지 않고 쓰는 것**
-| 키 | 무엇을 |
-|---|---|
-| `Tab` | 치던 `/` 명령을 채웁니다. 치는 도중에 후보가 상자 아래에 뜹니다 |
-| `Shift+Tab` | 승인 방식 (`⏵⏵ 자동` → `⏵ 위험만` → `⏸ 모두`) |
-| `Ctrl+O` | 작업 모드 (`종합` → `코드` → `계획` → …) |
-| `↑` `↓` | 지난 입력 이력 |
-| `Ctrl+C` | 답하는 중이면 그 답만 끊고, 빈 줄에서 두 번이면 끝냅니다 |
-한글 조합·붙여넣기·`Ctrl+A/E`·백스페이스는 전부 그대로 됩니다.
-> **자세히** — @파일 로 바로 붙이기 · 도중에 멈추기
->
-> **[화면과 조작 읽기 →](docs/ko/interface.md#대화-중-명령)**
----
-## 작업 모드
-무슨 일을 하는 중인지에 따라 **줄 수 있는 도구와 추론 설정이 같이 바뀝니다.**
-`Shift+Tab` 으로 차례로 돌리거나, 이름을 그대로 치면 됩니다.
-| 모드 | 하는 일 | 파일을 고치나 | 추론 |
-|---|---|---|---|
-| `/auto` ◎ 종합 | **처음 값.** 말을 보고 알맞은 모드로 옮겨 간다 | 예 | 보통 (`save`) |
-| `/code` ◆ 코드 | 고치고 만든다 | 예 | 보통 (`save`) |
-| `/plan` ☰ 계획 | 먼저 계획만 세운다 | **아니오** | 깊게 (`deep`·high) |
-| `/architect` ◈ 설계 | 구조를 짠다 | **아니오** | 깊게 (`deep`·high) |
-| `/debug` ◉ 디버그 | 원인을 찾는다 | 예 | 깊게 · 단계 많이 (32) |
-| `/ask` ◇ 묻기 | 설명만 한다 | **아니오** | 얕게 (`low`) |
-| `/orchestrator` ❋ 총괄 | 큰 일을 쪼개서 | 예 | 단계 아주 많이 (40) |
-읽기만 하는 모드에서는 `Write`·`Edit`·`Bash` 를 **모델에게 아예 보내지 않습니다.**
-"고치지 마세요" 라고 부탁하지 않습니다 — 모델은 부탁을 잊습니다. 없는 도구는 못 씁니다.
-`/mode` 와 헷갈리지 마세요. 둘은 다른 축입니다.
-- `/mode` — **얼마나 물어보나** (auto · confirm · strict)
-- `/work` — **무슨 일을 하는 중인가** (위 일곱 가지)
-`/think` 나 `/mode` 를 직접 고른 적이 있으면 그 선택이 우선합니다.
-모드가 사람이 고른 값을 덮어쓰지 않습니다.
-> **자세히** — 저절로 옮겨 가기 (종합 모드)
->
-> **[화면과 조작 읽기 →](docs/ko/interface.md#작업-모드)**
----
-## 쉬움 · 개발자
-처음 켠 사람에게 명령 스무 개를 들이밀면 아무것도 못 고릅니다.
-그렇다고 기능을 잠그면 쓸 만해졌을 때 막힙니다. 그래서 **보이는 것만** 나눕니다.
-| | 쉬움 (기본) | 개발자 |
-|---|---|---|
-| `/help` 목록 | 자주 쓰는 것만 | 전부 |
-| 오류 문구 | 무엇을 하면 되는지 | 원래 문구 그대로 |
-| 안전 장치 | **똑같음** | **똑같음** |
-`/level 개발자` 로 바꾸면 설정에 남아 다음에 켤 때도 이어집니다.
-중요한 것 두 가지입니다.
-- **감춘 것도 그대로 먹습니다.** 쉬움에서 `/think high` 를 쳐도 됩니다. 목록에 안 띄울 뿐입니다.
-- **초보라고 승인을 덜 받지 않습니다.** 되돌리기·작업 범위·위험 명령 차단은 두 수준이 같습니다.
-  초보일수록 되돌릴 수 있어야 합니다.
-> **자세히** — 입력칸 · 명령은 다 안 쳐도 됩니다 · 일하는 중에는 상자가 그대로 있습니다 · 왼쪽 그림도 같이 움직입니다 외 1개
->
-> **[화면과 조작 읽기 →](docs/ko/interface.md#쉬움--개발자)**
----
-## 도구
-이름과 인자를 Claude Code 와 같게 맞췄습니다. 그 관례로 쓰인 스킬·명령이 그대로 먹습니다.
-| 도구 | 하는 일 |
-|---|---|
-| `Read` | 파일 읽기 (줄 번호 · `offset`/`limit` 지원 · **엑셀은 CSV 로, hwpx·docx·pptx 는 글로 바꿔서**) |
-| `Write` | 파일 쓰기·덮어쓰기 (**여러 개는 `files` 배열로 한 번에**) |
-| `Append` | 파일 끝에 이어 붙이기 — **큰 파일을 나눠 쓰는 자리** |
-| `Edit` | 정확한 문자열 바꾸기 (`replace_all` · **여러 군데는 `edits` 배열로 한 번에**) |
-| `Glob` | 이름 패턴으로 파일 찾기 |
-| `Grep` | 내용 정규식 검색 |
-| `Bash` | 명령 실행 (**끝나지 않는 것은 `background: true`**) |
-| `Skill` | 스킬 본문 펼쳐 읽기 (스킬이 있을 때만 모델에게 보임) |
-| `WebFetch` | 웹 페이지 읽기 (읽기 전용 · `--offline` 이면 숨김) |
-| `Recall` | **지난 대화**에서 찾기 — "저번에 그거" 를 모델이 스스로 뒤진다 |
-| `Remember` | 대화가 끝나도 남길 것 한 줄 — 다음에 켤 때 처음부터 안다 |
-| `TodoWrite` | 할 일 목록 — 긴 일을 쪼개서 어디까지 했는지 화면에 띄움 |
-| `Outline` | 폴더의 **뼈대만** 보기 — 통째로 읽는 것보다 수십 분의 일 |
-| `Verify` | 만든 것이 **진짜 되는지** 확인 |
-| `Task` | 큰 일의 한 덩이를 **따로 떨어진 창**에서 돌리기 |
-| `Jobs` | **뒤에서 도는 명령** 보기·읽기·끝내기 — `Bash` 의 `background` 와 짝 |
-| `Def` | 이름이 **어디 정의됐는지** — 언어 서버가 깔려 있을 때만 보입니다 |
-| `Refs` | 이름을 **어디서 쓰는지** 전부 — 언어 서버가 깔려 있을 때만 보입니다 |
-Claude Code 에 없는 것은 일곱입니다 — `Append` · `Recall` · `Remember` ·
-`Outline` · `Verify` · `Task` · `Jobs`. 도구 하나가 스키마로 150~400토큰을 먹고
-그게 **매 요청마다** 나가므로, 늘릴 때마다 검사에서 한 번 멈추게 해 뒀습니다
-(`test/loop.test.js`). 뒤의 넷은 그 값을 치르고도 넣을 만해서 넣은 것들이라,
-아래에 왜인지를 적어 뒀습니다.
-> **자세히** — Outline · Verify · Task · Def · Refs · 끝나지 않는 명령은 뒤에서 외 9개
->
-> **[도구 자세히 읽기 →](docs/ko/tools.md#도구)**
----
-## 한글 문서와 엑셀
-**CP949 로 저장된 파일은 CP949 로 되돌려 씁니다.** 인코딩을 바꾸지 않습니다.
-엑셀(`.xlsx`)은 CSV 로, 한글·워드·파워포인트(`.hwpx`/`.docx`/`.pptx`)는 글로
-바꿔서 읽습니다 — 전부 읽기 전용입니다.
-> **자세히** — 인코딩 · 엑셀 · hwpx/docx/pptx
->
-> **[한글 문서와 엑셀 읽기 →](docs/ko/documents.md#한글-문서와-엑셀)**
----
-## 만든 웹을 그 자리에서 띄웁니다
-```
-❯ /preview
-  ▶ 띄웠습니다  http://127.0.0.1:56801/
-  보여 주는 것 .
-  파일을 고치면 화면이 저절로 새로 뜹니다.
-  이 컴퓨터에서만 열립니다(127.0.0.1). 다른 PC 에서는 안 보입니다.
-  끄려면 /preview off  · deel 을 끝내면 같이 꺼집니다.
-```
-브라우저가 같이 열립니다. `/preview 폴더` 로 자리를 정하고, `/preview off` 로 끕니다.
-**파일을 두 번 눌러 여는 것(`file://`)과 다릅니다.** `file://` 에서는 아래가 전부
-막힙니다 — 그런데 오류는 콘솔에만 나오고 화면은 그냥 희어서, 만든 사람은 제 코드를
-의심하며 시간을 씁니다. 진짜 HTTP 서버라 다 돕니다:
-| | `file://` | `/preview` |
-|---|---|---|
-| `<script type="module">` · `import` | 막힘 (CORS) | **됨** |
-| `fetch('./자료.json')` | 막힘 | **됨** |
-| `new Worker(...)` | 막힘 | **됨** |
-| `WebAssembly.compileStreaming` | 막힘 (형식) | **됨** |
-| 텍스처·`getImageData` | 캔버스 오염 | **됨** |
-| `.glb` / `.gltf` (Three.js) | 형식 없음 → 조용히 안 그려짐 | **됨** |
-실제 크롬에서 이 일곱 가지를 돌려 **7/7** 을 확인했습니다.
-라우터를 쓰는 앱(React Router 등)은 안쪽 주소에서 새로고침해도 첫 장이 나옵니다.
-다만 확장자가 있는 요청(`app.js`)에는 절대 안 그럽니다 — 없는 스크립트에 HTML 을
-돌려주면 `Unexpected token '<'` 로 죽는데, 그게 진짜 원인(파일 이름 오타)을 가립니다.
-### 열어 주는 만큼만 엽니다
-서버를 띄운다는 것은 내 디스크를 남에게 열어 주는 일입니다.
-- **`127.0.0.1` 에만** 묶습니다. `0.0.0.0` 은 아예 못 씁니다 — 같은 사무실 망에서
-  아무나 내 소스를 읽게 됩니다.
-- 포트는 **0**(커널이 빈 것을 줍니다). 고정 포트는 남이 쓰던 것을 뺏습니다.
-- 경로는 작업 범위 밖으로 못 나갑니다. `../` · `%2e%2e` · 두 번 인코딩 · 절대 경로 ·
-  널바이트 · 심볼릭 링크 — 여덟 가지를 검사로 막아 뒀습니다.
-- **주기만 합니다.** `POST` · `PUT` · `DELETE` 는 405 로 거절합니다.
-- `deel` 을 끝내면 같이 꺼집니다.
-## 스킬·플러그인
-**남의 스킬은 품고 다니지 않습니다.** 켜질 때 그 PC 를 훑어 있는 것을 그대로 씁니다.
-**다만 일하는 방법 일곱 가지는 품고 다닙니다.** 사내에서 새로 받은 PC 에는
-`~/.claude/skills` 도 플러그인도 없습니다. 거기서는 방법론이 0개라 모델이 매번
-제 나름대로 했고, 시킨 것만 겨우 하고 끝나는 얄팍한 결과가 거기서 나왔습니다.
-| 스킬 | 언제 |
-|---|---|
-| `깊이있게-만들기` | 고도화·보고용·선포용 — 최소치만 내고 끝내지 않게 |
-| `끝까지-하기` | 시킨 것이 여러 조각일 때. 빼먹은 것은 말하게 |
-| `차근차근-디버깅` | 재현 → 좁히기 → 원인 → 고치기 → 증명 |
-| `검사-먼저` | 고치기 전에 실패하는 검사부터 |
-| `찔러보기` | 되는지 모를 때 시간 정해 작게 찔러 보고 버리기 |
-| `코드-줄이기` | 동작은 그대로 두고 읽기 쉽게 |
-| `스스로-검토` | 다 됐다고 말하기 전에. 못 잰 것까지 말하게 |
-목록으로 늘 나가는 몫은 354토큰입니다(8k 창의 4%). 본문은 `Skill` 로 부를 때만 나갑니다.
-같은 이름을 직접 만들면 그쪽이 이깁니다 — 품고 다니는 것이 제일 낮은 자리입니다.
-```
-품고 다님  (패키지 안)                                    ← 제일 낮은 자리
-프로젝트  ./.deel/skills   ./.claude/skills   ./.deel/commands   ./.claude/commands
-사용자    ~/.deel/skills   ~/.claude/skills   ~/.claude/commands
-플러그인  ~/.claude/plugins/**   ~/.deel/plugins/**
-```
-Claude Code 와 같은 형식(`SKILL.md` + YAML 앞머리, `commands/*.md`, `$ARGUMENTS`)을 읽습니다.
-> **자세히** — 3단계로 나눠 올립니다 · 플러그인 받아 오기 · 안 넣은 것
->
-> **[늘려 쓰기 읽기 →](docs/ko/extend.md#스킬플러그인)**
----
-## 추론 강도
-에이전트 한 번의 대답은 모델을 여러 번 부릅니다. **부를 때마다 필요한 생각의 양이 다릅니다.**
-전부 세게 두면 느리고, 전부 얕게 두면 엉뚱한 길로 갑니다.
-기본은 **한 줄**입니다. 알고 싶은 것은 '지금 얼마나 생각하나' 이지 단계표가 아닙니다.
-```
-$ /think
-  추론 강도  medium   (첫 판단 medium · 이어가기 low · 막혔을 때 high)
-  더 세게 /think high   더 빠르게 /think low
-```
-| 배분 | 성격 |
-|---|---|
-| `even` (균일) | 모든 단계 같은 강도 — 예측 가능한 대신 느림 |
-| `save` (절약, 기본) | 첫 판단만 세게, 이어가기는 얕게 |
-| `deep` (깊게) | 전 단계 한 칸씩 위로 — 어려운 일에만 |
-배분은 `/think 배분 절약` 로 정합니다. **강도와 배분은 다른 축이라 명령을 갈랐습니다** —
-전에는 `/think high` 와 `/think save` 가 같은 이름으로 다른 것을 정해서,
-화면을 봐도 지금 무엇이 무엇인지 읽히지 않았습니다.
-단계표는 `/think 자세히` 로 뺐습니다(개발자 수준 기본).
-```
-$ /think 자세히
-  추론 강도  medium   (첫 판단 medium · 이어가기 low · 막혔을 때 high)
-  배분      절약   첫 판단만 세게, 이어가기는 얕게 — 대개 이게 낫습니다
-  단계        강도      출력상한  언제
-  첫 판단     · medium      15,549  무엇을 할지 정하는 자리
-  이어가기    ↓ low         13,605  도구 결과를 읽고 다음 한 수
-  막혔을 때   ↑ high        16,384  직전 도구가 오류를 냄
-  출력 상한은 16,384 (모르는 값이라 기본값) 안에서 나눕니다 — /out
-  컨텍스트 40,960 · 지금 찬 양 2,087
-```
-마지막에서 두 번째 줄이 있는 이유: **세 값이 다 같을 때 그게 고장인지 아닌지**
-이 한 줄로 갈립니다. 아는 상한이 낮으면 셋이 같아지는 것이 맞습니다.
-한동안 이 표는 세 줄이 늘 `16,384` 였고, 그건 표가 뜻이 없다는 뜻이었습니다.
-> **자세히** — 컨텍스트 길이는 모델에서 긁어옵니다 · /out · 잘린 도구 호출
->
-> **[속도와 씀씀이 읽기 →](docs/ko/tuning.md#추론-강도)**
----
-## 자동 압축
-컨텍스트가 80% 차면 앞선 대화를 **요약해서 접고 계속 이어 갑니다.**
-그냥 잘라내면 모델이 하던 일을 잊고, 파일을 다시 읽고, 이미 고친 곳을 또 고칩니다.
-```
-  ◱ 대화 44개를 요약으로 접었습니다 — 10,399 → 3,170 토큰 (70% 줄어듦)
-```
-요약은 목표 / 한 일 / 알아낸 것 / 정한 것 / 남은 일 다섯 항목으로 남습니다.
-접을 때 **도구 호출과 그 결과가 갈라지지 않는 자리**를 골라 자릅니다 — 갈라지면 서버가 400 을 냅니다.
-요약 요청이 실패하면 옛 방식(그냥 줄이기)으로 물러서고 멈추지 않습니다.
-`/compact` 로 직접 접을 수도 있습니다.
----
-## 대화 이어하기
-터미널을 실수로 닫거나 컴퓨터가 재부팅돼도 하던 대화를 그대로 이어 받습니다.
-오간 내용은 **메시지 하나가 끝날 때마다 바로** `.deel/sessions/` 에 적히기 때문에,
-도중에 죽어도 그 직전까지는 남습니다.
-```
-$ deel sessions
-── 이 폴더의 대화 ──────────────────────────────────────────────
-  ● 20260824-090200  방금        1턴  devstral-small-2507
-      테스트 깨진 거 고쳐줘
-  · 20260824-084500  2시간 전     2턴  qwen2.5-coder:7b
-      src/a.js 의 로그를 logger 로 바꿔줘
-```
-| 명령 | 하는 일 |
-|---|---|
-| `deel --continue` | 이 폴더에서 가장 최근 대화 이어하기 |
-| `deel --resume <id>` | 골라서 이어하기 |
-| `deel sessions` | 남아 있는 대화 목록 |
-| `deel sessions --rm <id>` | 하나 지우기 |
-한 줄에 메시지 하나씩 쓰는 `jsonl` 이라, 쓰다가 전원이 나가도 마지막 줄만 잃습니다.
-이어받은 대화는 도구 호출과 그 결과의 짝까지 그대로 살아 있어 바로 이어서 일할 수 있습니다.
-30일이 지나고 최근 30개 밖인 것은 자동으로 정리합니다.
-저장 위치는 작업 폴더의 `.deel/sessions/` 이고, `.gitignore` 에 `.deel/` 이 들어 있어
-깃에 올라가지 않습니다.
----
-## 밖에서 도구 붙이기 (MCP)
-사내 위키 검색기, 이슈 트래커, DB 조회기 같은 것을 각 팀이 MCP 서버로 만들어 두면
-deel 은 그걸 **코드를 안 고치고** 도구로 씁니다.
-`.deel/mcp.json` 에 적습니다. Claude Code 설정을 그대로 복사해 붙일 수 있습니다:
-```json
-{ "mcpServers": { "사내위키": { "command": "node", "args": ["wiki-mcp.js"] } } }
-```
-모델에게는 `mcp__사내위키__검색` 이라는 이름으로 보입니다. `/mcp` 로 무엇이 붙었는지 봅니다.
-**의존성은 그대로 0 입니다.** stdio 규격은 자식 프로세스의 stdin/stdout 에 줄 단위
-JSON-RPC 2.0 을 주고받는 것이 전부라, `child_process` 와 `JSON` 이면 됩니다. SDK 가
-필요 없습니다.
-> **자세히** — 다만 이건 남의 프로그램입니다
->
-> **[늘려 쓰기 읽기 →](docs/ko/extend.md#밖에서-도구-붙이기-mcp)**
----
-## 에디터 안에서 쓰기 (ACP)
-터미널을 하나 더 띄우게 하는 도구는 두 주쯤 뒤에 안 씁니다. 개발자는 하루 종일
-IDE 안에 있습니다. 그래서 **ACP**(Agent Client Protocol)를 지킵니다 — Zed ·
-JetBrains · Neovim · Emacs 가 **저쪽을 한 줄도 안 고치고** deel 을 붙입니다.
-에디터 설정에 이 명령 하나만 적으면 됩니다.
-```
-deel acp
-```
-에디터가 이걸 자식 프로세스로 띄우고, 표준입출력으로 줄 단위 JSON-RPC 2.0 을
-주고받습니다. 사람이 직접 칠 명령은 아닙니다.
-**붙으면 이렇게 됩니다.**
-| 에디터 쪽 | deel 쪽 |
-|---|---|
-| 답이 흘러나오는 자리 | 모델이 흘리는 글 · 생각 |
-| 도구 목록 (아이콘·상태) | `Read` 는 읽기, `Edit` 는 고치기, `Bash` 는 실행 — **갈래를 붙여** 보냅니다 |
-| 파일 링크 | 고친 파일의 **절대 경로**. 눌러서 그 자리로 갑니다 |
-| 승인 창 | deel 의 안전망이 그대로 에디터 창으로 뜹니다 (`이번만` · `앞으로 묻지 않기` · `안 함`) |
-| 모드 고르개 | deel 의 작업 모드 7개 (`종합` · `코드` · `계획` · `설계` · `디버그` · `묻기` · `총괄`) |
-| 멈춤 단추 | 도중에 닿습니다 — 답을 기다리는 중에도 |
-**의존성은 그대로 0 입니다.** MCP 와 같은 이유입니다 — 줄 단위 JSON-RPC 2.0 이
-전부라 SDK 가 필요 없습니다.
-> **자세히** — 조용히 깨지는 자리들
->
-> **[늘려 쓰기 읽기 →](docs/ko/extend.md#에디터-안에서-쓰기-acp)**
----
-## 비밀이 새지 않게
-사람이 열쇠를 붙여 넣는 일은 드뭅니다. 새는 자리는 거의 항상 **명령 출력**입니다.
-```
-env                  OPENAI_API_KEY=sk-proj-…
-git remote -v        https://사람:토큰@github.com/…
-curl -v              > Authorization: Bearer eyJ…
-검사 실패 로그         연결 문자열이 통째로
-```
-그 글은 모델에게 실려 가고, **동시에** `.deel/sessions/*.jsonl` 로 디스크에
-적힙니다. 그 파일은 나중에 `/recall` 로 다시 읽히고 `deel pack` 에 딸려 갈 수도
-있습니다. 한 번 새면 여러 벌이 됩니다.
-그래서 도구 결과가 대화로 들어가는 **한 자리**에서 가립니다.
-```
-  ⏺ Bash(env | grep API)  완료
-    ⊘ 비밀로 보이는 값 2군데가 대화에 들어갔습니다 (openai · 환경변수) — 모델에 가려서 보냈습니다
-```
-찾는 것: 사설키 블록 · OpenAI/Anthropic 열쇠 · GitHub 토큰 · Slack 토큰 ·
-AWS 키 · Google 키 · JWT · 주소에 박힌 열쇠 · `Authorization` 계열 헤더 ·
-이름이 `…KEY`/`…TOKEN`/`…SECRET`/`…PASSWORD` 인 환경변수. 그리고 **설정에 든
-게이트웨이 열쇠는 모양과 상관없이** — 그건 짐작이 아니라 아는 값이니까요.
-### 파일 내용은 일부러 안 가립니다
-가리고 싶은 마음이 제일 드는 자리가 `.env` 인데, 거기를 가리면 이렇게 됩니다 —
-모델이 가려진 글을 보고, 그걸 고쳐서 되돌려 씁니다. 그러면 진짜 열쇠가 있던
-자리에 `«가림»` 이 적힙니다. **비밀을 지키려다 사람의 열쇠를 우리 손으로
-지우는 셈입니다.**
-그래서 파일 쪽은 가리는 대신 **알립니다.**
-```
-  ⏺ Read(.env)  12줄
-    ! 비밀로 보이는 값 3군데가 대화에 들어갔습니다 (환경변수)
-      — 파일 내용은 가리지 않습니다 (가리면 되돌려 쓸 때 지워집니다)
-```
-무엇을 못 막는지 분명히 말하는 편이, 막았다고 해 놓고 파일을 망가뜨리는 것보다
-언제나 낫습니다. 어느 쪽이든 감사기록에 남습니다.
----
-## 안전망
-승인 프롬프트 대신 **되돌릴 수 있게** 만들었습니다. 기본 모드 `auto` 는 묻지 않고 알아서 합니다.
-| 장치 | 내용 |
-|---|---|
-| **되돌리기** | 파일을 고치기 전 항상 스냅샷. `/undo` 로 턴 단위 복구. **`Bash` 로 옮기고 지우는 것도 포함** |
-| **바뀐 자리 보기** | 고칠 때마다 바뀐 줄을 화면에. 이번 대화 전체는 `/diff` |
-| **작업 범위** | 시작한 폴더 밖은 모델이 시켜도 거부 |
-| **위험 명령 차단** | 되돌릴 수 없는 것만 (디스크 포맷, 재귀 삭제, `--force` 푸시 등) |
-| **재실행 금지** | 변경성 명령은 실패해도 다시 실행하지 않음 — 두 번 돌면 사고 |
-| **중단** | Ctrl+C 로 도중에 끊어도 대화가 성한 채로 남음 |
-| **헛돌기 차단** | 같은 도구가 같은 이유로 3번 실패하면 그 턴을 멈추고 왜인지 말함 |
-| **안 읽는 자리** | 남의 도구 살림과 deel 자신의 기록·설정(열쇠)은 거절 |
-| **감사 로그** | `.deel/audit.jsonl` 에 전부 기록 |
-| 모드 | 언제 물어보나 |
-|---|---|
-| `auto` (기본) | 안 물어봄. 되돌리기가 안전망 |
-| `confirm` | 되돌릴 수 없는 명령만 |
-| `strict` | 파일 변경·명령 전부 |
-되돌리기 이력은 파일 내용을 통째로 담기 때문에 큰 파일을 여러 번 고치면 금방 커집니다.
-32MB 를 넘으면 **최근 50턴만 남기고** 오래된 것을 버립니다. 방금 한 일은 언제나
-되돌릴 수 있고, 지금 이력이 얼마나 되는지는 `/status` 에서 봅니다.
-> **자세히** — Bash 로 사라진 것도 되돌아갑니다 · 안 읽는 자리
->
-> **[안전망과 사내 반입 읽기 →](docs/ko/safety.md#안전망)**
----
-## 사내 반입
-심사서와 소스를 zip 하나로 묶습니다.
-```bash
-deel pack --out deel-반입.zip
-```
-```
-── 반입 묶음 ───────────────────────────────────────────────────
-  ✓ deel-반입.zip
-     94개 파일 · 509.6KB
-  의존성          0개
-  설치 스크립트   없음
-  외부 import     0건
-  네트워크 호출   3곳 (설정한 주소로만)
-  포트 열기       1곳 (/preview 만)
-```
-zip 안에는 **사람이 읽을 것 한 장, 기계가 읽을 것 두 장**이 같이 들어갑니다.
-반입 심사는 사람만 보는 절차가 아니기 때문입니다 — 보안팀은 SBOM 을 스캐너에
-먹여 취약점 목록을 뽑고, 운영팀은 감사 사양을 보고 SIEM 수집 규칙을 짭니다.
-| 파일 | 무엇 |
-|---|---|
-| `반입심사서.txt` | 의존성 · 설치 스크립트 · **소스를 훑어 찾은 네트워크·외부 명령 호출 자리 전부**(파일:줄) · 나가는 길 세 갈래 · 파일별 SHA-256 |
-| `sbom.cdx.json` | **SBOM (CycloneDX 1.5).** 스캐너에 그대로 넣습니다. 파일마다 부품 하나에 SHA-256, 의존성은 **빈 배열로 명시** — 안 적어 낸 것과 없는 것은 다릅니다 |
-| `심사명세.json` | 통신 목록(갈래마다 언제·어디로·무엇이·막는법·소스 자리) · **감사기록 사양**(칸 이름과 뜻, 안 남기는 것) · 파일 해시 |
-```bash
-deel audit                    # 사람이 읽는 심사서만 보기
-deel sbom                     # 기계가 읽는 두 장을 표준출력으로 (deel sbom | jq)
-deel sbom --out 심사.json     # 파일로
-deel sbom --only sbom         # SBOM 한 장만
-```
-셋 다 손으로 적지 않고 코드가 소스를 훑어서 만듭니다 — 손으로 적으면 언젠가
-사실과 어긋나고, **어긋난 심사 서류는 없느니만 못합니다.** 담당자가 한 번 틀린
-것을 발견하면 나머지도 안 믿습니다. 감사기록 사양만은 손으로 적혀 있어서,
-그것이 진짜 기록과 어긋나지 않는지를 검사가 매번 대조합니다.
-> **자세히** — 사내 게이트웨이 진단
->
-> **[안전망과 사내 반입 읽기 →](docs/ko/safety.md#사내-반입)**
----
-## 설정
-`~/.deel/config.json` 에 저장됩니다. 프로젝트 폴더에 `.deel/config.json` 이 있으면 그쪽이 우선입니다.
-> **자세히** — 붙는 서버 · 환경변수 · 실행 옵션 · 프로젝트 규칙
->
-> **[설정 읽기 →](docs/ko/config.md#설정)**
----
-## 문제 해결
-| 증상 | 확인할 것 |
-|---|---|
-| `주소를 찾을 수 없습니다` | 주소 오타, DNS, 사내망 접속 여부 |
-| `연결이 거부되었습니다` | 서버가 꺼져 있거나 포트가 다름 |
-| `인증서 문제` | `set NODE_EXTRA_CA_CERTS=C:\경로\사내CA.pem` |
-| 프록시를 거쳐야 함 | `set HTTPS_PROXY=http://프록시:포트` |
-| 401 / 403 | 키가 틀렸거나 인증 헤더 형식이 다름 (4가지를 자동 시도합니다) |
-| `허용되지 않은 주소입니다` | 자물쇠가 막은 것. 정상입니다 — `/model` 로 연결을 고르세요 |
-| 도구 호출이 안 먹음 | `deel diagnose` 로 판정을 보세요. 작은 모델(1B~3B)은 자주 못 합니다 |
-| 대답이 비어 있음 | 스트리밍을 무시하는 서버입니다. 한 번은 저절로 다시 부르고, 그래도 비면 이 대화에서는 스트리밍을 끕니다 |
-| 큰 파일이 중간에 끊김 | `/out` 으로 지금 상한을 보고 올리세요. 상한을 몰라 16,384 로 서 있을 수 있습니다 |
-| `HTTP 400` 만 뜸 | 서버가 보낸 문장을 그대로 보여 줍니다. 길이 문제면 숫자를 읽어 저절로 맞춥니다 |
-| `deel scan` 이 0곳 | 로컬 서버가 꺼져 있거나 다른 포트 — `--ports` 로 지정 |
----
-## 개발
-```bash
-npm test          전체 검증 (1,832항목)
-npm run coverage  검사가 소스의 어디를 밟았는지
-npm run verify    반입·통신 검증만
-npm run bench     편집 성공률 측정
-npm run demo      화면이 어떻게 보이는지 실제로 돌려 보기
-npm run check     전 파일 문법 검사
-```
-검증은 **가짜 게이트웨이**를 띄워서 합니다. 실제 모델 없이 규격 그대로
-루프·스트리밍·도구 실행·되돌리기·압축을 결정적으로 확인합니다.
-zip 은 진짜 `unzip` 으로, tar 는 진짜 `tar` 가 만든 것을 읽혀 교차 확인합니다.
-`npm test` 는 파일을 하나씩 돌리고 **파일별 종료코드**를 표로 남깁니다.
-화면의 통과 표시가 아니라 종료코드가 CI 가 보는 값이기 때문입니다. 둘은
-갈라질 수 있습니다 — 검사를 다 통과하고도 끝낼 때 죽으면 화면은 초록인데
-종료코드는 1 입니다. 실제로 윈도우에서 그렇게 한 번 놓쳤습니다.
-첫 실패에서 멈추지 않고 끝까지 돌기 때문에, 한 번 돌리면 전부 알 수 있습니다.
-```
-  ────────────────────────────────────────────────────────────
-  검사 파일              종료코드   통과   실패   시간
-  ────────────────────────────────────────────────────────────
-  ✓ smoke.js            0            20     0     0.2초
-  ✗ scan.test.js        1            19     0     0.2초
-  ────────────────────────────────────────────────────────────
-  ✗ scan.test.js — 종료코드 1
-     검사는 전부 통과했는데 종료코드만 1 입니다 —
-     끝낼 때 남은 핸들·처리 안 된 거절 때문입니다.
-```
-| 검증 | 항목 | 무엇을 |
-|---|---|---|
-| `smoke` | 20 | 도구·작업범위·되돌리기·감사로그 |
-| `loop` | 16 | 에이전트 루프·스트리밍·도구 호출 |
-| `guard` | 24 | **안 하는 자리** — 거부·모르는 도구·두 번 실행·범위 밖 |
-| `network` | 30 | 정해진 자리 밖으로 새지 않는가 |
-| `web` | 25 | 웹 읽기가 읽기만 하는가 |
-| `abort` | 16 | Ctrl+C 로 끊어도 대화가 성한가 |
-| `parallel` | 23 | 읽기만 동시에 도는가 · 할 일 목록 |
-| `cli` | 75 | **진짜 `deel` 을 띄워** 끝까지 돌려 본다 |
-| `setup` | 42 | 첫 실행 마법사 (가짜 TTY 로 사람처럼 입력) |
-| `detect` | 66 | 주소 한 줄로 규격·인증을 짚어내는가 |
-| `modes` · `route` | 89 · 33 | 작업 모드 · 종합에서 알맞은 모드로 옮겨 가는가 |
-| `ctxsize` | 43 | 모델에 걸린 컨텍스트 길이를 긁어오는가 |
-| `commands` · `commands-more` | 128 · 62 | 슬래시 명령 전부 |
-| `ui` · `ui2` | 60 · 40 | 암호 가림·한글 폭·상태줄·대화 목록·엑셀→글 |
-| `encoding` · `xlsx` | 68 · 72 | 한글 인코딩 판별 · 엑셀 읽기 |
-| `compact` | 21 | 요약 압축·짝 안 깨짐·실패 시 물러섬 |
-| `store` | 34 | 대화 저장·이어하기·중간에 죽어도 복구 |
-| `scan` | 29 | 여러 런타임을 구분해 찾는가 |
-| `plugins` | 38 | 플러그인 받기·묶기·ZIP/TAR |
-| `no-bundle` | 12 | 배포 묶음에 남의 것이 안 섞였는가 · 검사 파일 위생 |
-| `edit-bench` | 20건 | 편집 성공률 |
-> **자세히** — 어디를 밟았는지 · 폴더 구조
->
-> **[개발 읽기 →](docs/ko/develop.md#개발)**
----
-## 릴리스 노트
-| 판 | 무엇이 바뀌었나 |
-|---|---|
-| **[1.4.2](docs/ko/releases.md#142)** | 1.4.1 이 보안 수정 전에 나갔다 — 그걸 바로잡는 판 |
-| [1.4.1](docs/ko/releases.md#141) | 새 기능 없이, 실제로 찾은 것만 고친다 — 윈도우 abort·ReDoS·XSS |
-| [1.4.0](docs/ko/releases.md#140) | deel 이 제 얼굴을 갖고, 영어로도 말하고, 뜻까지 본다 — 열한 자리 |
-| [1.3.0](docs/ko/releases.md#130) | 말 대신 증거, 터미널 대신 에디터 — 여섯 자리 |
-| [1.2.0](docs/ko/releases.md#120) | 대화가 끊기지 않게 — 여섯 자리 |
-무엇이 왜 바뀌었는지는 **[릴리스 노트](docs/ko/releases.md)** 에 있습니다.
----
-## 라이선스
-[MIT](LICENSE)
+<div align="center">
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/hero-ko-dark.svg">
+  <img alt="deel — 이 컴퓨터 안에서만" src="docs/assets/hero-ko-light.svg" width="620">
+</picture>
+### 로컬 모델과 사내 게이트웨이만으로 도는 코딩 에이전트 CLI
+의존성 0개 · Node 20+ · 소스가 나가는 자리는 딱 한 곳
+<br>
+[![npm](https://img.shields.io/npm/v/deel-local-cli?logo=npm&logoColor=white&label=npm&color=cb3837)](https://www.npmjs.com/package/deel-local-cli)
+[![downloads](https://img.shields.io/npm/dt/deel-local-cli?label=downloads&color=1a7f37)](https://www.npmjs.com/package/deel-local-cli)
+[![node](https://img.shields.io/node/v/deel-local-cli?logo=nodedotjs&logoColor=white&label=node&color=5FA04E)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/deel-local-cli?label=license&color=0969da)](LICENSE)
+[![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-3%2C498%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)
+[![network](https://img.shields.io/badge/network-127.0.0.1%20only-1a7f37?logo=wireguard&logoColor=white)](#데이터가-나가는-길)
+[![telemetry](https://img.shields.io/badge/telemetry-none-1a7f37?logo=ghostery&logoColor=white)](#데이터가-나가는-길)
+**[English](README.en.md)** · [사내 반입 안내](#사내-반입) · [문제 해결](#문제-해결) · [자세한 문서](docs/ko/)
+</div>
+---
+```
+ ╭──────────────────────────────────────────────────────────────╮
+ │ deel  OpenAI 호환 규격                                        │
+ │                                                              │
+ │ 모델    qwen2.5-coder:7b  (40k 토큰)                          │
+ │ 보냄    이 컴퓨터 안 127.0.0.1:11434  ← 여기 말고는 어디로도 안 갑니다  │
+ │ 연결    스트리밍 · 도구 · 추론 조절                              │
+ │ 폴더    C:\work\myproject                                     │
+ │ 승인    ⏵⏵ 자동 승인  — 안 묻고 고칩니다. 되돌리기(/undo)가 안전망입니다 │
+ │         Shift+Tab 으로 바꿉니다  ·  Tab 은 치던 / 명령을 채웁니다   │
+ │ 이 PC   스킬 337 · 명령 127 · 플러그인 42                       │
+ ╰──────────────────────────────────────────────────────────────╯
+ /help 명령 목록   /think 추론 강도   Ctrl+C 중단·끝내기
+ ▏myproject · qwen2.5-coder:7b ▏ ▰▰▱▱▱▱▱▱▱▱ 22% 28k/128k ▏ ◎ 종합 · ◇ medium·절약 · ⏵⏵ 자동
+ ❯ 로그 형식 통일해줘
+  ❊ Grep(console.log)
+    └ 1개 파일 · 1건
+  ◧ Read(src/runner.js)
+    └ 5줄
+  ◈ Edit(src/runner.js)
+    └ 1군데
+  ▌ 로그 호출을 logger 형식으로 통일했습니다. runner.js 한 군데를 고쳤습니다.
+  ── 4.2초 · 도구 3회 · ↑3,900 ↓180
+```
+---
+## 목차
+- [왜 만들었나](#왜-만들었나)
+- [무엇이 다른가](#무엇이-다른가)
+- [빠른 시작](#빠른-시작)
+- [데이터가 나가는 길](#데이터가-나가는-길)
+- [로컬 모델 여러 개 쓰기](#로컬-모델-여러-개-쓰기)
+- [대화 중 명령](#대화-중-명령)
+- [작업 모드](#작업-모드)
+- [쉬움 · 개발자](#쉬움--개발자)
+- [도구](#도구)
+- [한글 문서와 엑셀](#한글-문서와-엑셀)
+- [만든 웹을 그 자리에서 띄웁니다](#만든-웹을-그-자리에서-띄웁니다)
+- [스킬·플러그인](#스킬플러그인)
+- [추론 강도](#추론-강도)
+- [자동 압축](#자동-압축)
+- [대화 이어하기](#대화-이어하기)
+- [밖에서 도구 붙이기 (MCP)](#밖에서-도구-붙이기-mcp)
+- [에디터 안에서 쓰기 (ACP)](#에디터-안에서-쓰기-acp)
+- [비밀이 새지 않게](#비밀이-새지-않게)
+- [안전망](#안전망)
+- [사내 반입](#사내-반입)
+- [설정](#설정)
+- [문제 해결](#문제-해결)
+- [개발](#개발)
+- [릴리스 노트](#릴리스-노트)
+여기는 **요약**입니다. 절마다 붙은 링크를 따라가면 그 안의 이야기가 나옵니다.
+| 자세한 문서 | 무엇이 있나 |
+|---|---|
+| [모델 다루기](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 · 인코딩 · 엑셀 → 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.5.0](docs/ko/releases.md#150) · [1.4.3](docs/ko/releases.md#143) · [1.4.2](docs/ko/releases.md#142) · [1.4.1](docs/ko/releases.md#141) · [1.4.0](docs/ko/releases.md#140) · [1.3.0](docs/ko/releases.md#130) · [1.2.0](docs/ko/releases.md#120) |
+---
+## 왜 만들었나
+사내 보안 정책이 **미승인 소프트웨어 반입**을 막으면, 코딩 에이전트 도구는 대부분 쓸 수 없습니다.
+의존성 수백 개가 딸려 오고, 설치할 때 스크립트가 돌고, 어디로 통신하는지 한 줄로 답할 수 없기 때문입니다.
+deel 은 그 심사를 통과하는 것을 목표로 만들었습니다.
+| | deel |
+|---|---|
+| 외부 의존성 | **0개** — Node 내장 기능만 |
+| 설치 스크립트 | **없음** — 압축 풀고 바로 실행 |
+| 소스가 나가는 자리 | **딱 한 곳** — 직접 설정한 주소 |
+| 필요한 것 | Node 20 이상 |
+직접 확인하실 수 있습니다.
+```bash
+npm view deel-local-cli dependencies   # {}
+npm view deel-local-cli scripts        # install/postinstall 없음
+deel audit                             # 심사서 전문 출력
+```
+---
+## 무엇이 다른가
+로컬 모델을 상대하는 코딩 에이전트는 몇 개 있습니다. 그런데 **로컬로 돌리는
+걸 전제로 속을 다시 설계한** 것은 드뭅니다.
+| | 다른 도구 | deel |
+|---|---|---|
+| `/undo` | 파일만 되돌린다 — 대화는 그 일이 있었다고 믿는 채로 | **대화까지** 같이 되감는다 |
+| 긴 대화 | 클라우드가 안 느끼는 비용을 로컬에서도 그대로 짊어진다 | 프리픽스 캐시가 **살아남게** 순서를 설계 |
+| 작은 모델의 편집 | 공백 하나 틀려도 실패 | 성공률 20%→**100%**, 엉뚱한 곳 0건 |
+| 국산 모델 | 겪어 보기 전엔 모른다 | 공개 문서로 **미리** 안다 |
+| "다 됐습니다" | 확인 안 된 것도 됐다고 한다 | `/evidence`·`/export` — **안 된 것까지** 적는다 |
+| MCP·ACP | SDK 가 필요하다 | `child_process` + `JSON` 뿐 |
+| 심사 서류 | 사람이 손으로 써서 실제와 어긋난다 | **코드가 소스를 훑어서** 만든다 |
+<br>
+#### `/undo` 는 파일과 대화를 같이 되감습니다
+파일만 되돌리면 모델은 방금 그 편집을 했다고 계속 믿고 다음 턴을 그 위에
+쌓습니다 — 화면에는 아무 일도 없었던 것처럼 보입니다. deel 은 되돌린 만큼
+오간 메시지도 같이 접습니다. 접다가 도구 호출의 짝이 어긋나면 API 가 400 을
+내므로, 짝을 다시 맞추는 로직(`repairToolPairs`)까지 같이 돕니다.
+#### 긴 대화에서 로컬 모델이 갈수록 느려지는 이유를 직접 잡았습니다
+Ollama·llama.cpp 는 프롬프트 앞부분이 한 글자라도 바뀌면 그 뒤 전부를 다시
+계산합니다. 클라우드 API 는 이 비용을 안 느끼니 신경 쓸 이유가 없지만,
+로컬로 돌리는 사람에게는 대화가 길어질수록 턴마다 지연이 쌓입니다. deel 은
+매 턴 바뀔 수 있는 것(모드·핀)을 프롬프트 **맨 끝**으로 보내고, Ollama 에는
+`keep_alive: 60m` 을 같이 보내 앞부분이 캐시에 그대로 남게 합니다. 이 순서는
+검사(`test/cache.test.js`)가 지킵니다.
+#### 작은 모델도 편집이 실제로 성공합니다
+작은 로컬 모델은 고치려는 문자열을 공백 하나까지 완벽히 재현하지 못하는
+경우가 흔합니다. `npm run bench` 로 잰 내부 벤치마크에서, 정확히 일치만
+요구하던 옛 방식은 성공률 20% 였습니다. 지금 방식(공백·들여쓰기를 단계적으로
+완화)은 **100%** — 그러면서도 엉뚱한 곳을 고친 건수는 두 방식 다 **0건**
+입니다. 모호하면 찾지 못했다고 말할지언정 짐작해서 고치지 않습니다.
+#### 국산 모델은 겪어 보기 전에 압니다
+EXAONE·HyperCLOVA X·Kanana·Midm·Solar 는 공개 문서로 확인 가능한 버릇(예:
+추론형 여부)을 deel 이 미리 알고 시작합니다. 다른 도구는 이 모델들을 한
+번도 못 만나 본 채로 취급하고, 사람이 열 몇 턴을 겪어야 요령이 붙습니다.
+#### "다 됐습니다" 대신 증명서를 냅니다
+`/evidence` 와 `/export` 는 무엇을 바꿨는지뿐 아니라 **무엇을 확인하지
+못했는지**까지 적습니다. AI 코딩 도구가 사람을 제일 잘 속이는 순간이 자신
+있게 "됐습니다" 라고 말할 때라는 걸 알기 때문입니다. `/export` 는 바깥
+주소가 하나도 없는 자기완결 HTML 이라 폐쇄망 어디서든 열립니다.
+#### MCP·ACP 를 SDK 없이 붙였습니다
+Model Context Protocol 과 Agent Client Protocol 은 둘 다 표준입출력으로 줄
+단위 JSON-RPC 2.0 을 주고받는 게 전부입니다. deel 은 `child_process` 와
+`JSON` 만으로 둘 다 구현했습니다 — 의존성 0개가 "기능을 뺀 결과" 가 아니라
+"안 필요해서" 라는 걸 이 두 가지가 보여 줍니다.
+#### 심사 서류를 손으로 안 씁니다
+`deel pack` 이 만드는 반입심사서·SBOM·감사 사양은 **코드가 소스를 훑어서**
+만든 겁니다. 손으로 적은 서류는 언젠가 실제와 어긋나고, 담당자가 그걸 한 번
+발견하면 나머지 서류도 안 믿습니다.
+---
+## 빠른 시작
+### 설치
+```bash
+npm install -g deel-local-cli
+```
+설치가 싫으면 소스를 받아 그대로 쓰셔도 됩니다. `npm install` 이 필요 없습니다.
+```bash
+git clone https://github.com/jysvai/deel-local-cli
+node deel-local-cli/bin/deel.js
+```
+> **주의** — 홈 디렉터리(`~`)에서 `npm install` 하지 마세요. 거기에 `node_modules` 가 생기면
+> 이후 모든 npm 명령이 그 폴더를 훑어서 무관한 패키지 경고를 냅니다. `-g` 로 설치하거나 `npx` 를 쓰세요.
+### 연결 정하기
+이 PC 에 떠 있는 로컬 서버를 훑어서 고르는 방법:
+```bash
+deel scan --pick
+```
+주소를 직접 넣는 방법 (사내 게이트웨이는 이쪽):
+```bash
+deel setup
+```
+### 시작
+작업할 폴더에서 `deel` 을 칩니다. **그 폴더가 작업 범위가 되고, 밖의 파일은 읽지도 쓰지도 못합니다.**
+```bash
+cd C:\work\myproject
+deel
+```
+---
+## 데이터가 나가는 길
+코딩 에이전트는 소스 코드를 통째로 모델에 보냅니다. **그 주소가 어디인지가 전부입니다.**
+말로 보장하는 대신 코드가 막습니다 — `src/safety/network.js` 가 요청마다 확인하고,
+허용 목록에 없으면 요청을 만들지도 않습니다.
+```
+ [A] 모델 게이트웨이 ─── 소스 코드가 나가는 유일한 길
+     setup 에서 정한 한 자리만. 모델을 바꾸면 이전 자리는 닫힙니다.
+ [B] 웹 읽기 (WebFetch) ─ 받아 오기만 하는 길
+     GET 만. 본문 0바이트. 사내망·로컬 주소는 거절. 다녀온 곳은 전부 기록.
+ [C] 플러그인 받기 ────── /plugin install 을 칠 때만 잠깐
+ [D] MCP 서버 ─────────── 딴 자식 프로세스, 남의 프로그램
+     .deel/mcp.json 에 사람이 직접 적어야만 뜹니다. 기본은 꺼져 있습니다.
+```
+A·B·C 는 deel 이 직접 만드는 요청이라 하나씩 걸러낼 수 있습니다. **[D] 는
+다릅니다** — MCP 서버는 별도 프로세스라 그 안에서 무슨 소켓을 여는지 코드로
+볼 수 없습니다. 그래서 `--offline` 일 때는 요청을 거르는 대신 **그 서버
+자체를 아예 띄우지 않습니다** — 막을 수 없는 것을 막았다고 말하지 않습니다.
+`--offline` 을 주면 **B·C·D 가 모두 막히고 이 컴퓨터 안으로만** 다닙니다.
+```bash
+deel --offline
+```
+무엇이 어디로 갈 수 있는지는 켤 때 화면 맨 위에 늘 적혀 있습니다.
+```
+ 보냄    이 컴퓨터 안 127.0.0.1:11434  ← 여기 말고는 어디로도 안 갑니다
+```
+수집·전송하는 것이 없습니다. 텔레메트리, 사용 통계, 오류 보고 전부 없습니다.
+대화 기록·되돌리기 이력·설정은 작업 폴더의 `.deel/` 안에만 남습니다.
+> 검증: `npm test` 의 network·web·mcp 검사 123항목. 허용되지 않은 서버에 실제로
+> 요청이 **한 건도 닿지 않는지**, `--offline` 일 때 MCP 서버가 **한 번도 안
+> 뜨는지**까지 진짜 서버를 띄워서 확인합니다.
+---
+## 로컬 모델 여러 개 쓰기
+로컬 런타임은 보통 하나만 쓰지 않습니다. Ollama 로 작은 모델을 돌리면서
+LM Studio 로 큰 모델을 띄워 두기도 합니다. `deel scan` 이 알려진 자리 13곳을 동시에 두드려
+전부 찾아냅니다.
+```
+$ deel scan
+── 로컬 모델 서버 훑기 ───────────────────────────────────────────────
+  127.0.0.1 의 알려진 자리 13곳을 두드립니다. 바깥으로는 나가지 않습니다.
+  ✓ 3곳 찾음
+  ◆ Ollama      127.0.0.1:11434   Ollama 규격   36ms
+      · qwen2.5-coder:7b            7B · 4.4GB
+      · llama3.2:1b                 1B · 1.2GB
+  ◆ LM Studio   127.0.0.1:1234     OpenAI 호환    7ms
+      · devstral-small-2507
+  ◆ llama.cpp   127.0.0.1:8080     OpenAI 호환    7ms
+      · gemma-3-4b-it
+  합계  서버 3곳 · 모델 6개
+  추천  Ollama · qwen2.5-coder:7b
+        코딩용 모델 · 도구 호출을 잘하는 계열
+```
+포트로 단정하지 않고 **응답을 보고** 런타임을 구분합니다 — Ollama 는 `/api/version`,
+LM Studio 는 `/api/v0/models`, llama.cpp 는 `/props`. 못 알아보면 `(추정)` 이라고 밝힙니다.
+| 명령 | 하는 일 |
+|---|---|
+| `deel scan` | 찾아서 보여주기만 |
+| `deel scan --pick` | 목록에서 골라 등록 |
+| `deel scan --save` | 찾은 것 전부 등록 |
+| `deel scan --ports 9000,9100` | 기본 자리 말고 더 볼 포트 |
+| `deel scan --host <주소>` | 기본은 `127.0.0.1` |
+| `deel scan --key <키>` | 키가 필요한 로컬 서버일 때 |
+등록한 뒤에는 대화 중 `/model` 로 갈아탑니다. **대화 내용은 그대로 이어집니다.**
+> **자세히** — 걸린 모델에 맞춰 스스로 바뀝니다 · 국산 모델은 겪기 전에 압니다 · 작은 창에서는 고정 몫을 줄입니다 · 켤 때 이 폴더가 무슨 프로젝트인지 읽습니다
+>
+> **[모델 다루기 읽기 →](docs/ko/models.md#로컬-모델-여러-개-쓰기)**
+---
+## 대화 중 명령
+이름은 Claude Code / Codex 관례에 맞췄습니다.
+| 명령 | 하는 일 |
+|---|---|
+| `/help` | 명령 목록 |
+| `/bell [on|off]` | 다 됐을 때·물어볼 때 종소리와 창 제목 |
+| `/lang [ko|en]` | 화면 말 — 영어권 사람이 쓸 때. 모델이 읽는 글도 같이 따라간다(영어 쪽이 1,400토큰 덜 먹는다). 코드는 그대로 |
+| `/consult <프로필> <질문>` | 다른 모델에게 한 번 물어보기 — 지금 쓰는 것은 안 바꿈 |
+| `/export` | 이 대화를 **보고서 한 장**(HTML)으로 — 시킨 것·바뀐 것·확인한 것. 폐쇄망에서 여는 자기완결 파일 |
+| `/lsp [on\|off]` | 언어 서버 — 무엇이 깔려 있고 `Def`·`Refs` 를 쓸 수 있는지. `off` 는 고친 뒤 진단만 끔 |
+| `/context` | 무엇이 컨텍스트를 먹고 있는지 |
+| `/ctx [auto\|숫자\|자세히]` | 컨텍스트 **길이** — 모델에 맞춰 다시 재거나 직접 지정 |
+| `/out [숫자\|auto]` | 한 번에 받을 **답 길이** 상한 — 큰 파일이 잘리면 여기를 올립니다 |
+| `/grade [작음\|보통\|큼\|auto]` | 모델 **급** — 얼마나 알아서 하나. `/ctx` 와 다른 축입니다 |
+| `/compact` | 앞선 대화를 요약해서 접기 |
+| `/clear` | 대화 비우기 (연결·규칙은 유지) |
+| `/thread [new\|fork\|close\|번호]` | 대화 갈래 — 곁가지를 딴 자리에서. 연결·되돌리기는 같이 씁니다 |
+| `/learned [지우기]` | 쓰면서 저절로 알게 된 것 — 되는 명령·이 모델의 버릇 |
+| `/pin <말>` | 못 박기 — 접거나 요약해도 **안 지워지는** 말 |
+| `/evidence [파일]` | 증거 — 무엇을 바꿨고 무엇이 그걸 증명하나. **안 된 것도** 적습니다 |
+| `/model` | 연결·모델 바꾸기 |
+| `/model 카드` | 이 모델을 겪어 본 결과 — 그래서 deel 이 무엇을 바꿔 뒀는지 |
+| `/think <강도>` | 추론 강도 (`off·low·medium·high·max`) |
+| `/think 배분 <배분>` | 단계별 배분 (`균일·절약·깊게`) |
+| `/think 자세히` | 단계표 — 어느 단계를 어떤 강도·상한으로 도는지 |
+| `/mode <모드>` | 승인 정책 — 얼마나 물어보나 (`auto` · `confirm` · `strict`) |
+| `/work [모드]` | 작업 모드 — 무슨 일을 하는 중인가 |
+| `/auto` | 다시 맡기기 — 말을 보고 알맞은 모드로 저절로 옮겨 갑니다 |
+| `/code` `/plan` `/architect` `/debug` `/ask` `/orchestrator` | 작업 모드 바로 바꾸기 (그때부터 고정) |
+| `/level [수준]` | 화면에 무엇을 내놓을지 (`쉬움` · `개발자`) |
+| `/undo [턴수]` | 파일 변경 되돌리기 |
+| `/diff [파일]` | 이번 대화에서 바뀐 파일 · 바뀐 자리 보기 |
+| `/preview [폴더\|파일\|off]` | 만든 웹을 이 자리에서 띄워 보기 — 브라우저가 같이 열립니다 |
+| `/tools` | 쓸 수 있는 도구 |
+| `/skills [검색어\|all\|off]` | 스킬 보기·검색·골라 올리기 |
+| `/plugin [install\|remove\|pack]` | 플러그인 관리 |
+| `/cost` | 이번 세션 사용량 |
+| `/status` | 연결 상태 |
+| `/scan [save]` | 이 PC 에 떠 있는 로컬 모델 서버 훑기 (`save` 면 바로 등록) |
+| `/sessions` | 이 폴더의 지난 대화 목록 |
+| `/recall <말>` | 지난 대화에서 **내용으로** 찾기 |
+| `/memory` | 대화가 끝나도 남는 기억 — 보기·적기·지우기 |
+| `/mcp` | 밖에서 붙인 도구(MCP) 서버 보기 |
+| `/init` | `DEEL.md` 규칙 파일 만들기 |
+| `/exit` | 끝내기 |
+`/scan` 과 `/sessions` 는 나가지 않고도 씁니다. 로컬 서버를 새로 켰거나 모델을
+바꿔 올렸을 때 `/scan save` → `/model` 두 번이면 대화를 이어둔 채로 갈아탑니다.
+**치지 않고 쓰는 것**
+| 키 | 무엇을 |
+|---|---|
+| `Tab` | 치던 `/` 명령을 채웁니다. 치는 도중에 후보가 상자 아래에 뜹니다 |
+| `Shift+Tab` | 승인 방식 (`⏵⏵ 자동` → `⏵ 위험만` → `⏸ 모두`) |
+| `Ctrl+O` | 작업 모드 (`종합` → `코드` → `계획` → …) |
+| `↑` `↓` | 지난 입력 이력 |
+| `Ctrl+C` | 답하는 중이면 그 답만 끊고, 빈 줄에서 두 번이면 끝냅니다 |
+한글 조합·붙여넣기·`Ctrl+A/E`·백스페이스는 전부 그대로 됩니다.
+> **자세히** — @파일 로 바로 붙이기 · 도중에 멈추기
+>
+> **[화면과 조작 읽기 →](docs/ko/interface.md#대화-중-명령)**
+---
+## 작업 모드
+무슨 일을 하는 중인지에 따라 **줄 수 있는 도구와 추론 설정이 같이 바뀝니다.**
+`Shift+Tab` 으로 차례로 돌리거나, 이름을 그대로 치면 됩니다.
+| 모드 | 하는 일 | 파일을 고치나 | 추론 |
+|---|---|---|---|
+| `/auto` ◎ 종합 | **처음 값.** 말을 보고 알맞은 모드로 옮겨 간다 | 예 | 보통 (`save`) |
+| `/code` ◆ 코드 | 고치고 만든다 | 예 | 보통 (`save`) |
+| `/plan` ☰ 계획 | 먼저 계획만 세운다 | **아니오** | 깊게 (`deep`·high) |
+| `/architect` ◈ 설계 | 구조를 짠다 | **아니오** | 깊게 (`deep`·high) |
+| `/debug` ◉ 디버그 | 원인을 찾는다 | 예 | 깊게 · 단계 많이 (32) |
+| `/ask` ◇ 묻기 | 설명만 한다 | **아니오** | 얕게 (`low`) |
+| `/orchestrator` ❋ 총괄 | 큰 일을 쪼개서 | 예 | 단계 아주 많이 (40) |
+읽기만 하는 모드에서는 `Write`·`Edit`·`Bash` 를 **모델에게 아예 보내지 않습니다.**
+"고치지 마세요" 라고 부탁하지 않습니다 — 모델은 부탁을 잊습니다. 없는 도구는 못 씁니다.
+`/mode` 와 헷갈리지 마세요. 둘은 다른 축입니다.
+- `/mode` — **얼마나 물어보나** (auto · confirm · strict)
+- `/work` — **무슨 일을 하는 중인가** (위 일곱 가지)
+`/think` 나 `/mode` 를 직접 고른 적이 있으면 그 선택이 우선합니다.
+모드가 사람이 고른 값을 덮어쓰지 않습니다.
+> **자세히** — 저절로 옮겨 가기 (종합 모드)
+>
+> **[화면과 조작 읽기 →](docs/ko/interface.md#작업-모드)**
+---
+## 쉬움 · 개발자
+처음 켠 사람에게 명령 스무 개를 들이밀면 아무것도 못 고릅니다.
+그렇다고 기능을 잠그면 쓸 만해졌을 때 막힙니다. 그래서 **보이는 것만** 나눕니다.
+| | 쉬움 (기본) | 개발자 |
+|---|---|---|
+| `/help` 목록 | 자주 쓰는 것만 | 전부 |
+| 오류 문구 | 무엇을 하면 되는지 | 원래 문구 그대로 |
+| 안전 장치 | **똑같음** | **똑같음** |
+`/level 개발자` 로 바꾸면 설정에 남아 다음에 켤 때도 이어집니다.
+중요한 것 두 가지입니다.
+- **감춘 것도 그대로 먹습니다.** 쉬움에서 `/think high` 를 쳐도 됩니다. 목록에 안 띄울 뿐입니다.
+- **초보라고 승인을 덜 받지 않습니다.** 되돌리기·작업 범위·위험 명령 차단은 두 수준이 같습니다.
+  초보일수록 되돌릴 수 있어야 합니다.
+> **자세히** — 입력칸 · 명령은 다 안 쳐도 됩니다 · 일하는 중에는 상자가 그대로 있습니다 · 왼쪽 그림도 같이 움직입니다 외 1개
+>
+> **[화면과 조작 읽기 →](docs/ko/interface.md#쉬움--개발자)**
+---
+## 도구
+이름과 인자를 Claude Code 와 같게 맞췄습니다. 그 관례로 쓰인 스킬·명령이 그대로 먹습니다.
+| 도구 | 하는 일 |
+|---|---|
+| `Read` | 파일 읽기 (줄 번호 · `offset`/`limit` 지원 · **엑셀은 CSV 로, hwpx·docx·pptx 는 글로 바꿔서**) |
+| `Write` | 파일 쓰기·덮어쓰기 (**여러 개는 `files` 배열로 한 번에**) |
+| `Append` | 파일 끝에 이어 붙이기 — **큰 파일을 나눠 쓰는 자리** |
+| `Edit` | 정확한 문자열 바꾸기 (`replace_all` · **여러 군데는 `edits` 배열로 한 번에**) |
+| `Glob` | 이름 패턴으로 파일 찾기 |
+| `Grep` | 내용 정규식 검색 |
+| `Bash` | 명령 실행 (**끝나지 않는 것은 `background: true`**) |
+| `Skill` | 스킬 본문 펼쳐 읽기 (스킬이 있을 때만 모델에게 보임) |
+| `WebFetch` | 웹 페이지 읽기 (읽기 전용 · `--offline` 이면 숨김) |
+| `Recall` | **지난 대화**에서 찾기 — "저번에 그거" 를 모델이 스스로 뒤진다 |
+| `Remember` | 대화가 끝나도 남길 것 한 줄 — 다음에 켤 때 처음부터 안다 |
+| `TodoWrite` | 할 일 목록 — 긴 일을 쪼개서 어디까지 했는지 화면에 띄움 |
+| `Outline` | 폴더의 **뼈대만** 보기 — 통째로 읽는 것보다 수십 분의 일 |
+| `Verify` | 만든 것이 **진짜 되는지** 확인 |
+| `Task` | 큰 일의 한 덩이를 **따로 떨어진 창**에서 돌리기 |
+| `Jobs` | **뒤에서 도는 명령** 보기·읽기·끝내기 — `Bash` 의 `background` 와 짝 |
+| `Def` | 이름이 **어디 정의됐는지** — 언어 서버가 깔려 있을 때만 보입니다 |
+| `Refs` | 이름을 **어디서 쓰는지** 전부 — 언어 서버가 깔려 있을 때만 보입니다 |
+Claude Code 에 없는 것은 일곱입니다 — `Append` · `Recall` · `Remember` ·
+`Outline` · `Verify` · `Task` · `Jobs`. 도구 하나가 스키마로 150~400토큰을 먹고
+그게 **매 요청마다** 나가므로, 늘릴 때마다 검사에서 한 번 멈추게 해 뒀습니다
+(`test/loop.test.js`). 뒤의 넷은 그 값을 치르고도 넣을 만해서 넣은 것들이라,
+아래에 왜인지를 적어 뒀습니다.
+> **자세히** — Outline · Verify · Task · Def · Refs · 끝나지 않는 명령은 뒤에서 외 9개
+>
+> **[도구 자세히 읽기 →](docs/ko/tools.md#도구)**
+---
+## 한글 문서와 엑셀
+**CP949 로 저장된 파일은 CP949 로 되돌려 씁니다.** 인코딩을 바꾸지 않습니다.
+엑셀(`.xlsx`)은 CSV 로, 한글·워드·파워포인트(`.hwpx`/`.docx`/`.pptx`)는 글로
+바꿔서 읽습니다 — 전부 읽기 전용입니다.
+> **자세히** — 인코딩 · 엑셀 · hwpx/docx/pptx
+>
+> **[한글 문서와 엑셀 읽기 →](docs/ko/documents.md#한글-문서와-엑셀)**
+---
+## 만든 웹을 그 자리에서 띄웁니다
+```
+❯ /preview
+  ▶ 띄웠습니다  http://127.0.0.1:56801/
+  보여 주는 것 .
+  파일을 고치면 화면이 저절로 새로 뜹니다.
+  이 컴퓨터에서만 열립니다(127.0.0.1). 다른 PC 에서는 안 보입니다.
+  끄려면 /preview off  · deel 을 끝내면 같이 꺼집니다.
+```
+브라우저가 같이 열립니다. `/preview 폴더` 로 자리를 정하고, `/preview off` 로 끕니다.
+**파일을 두 번 눌러 여는 것(`file://`)과 다릅니다.** `file://` 에서는 아래가 전부
+막힙니다 — 그런데 오류는 콘솔에만 나오고 화면은 그냥 희어서, 만든 사람은 제 코드를
+의심하며 시간을 씁니다. 진짜 HTTP 서버라 다 돕니다:
+| | `file://` | `/preview` |
+|---|---|---|
+| `<script type="module">` · `import` | 막힘 (CORS) | **됨** |
+| `fetch('./자료.json')` | 막힘 | **됨** |
+| `new Worker(...)` | 막힘 | **됨** |
+| `WebAssembly.compileStreaming` | 막힘 (형식) | **됨** |
+| 텍스처·`getImageData` | 캔버스 오염 | **됨** |
+| `.glb` / `.gltf` (Three.js) | 형식 없음 → 조용히 안 그려짐 | **됨** |
+실제 크롬에서 이 일곱 가지를 돌려 **7/7** 을 확인했습니다.
+라우터를 쓰는 앱(React Router 등)은 안쪽 주소에서 새로고침해도 첫 장이 나옵니다.
+다만 확장자가 있는 요청(`app.js`)에는 절대 안 그럽니다 — 없는 스크립트에 HTML 을
+돌려주면 `Unexpected token '<'` 로 죽는데, 그게 진짜 원인(파일 이름 오타)을 가립니다.
+### 열어 주는 만큼만 엽니다
+서버를 띄운다는 것은 내 디스크를 남에게 열어 주는 일입니다.
+- **`127.0.0.1` 에만** 묶습니다. `0.0.0.0` 은 아예 못 씁니다 — 같은 사무실 망에서
+  아무나 내 소스를 읽게 됩니다.
+- 포트는 **0**(커널이 빈 것을 줍니다). 고정 포트는 남이 쓰던 것을 뺏습니다.
+- 경로는 작업 범위 밖으로 못 나갑니다. `../` · `%2e%2e` · 두 번 인코딩 · 절대 경로 ·
+  널바이트 · 심볼릭 링크 — 여덟 가지를 검사로 막아 뒀습니다.
+- **주기만 합니다.** `POST` · `PUT` · `DELETE` 는 405 로 거절합니다.
+- `deel` 을 끝내면 같이 꺼집니다.
+## 스킬·플러그인
+**남의 스킬은 품고 다니지 않습니다.** 켜질 때 그 PC 를 훑어 있는 것을 그대로 씁니다.
+**다만 일하는 방법 일곱 가지는 품고 다닙니다.** 사내에서 새로 받은 PC 에는
+`~/.claude/skills` 도 플러그인도 없습니다. 거기서는 방법론이 0개라 모델이 매번
+제 나름대로 했고, 시킨 것만 겨우 하고 끝나는 얄팍한 결과가 거기서 나왔습니다.
+| 스킬 | 언제 |
+|---|---|
+| `깊이있게-만들기` | 고도화·보고용·선포용 — 최소치만 내고 끝내지 않게 |
+| `끝까지-하기` | 시킨 것이 여러 조각일 때. 빼먹은 것은 말하게 |
+| `차근차근-디버깅` | 재현 → 좁히기 → 원인 → 고치기 → 증명 |
+| `검사-먼저` | 고치기 전에 실패하는 검사부터 |
+| `찔러보기` | 되는지 모를 때 시간 정해 작게 찔러 보고 버리기 |
+| `코드-줄이기` | 동작은 그대로 두고 읽기 쉽게 |
+| `스스로-검토` | 다 됐다고 말하기 전에. 못 잰 것까지 말하게 |
+목록으로 늘 나가는 몫은 354토큰입니다(8k 창의 4%). 본문은 `Skill` 로 부를 때만 나갑니다.
+같은 이름을 직접 만들면 그쪽이 이깁니다 — 품고 다니는 것이 제일 낮은 자리입니다.
+```
+품고 다님  (패키지 안)                                    ← 제일 낮은 자리
+프로젝트  ./.deel/skills   ./.claude/skills   ./.deel/commands   ./.claude/commands
+사용자    ~/.deel/skills   ~/.claude/skills   ~/.claude/commands
+플러그인  ~/.claude/plugins/**   ~/.deel/plugins/**
+```
+Claude Code 와 같은 형식(`SKILL.md` + YAML 앞머리, `commands/*.md`, `$ARGUMENTS`)을 읽습니다.
+> **자세히** — 3단계로 나눠 올립니다 · 플러그인 받아 오기 · 안 넣은 것
+>
+> **[늘려 쓰기 읽기 →](docs/ko/extend.md#스킬플러그인)**
+---
+## 추론 강도
+에이전트 한 번의 대답은 모델을 여러 번 부릅니다. **부를 때마다 필요한 생각의 양이 다릅니다.**
+전부 세게 두면 느리고, 전부 얕게 두면 엉뚱한 길로 갑니다.
+기본은 **한 줄**입니다. 알고 싶은 것은 '지금 얼마나 생각하나' 이지 단계표가 아닙니다.
+```
+$ /think
+  추론 강도  medium   (첫 판단 medium · 이어가기 low · 막혔을 때 high)
+  더 세게 /think high   더 빠르게 /think low
+```
+| 배분 | 성격 |
+|---|---|
+| `even` (균일) | 모든 단계 같은 강도 — 예측 가능한 대신 느림 |
+| `save` (절약, 기본) | 첫 판단만 세게, 이어가기는 얕게 |
+| `deep` (깊게) | 전 단계 한 칸씩 위로 — 어려운 일에만 |
+배분은 `/think 배분 절약` 로 정합니다. **강도와 배분은 다른 축이라 명령을 갈랐습니다** —
+전에는 `/think high` 와 `/think save` 가 같은 이름으로 다른 것을 정해서,
+화면을 봐도 지금 무엇이 무엇인지 읽히지 않았습니다.
+단계표는 `/think 자세히` 로 뺐습니다(개발자 수준 기본).
+```
+$ /think 자세히
+  추론 강도  medium   (첫 판단 medium · 이어가기 low · 막혔을 때 high)
+  배분      절약   첫 판단만 세게, 이어가기는 얕게 — 대개 이게 낫습니다
+  단계        강도      출력상한  언제
+  첫 판단     · medium      15,549  무엇을 할지 정하는 자리
+  이어가기    ↓ low         13,605  도구 결과를 읽고 다음 한 수
+  막혔을 때   ↑ high        16,384  직전 도구가 오류를 냄
+  출력 상한은 16,384 (모르는 값이라 기본값) 안에서 나눕니다 — /out
+  컨텍스트 40,960 · 지금 찬 양 2,087
+```
+마지막에서 두 번째 줄이 있는 이유: **세 값이 다 같을 때 그게 고장인지 아닌지**
+이 한 줄로 갈립니다. 아는 상한이 낮으면 셋이 같아지는 것이 맞습니다.
+한동안 이 표는 세 줄이 늘 `16,384` 였고, 그건 표가 뜻이 없다는 뜻이었습니다.
+> **자세히** — 컨텍스트 길이는 모델에서 긁어옵니다 · /out · 잘린 도구 호출
+>
+> **[속도와 씀씀이 읽기 →](docs/ko/tuning.md#추론-강도)**
+---
+## 자동 압축
+컨텍스트가 80% 차면 앞선 대화를 **요약해서 접고 계속 이어 갑니다.**
+그냥 잘라내면 모델이 하던 일을 잊고, 파일을 다시 읽고, 이미 고친 곳을 또 고칩니다.
+```
+  ◱ 대화 44개를 요약으로 접었습니다 — 10,399 → 3,170 토큰 (70% 줄어듦)
+```
+요약은 목표 / 한 일 / 알아낸 것 / 정한 것 / 남은 일 다섯 항목으로 남습니다.
+접을 때 **도구 호출과 그 결과가 갈라지지 않는 자리**를 골라 자릅니다 — 갈라지면 서버가 400 을 냅니다.
+요약 요청이 실패하면 옛 방식(그냥 줄이기)으로 물러서고 멈추지 않습니다.
+`/compact` 로 직접 접을 수도 있습니다.
+---
+## 대화 이어하기
+터미널을 실수로 닫거나 컴퓨터가 재부팅돼도 하던 대화를 그대로 이어 받습니다.
+오간 내용은 **메시지 하나가 끝날 때마다 바로** `.deel/sessions/` 에 적히기 때문에,
+도중에 죽어도 그 직전까지는 남습니다.
+```
+$ deel sessions
+── 이 폴더의 대화 ──────────────────────────────────────────────
+  ● 20260824-090200  방금        1턴  devstral-small-2507
+      테스트 깨진 거 고쳐줘
+  · 20260824-084500  2시간 전     2턴  qwen2.5-coder:7b
+      src/a.js 의 로그를 logger 로 바꿔줘
+```
+| 명령 | 하는 일 |
+|---|---|
+| `deel --continue` | 이 폴더에서 가장 최근 대화 이어하기 |
+| `deel --resume <id>` | 골라서 이어하기 |
+| `deel sessions` | 남아 있는 대화 목록 |
+| `deel sessions --rm <id>` | 하나 지우기 |
+한 줄에 메시지 하나씩 쓰는 `jsonl` 이라, 쓰다가 전원이 나가도 마지막 줄만 잃습니다.
+이어받은 대화는 도구 호출과 그 결과의 짝까지 그대로 살아 있어 바로 이어서 일할 수 있습니다.
+30일이 지나고 최근 30개 밖인 것은 자동으로 정리합니다.
+저장 위치는 작업 폴더의 `.deel/sessions/` 이고, `.gitignore` 에 `.deel/` 이 들어 있어
+깃에 올라가지 않습니다.
+---
+## 밖에서 도구 붙이기 (MCP)
+사내 위키 검색기, 이슈 트래커, DB 조회기 같은 것을 각 팀이 MCP 서버로 만들어 두면
+deel 은 그걸 **코드를 안 고치고** 도구로 씁니다.
+`.deel/mcp.json` 에 적습니다. Claude Code 설정을 그대로 복사해 붙일 수 있습니다:
+```json
+{ "mcpServers": { "사내위키": { "command": "node", "args": ["wiki-mcp.js"] } } }
+```
+모델에게는 `mcp__사내위키__검색` 이라는 이름으로 보입니다. `/mcp` 로 무엇이 붙었는지 봅니다.
+**의존성은 그대로 0 입니다.** stdio 규격은 자식 프로세스의 stdin/stdout 에 줄 단위
+JSON-RPC 2.0 을 주고받는 것이 전부라, `child_process` 와 `JSON` 이면 됩니다. SDK 가
+필요 없습니다.
+> **자세히** — 다만 이건 남의 프로그램입니다
+>
+> **[늘려 쓰기 읽기 →](docs/ko/extend.md#밖에서-도구-붙이기-mcp)**
+---
+## 에디터 안에서 쓰기 (ACP)
+터미널을 하나 더 띄우게 하는 도구는 두 주쯤 뒤에 안 씁니다. 개발자는 하루 종일
+IDE 안에 있습니다. 그래서 **ACP**(Agent Client Protocol)를 지킵니다 — Zed ·
+JetBrains · Neovim · Emacs 가 **저쪽을 한 줄도 안 고치고** deel 을 붙입니다.
+에디터 설정에 이 명령 하나만 적으면 됩니다.
+```
+deel acp
+```
+에디터가 이걸 자식 프로세스로 띄우고, 표준입출력으로 줄 단위 JSON-RPC 2.0 을
+주고받습니다. 사람이 직접 칠 명령은 아닙니다.
+**붙으면 이렇게 됩니다.**
+| 에디터 쪽 | deel 쪽 |
+|---|---|
+| 답이 흘러나오는 자리 | 모델이 흘리는 글 · 생각 |
+| 도구 목록 (아이콘·상태) | `Read` 는 읽기, `Edit` 는 고치기, `Bash` 는 실행 — **갈래를 붙여** 보냅니다 |
+| 파일 링크 | 고친 파일의 **절대 경로**. 눌러서 그 자리로 갑니다 |
+| 승인 창 | deel 의 안전망이 그대로 에디터 창으로 뜹니다 (`이번만` · `앞으로 묻지 않기` · `안 함`) |
+| 모드 고르개 | deel 의 작업 모드 7개 (`종합` · `코드` · `계획` · `설계` · `디버그` · `묻기` · `총괄`) |
+| 멈춤 단추 | 도중에 닿습니다 — 답을 기다리는 중에도 |
+**의존성은 그대로 0 입니다.** MCP 와 같은 이유입니다 — 줄 단위 JSON-RPC 2.0 이
+전부라 SDK 가 필요 없습니다.
+> **자세히** — 조용히 깨지는 자리들
+>
+> **[늘려 쓰기 읽기 →](docs/ko/extend.md#에디터-안에서-쓰기-acp)**
+---
+## 비밀이 새지 않게
+사람이 열쇠를 붙여 넣는 일은 드뭅니다. 새는 자리는 거의 항상 **명령 출력**입니다.
+```
+env                  OPENAI_API_KEY=sk-proj-…
+git remote -v        https://사람:토큰@github.com/…
+curl -v              > Authorization: Bearer eyJ…
+검사 실패 로그         연결 문자열이 통째로
+```
+그 글은 모델에게 실려 가고, **동시에** `.deel/sessions/*.jsonl` 로 디스크에
+적힙니다. 그 파일은 나중에 `/recall` 로 다시 읽히고 `deel pack` 에 딸려 갈 수도
+있습니다. 한 번 새면 여러 벌이 됩니다.
+그래서 도구 결과가 대화로 들어가는 **한 자리**에서 가립니다.
+```
+  ⏺ Bash(env | grep API)  완료
+    ⊘ 비밀로 보이는 값 2군데가 대화에 들어갔습니다 (openai · 환경변수) — 모델에 가려서 보냈습니다
+```
+찾는 것: 사설키 블록 · OpenAI/Anthropic 열쇠 · GitHub 토큰 · Slack 토큰 ·
+AWS 키 · Google 키 · JWT · 주소에 박힌 열쇠 · `Authorization` 계열 헤더 ·
+이름이 `…KEY`/`…TOKEN`/`…SECRET`/`…PASSWORD` 인 환경변수. 그리고 **설정에 든
+게이트웨이 열쇠는 모양과 상관없이** — 그건 짐작이 아니라 아는 값이니까요.
+### 파일 내용은 일부러 안 가립니다
+가리고 싶은 마음이 제일 드는 자리가 `.env` 인데, 거기를 가리면 이렇게 됩니다 —
+모델이 가려진 글을 보고, 그걸 고쳐서 되돌려 씁니다. 그러면 진짜 열쇠가 있던
+자리에 `«가림»` 이 적힙니다. **비밀을 지키려다 사람의 열쇠를 우리 손으로
+지우는 셈입니다.**
+그래서 파일 쪽은 가리는 대신 **알립니다.**
+```
+  ⏺ Read(.env)  12줄
+    ! 비밀로 보이는 값 3군데가 대화에 들어갔습니다 (환경변수)
+      — 파일 내용은 가리지 않습니다 (가리면 되돌려 쓸 때 지워집니다)
+```
+무엇을 못 막는지 분명히 말하는 편이, 막았다고 해 놓고 파일을 망가뜨리는 것보다
+언제나 낫습니다. 어느 쪽이든 감사기록에 남습니다.
+---
+## 안전망
+승인 프롬프트 대신 **되돌릴 수 있게** 만들었습니다. 기본 모드 `auto` 는 묻지 않고 알아서 합니다.
+| 장치 | 내용 |
+|---|---|
+| **되돌리기** | 파일을 고치기 전 항상 스냅샷. `/undo` 로 턴 단위 복구. **`Bash` 로 옮기고 지우는 것도 포함** |
+| **바뀐 자리 보기** | 고칠 때마다 바뀐 줄을 화면에. 이번 대화 전체는 `/diff` |
+| **작업 범위** | 시작한 폴더 밖은 모델이 시켜도 거부 |
+| **위험 명령 차단** | 되돌릴 수 없는 것만 (디스크 포맷, 재귀 삭제, `--force` 푸시 등) |
+| **재실행 금지** | 변경성 명령은 실패해도 다시 실행하지 않음 — 두 번 돌면 사고 |
+| **중단** | Ctrl+C 로 도중에 끊어도 대화가 성한 채로 남음 |
+| **헛돌기 차단** | 같은 도구가 같은 이유로 3번 실패하면 그 턴을 멈추고 왜인지 말함 |
+| **안 읽는 자리** | 남의 도구 살림과 deel 자신의 기록·설정(열쇠)은 거절 |
+| **감사 로그** | `.deel/audit.jsonl` 에 전부 기록 |
+| 모드 | 언제 물어보나 |
+|---|---|
+| `auto` (기본) | 안 물어봄. 되돌리기가 안전망 |
+| `confirm` | 되돌릴 수 없는 명령만 |
+| `strict` | 파일 변경·명령 전부 |
+되돌리기 이력은 파일 내용을 통째로 담기 때문에 큰 파일을 여러 번 고치면 금방 커집니다.
+32MB 를 넘으면 **최근 50턴만 남기고** 오래된 것을 버립니다. 방금 한 일은 언제나
+되돌릴 수 있고, 지금 이력이 얼마나 되는지는 `/status` 에서 봅니다.
+> **자세히** — Bash 로 사라진 것도 되돌아갑니다 · 안 읽는 자리
+>
+> **[안전망과 사내 반입 읽기 →](docs/ko/safety.md#안전망)**
+---
+## 사내 반입
+심사서와 소스를 zip 하나로 묶습니다.
+```bash
+deel pack --out deel-반입.zip
+```
+```
+── 반입 묶음 ───────────────────────────────────────────────────
+  ✓ deel-반입.zip
+     94개 파일 · 509.6KB
+  의존성          0개
+  설치 스크립트   없음
+  외부 import     0건
+  네트워크 호출   3곳 (설정한 주소로만)
+  포트 열기       1곳 (/preview 만)
+```
+zip 안에는 **사람이 읽을 것 한 장, 기계가 읽을 것 두 장**이 같이 들어갑니다.
+반입 심사는 사람만 보는 절차가 아니기 때문입니다 — 보안팀은 SBOM 을 스캐너에
+먹여 취약점 목록을 뽑고, 운영팀은 감사 사양을 보고 SIEM 수집 규칙을 짭니다.
+| 파일 | 무엇 |
+|---|---|
+| `반입심사서.txt` | 의존성 · 설치 스크립트 · **소스를 훑어 찾은 네트워크·외부 명령 호출 자리 전부**(파일:줄) · 나가는 길 세 갈래 · 파일별 SHA-256 |
+| `sbom.cdx.json` | **SBOM (CycloneDX 1.5).** 스캐너에 그대로 넣습니다. 파일마다 부품 하나에 SHA-256, 의존성은 **빈 배열로 명시** — 안 적어 낸 것과 없는 것은 다릅니다 |
+| `심사명세.json` | 통신 목록(갈래마다 언제·어디로·무엇이·막는법·소스 자리) · **감사기록 사양**(칸 이름과 뜻, 안 남기는 것) · 파일 해시 |
+```bash
+deel audit                    # 사람이 읽는 심사서만 보기
+deel sbom                     # 기계가 읽는 두 장을 표준출력으로 (deel sbom | jq)
+deel sbom --out 심사.json     # 파일로
+deel sbom --only sbom         # SBOM 한 장만
+```
+셋 다 손으로 적지 않고 코드가 소스를 훑어서 만듭니다 — 손으로 적으면 언젠가
+사실과 어긋나고, **어긋난 심사 서류는 없느니만 못합니다.** 담당자가 한 번 틀린
+것을 발견하면 나머지도 안 믿습니다. 감사기록 사양만은 손으로 적혀 있어서,
+그것이 진짜 기록과 어긋나지 않는지를 검사가 매번 대조합니다.
+> **자세히** — 사내 게이트웨이 진단
+>
+> **[안전망과 사내 반입 읽기 →](docs/ko/safety.md#사내-반입)**
+---
+## 설정
+`~/.deel/config.json` 에 저장됩니다. 프로젝트 폴더에 `.deel/config.json` 이 있으면 그쪽이 우선입니다.
+> **자세히** — 붙는 서버 · 환경변수 · 실행 옵션 · 프로젝트 규칙
+>
+> **[설정 읽기 →](docs/ko/config.md#설정)**
+---
+## 문제 해결
+| 증상 | 확인할 것 |
+|---|---|
+| `주소를 찾을 수 없습니다` | 주소 오타, DNS, 사내망 접속 여부 |
+| `연결이 거부되었습니다` | 서버가 꺼져 있거나 포트가 다름 |
+| `인증서 문제` | `set NODE_EXTRA_CA_CERTS=C:\경로\사내CA.pem` |
+| 프록시를 거쳐야 함 | `set HTTPS_PROXY=http://프록시:포트` |
+| 401 / 403 | 키가 틀렸거나 인증 헤더 형식이 다름 (4가지를 자동 시도합니다) |
+| `허용되지 않은 주소입니다` | 자물쇠가 막은 것. 정상입니다 — `/model` 로 연결을 고르세요 |
+| 도구 호출이 안 먹음 | `deel diagnose` 로 판정을 보세요. 작은 모델(1B~3B)은 자주 못 합니다 |
+| 대답이 비어 있음 | 스트리밍을 무시하는 서버입니다. 한 번은 저절로 다시 부르고, 그래도 비면 이 대화에서는 스트리밍을 끕니다 |
+| 큰 파일이 중간에 끊김 | `/out` 으로 지금 상한을 보고 올리세요. 상한을 몰라 16,384 로 서 있을 수 있습니다 |
+| `HTTP 400` 만 뜸 | 서버가 보낸 문장을 그대로 보여 줍니다. 길이 문제면 숫자를 읽어 저절로 맞춥니다 |
+| `deel scan` 이 0곳 | 로컬 서버가 꺼져 있거나 다른 포트 — `--ports` 로 지정 |
+---
+## 개발
+```bash
+npm test          전체 검증 (1,832항목)
+npm run coverage  검사가 소스의 어디를 밟았는지
+npm run verify    반입·통신 검증만
+npm run bench     편집 성공률 측정
+npm run demo      화면이 어떻게 보이는지 실제로 돌려 보기
+npm run check     전 파일 문법 검사
+```
+검증은 **가짜 게이트웨이**를 띄워서 합니다. 실제 모델 없이 규격 그대로
+루프·스트리밍·도구 실행·되돌리기·압축을 결정적으로 확인합니다.
+zip 은 진짜 `unzip` 으로, tar 는 진짜 `tar` 가 만든 것을 읽혀 교차 확인합니다.
+`npm test` 는 파일을 하나씩 돌리고 **파일별 종료코드**를 표로 남깁니다.
+화면의 통과 표시가 아니라 종료코드가 CI 가 보는 값이기 때문입니다. 둘은
+갈라질 수 있습니다 — 검사를 다 통과하고도 끝낼 때 죽으면 화면은 초록인데
+종료코드는 1 입니다. 실제로 윈도우에서 그렇게 한 번 놓쳤습니다.
+첫 실패에서 멈추지 않고 끝까지 돌기 때문에, 한 번 돌리면 전부 알 수 있습니다.
+```
+  ────────────────────────────────────────────────────────────
+  검사 파일              종료코드   통과   실패   시간
+  ────────────────────────────────────────────────────────────
+  ✓ smoke.js            0            20     0     0.2초
+  ✗ scan.test.js        1            19     0     0.2초
+  ────────────────────────────────────────────────────────────
+  ✗ scan.test.js — 종료코드 1
+     검사는 전부 통과했는데 종료코드만 1 입니다 —
+     끝낼 때 남은 핸들·처리 안 된 거절 때문입니다.
+```
+| 검증 | 항목 | 무엇을 |
+|---|---|---|
+| `smoke` | 20 | 도구·작업범위·되돌리기·감사로그 |
+| `loop` | 16 | 에이전트 루프·스트리밍·도구 호출 |
+| `guard` | 24 | **안 하는 자리** — 거부·모르는 도구·두 번 실행·범위 밖 |
+| `network` | 30 | 정해진 자리 밖으로 새지 않는가 |
+| `web` | 25 | 웹 읽기가 읽기만 하는가 |
+| `abort` | 16 | Ctrl+C 로 끊어도 대화가 성한가 |
+| `parallel` | 23 | 읽기만 동시에 도는가 · 할 일 목록 |
+| `cli` | 75 | **진짜 `deel` 을 띄워** 끝까지 돌려 본다 |
+| `setup` | 42 | 첫 실행 마법사 (가짜 TTY 로 사람처럼 입력) |
+| `detect` | 66 | 주소 한 줄로 규격·인증을 짚어내는가 |
+| `modes` · `route` | 89 · 33 | 작업 모드 · 종합에서 알맞은 모드로 옮겨 가는가 |
+| `ctxsize` | 43 | 모델에 걸린 컨텍스트 길이를 긁어오는가 |
+| `commands` · `commands-more` | 128 · 62 | 슬래시 명령 전부 |
+| `ui` · `ui2` | 60 · 40 | 암호 가림·한글 폭·상태줄·대화 목록·엑셀→글 |
+| `encoding` · `xlsx` | 68 · 72 | 한글 인코딩 판별 · 엑셀 읽기 |
+| `compact` | 21 | 요약 압축·짝 안 깨짐·실패 시 물러섬 |
+| `store` | 34 | 대화 저장·이어하기·중간에 죽어도 복구 |
+| `scan` | 29 | 여러 런타임을 구분해 찾는가 |
+| `plugins` | 38 | 플러그인 받기·묶기·ZIP/TAR |
+| `no-bundle` | 12 | 배포 묶음에 남의 것이 안 섞였는가 · 검사 파일 위생 |
+| `edit-bench` | 20건 | 편집 성공률 |
+> **자세히** — 어디를 밟았는지 · 폴더 구조
+>
+> **[개발 읽기 →](docs/ko/develop.md#개발)**
+---
+## 릴리스 노트
+| 판 | 무엇이 바뀌었나 |
+|---|---|
+| **[1.5.0](docs/ko/releases.md#150)** | 줄바꿈이 생겼고, 화면이 재미있어졌고, 그러면서 오히려 가벼워졌다 |
+| [1.4.3](docs/ko/releases.md#143) | README 가 왜 다른지 말하고, 심사서의 빠진 한 줄을 채운다 |
+| [1.4.2](docs/ko/releases.md#142) | 1.4.1 이 보안 수정 전에 나갔다 — 그걸 바로잡는 판 |
+| [1.4.1](docs/ko/releases.md#141) | 새 기능 없이, 실제로 찾은 것만 고친다 — 윈도우 abort·ReDoS·XSS |
+| [1.4.0](docs/ko/releases.md#140) | deel 이 제 얼굴을 갖고, 영어로도 말하고, 뜻까지 본다 — 열한 자리 |
+| [1.3.0](docs/ko/releases.md#130) | 말 대신 증거, 터미널 대신 에디터 — 여섯 자리 |
+| [1.2.0](docs/ko/releases.md#120) | 대화가 끊기지 않게 — 여섯 자리 |
+무엇이 왜 바뀌었는지는 **[릴리스 노트](docs/ko/releases.md)** 에 있습니다.
+---
+## 라이선스
+[MIT](LICENSE)