tabby-agentdeck 0.3.0 → 1.1.1

package/README.md

@@ -4,19 +4,21 @@ Tabby 터미널 플러그인. **Claude Code · Codex 같은 AI 에이전트 CLI
 
 터미널 뷰포트를 **4:3 으로 고정**하고 남는 공간에 **세션 목록 + 작업 상태 사이드바**를 그린다.
 어느 에이전트가 돌고 있고 어느 쪽이 내 입력을 기다리는지 탭을 옮겨 다니지 않고 한눈에 본다.
+에이전트가 만든 문서·그림은 **미리보기 패널**에서 터미널 옆에 띄워 확인한다.
 거기에 에이전트 CLI 가 터미널에서 겪는 문제들(이미지 붙여넣기, 줄바꿈 키, pty 폭 어긋남)을 같이 손봐 둔다.
 
 ```
-┌──────────────────────────────┬──────────────────┐
-│                              │ AGENT DECK    4   │
-│     터미널 (창 높이 × 4/3)     ├──────────────────┤
-│                              │ ● 진행중  리팩터링 │
-│     Tabby 순정 탭바는 숨김      │ ⏸ 승인대기 재빌드 │
-│                              │ ✔ 완료   테스트   │
-│                              │ ○ 대기            │
-│                              ├──────────────────┤
-│                              │ + 새 탭 │ 설정    │
-└──────────────────────────────┴──────────────────┘
+┌────────────────────┬──────────────────┬──────────────────┐
+│                    │ note.md   ＋ ⟳ ✕ │ AGENT DECK    4  │
+│  터미널 (4:3 기준)   ├──────────────────┼──────────────────┤
+│                    │ note.md  shot.png│ ● 진행중  리팩터링 │
+│  Tabby 순정 탭바는   ├──────────────────┤ ⏸ 승인대기 재빌드 │
+│  숨김               │ # 제목            │ ✔ 완료   테스트   │
+│                    │ 본문이 그려진다     │ ○ 대기            │
+│                    │ [그림]            ├──────────────────┤
+│                    │ 742 B · 방금      │ + 새 탭 │ 설정    │
+└────────────────────┴──────────────────┴──────────────────┘
+      터미널              미리보기 패널        세션 목록
 ```
 
 Windows 에서 만들고 검증했다. 상태 통보 훅은 PowerShell 스크립트라 Windows 전용이고, 그 외 기능은 플랫폼을 가리지 않는다.
@@ -27,14 +29,28 @@ Windows 에서 만들고 검증했다. 상태 통보 훅은 PowerShell 스크립
 |---|---|
 | **4:3 기준 폭 계산** | 창 높이에서 폭을 역산해 터미널을 고정폭으로 만든다. 남는 폭은 사이드바가 갖고, 그러고도 남으면 터미널이 흡수한다 |
 | **사이드바 탭 관리** | 클릭=선택, `×`=닫기, 더블클릭=작업 이름 편집, 우클릭=상태 직접 지정 |
+| **검색 · 상태 필터** | 헤더 아래 검색창으로 제목·작업이름·작업폴더를 좁히고, 상태 칩을 눌러 그 상태만 본다. Esc 로 해제 |
+| **순서 바꾸기** | 사이드바 줄을 끌어 옮긴다(순정 탭바 순서도 함께). 목록 끝에 커서를 대고 있으면 **저절로 흘러가** 화면 밖 자리로도 한 손짓에 옮긴다. 상태순 정렬이 켜져 있으면 막고 이유를 알린다 |
+| **키보드로 다루기** | `Ctrl+Shift+L` 로 목록에 들어가 `↑↓` 로 훑고 Enter 로 고른다. **훑는 동안 탭은 바뀌지 않는다** — 지나가는 탭의 출력이 화면을 채우지 않게 포커스와 선택을 갈랐다. `Ctrl+W` 로 지금 탭(목록에서는 포커스 줄)을 닫는다 |
+| **결과물 미리보기** | 에이전트가 만진 md · 이미지 · 표(csv/tsv) · 코드를 터미널 옆 패널에서 본다. 화면에 찍힌 경로를 스스로 주우므로 Claude Code · Codex · Gemini 를 가리지 않는다 |
+| **끌어다 놓기** | 파일을 패널에 놓으면 바로 열리고, **터미널 위에 놓으면** `패널에 띄우기` / `경로 붙여넣기` 를 물어본다 |
+| **변경 보기** | 같은 패널의 `변경` 탭이 작업트리의 `git diff` 를 보여준다 — 파일 목록 · `+N -M` · 줄번호 붙은 유니파이드 diff. 누가 고쳤는지와 무관하게 성립한다 |
+| **`파일:라인` 참조** | diff 나 코드 보기에서 줄을 누르면 그 위치를 터미널에 넣는다(Shift+클릭=범위). "이 줄 고쳐" 를 타이핑 없이 |
+| **스테이지 · 커밋** | `변경` 탭에서 파일 딱지를 눌러 `git add`/`unstage` 하고, 메시지를 적어 커밋한다. **두 번 눌러야 커밋된다**(첫 누름은 확인 대기) |
+| **세션 그룹** | 탭을 프로젝트별로 묶고 접는다. 경계는 저장소 루트(`.git` 등)를 위로 훑어 자동으로 잡으므로 설정이 없다. 그룹이 하나뿐이면 헤더를 그리지 않고 순서도 건드리지 않는다 |
+| **지난 세션 이어받기** | 그룹 안 `⟲ 지난 세션` 을 펴면 **닫힌 Claude Code 세션**이 사람이 친 프롬프트로 보인다. 누르면 그 세션의 작업 폴더에서 `claude --resume` 으로 대화가 되살아난다 |
+| **한글 조합 보정** | 조합 중인 음절이 커서를 따라가거나 새 줄로 내려가지 않게, pty 에 쓰기 전에 조합이 끝나기를 기다린다 |
+| **에이전트 프로필** | 어느 CLI 가 도는 탭인지 알아내고(프로세스 → 제목) 그에 맞는 규칙을 쓴다. 새 CLI 지원은 프로필 한 덩이 추가로 끝난다 |
 | **마우스 도킹** | 헤더를 끌어 좌/우/상/하 어느 가장자리에나 붙이고, 경계선을 끌어 크기를 바꾼다 |
-| **작업 상태** | 진행중 / 승인대기 / 한도 도달 / 완료 / 오류 / 대기 를 색·배지·경과시간으로 표시 |
+| **작업 상태** | 진행중 / 승인대기 / 한도 도달 / 완료 / 오류 / 대기 를 색·배지·경과시간으로 표시. 훅이 없어도 화면 문구로 판정하고, **왜 멈췄는지**(승인 대상·한도)를 배지에 붙인다 |
 | **상태별 집계** | 헤더 오른쪽에 상태별 탭 수를 `⏸ 2 ● 3 ○ 1` 처럼 급한 순서(승인대기 → 오류 → 한도 도달 → 진행중 → 완료 → 대기)로 보여준다. `sortByStatus` 를 켜면 같은 순서로 탭이 정렬된다 |
+| **서브에이전트 개수** | 그 세션이 백그라운드 에이전트를 몇 개 돌리고 있는지 줄에 `❖3` 으로 보인다. 대화 기록에서 **띄운 것과 끝난 것을 대조**해 세므로 훅이 알려주지 않아도 맞는다 |
 | **작업 이름** | Enter 로 프롬프트를 보내는 순간 입력창 원문을 읽어 라벨로 삼는다 |
 | **Claude Code 훅 연동** | 설정 창에서 한 번 설치하면 에이전트가 상태를 직접 알려준다 (선택) |
 | **기본 프로필** | 새 탭을 항상 지정한 작업 루트에서 연다 |
+| **자동 업데이트** | 기동할 때 npm 을 보고 새 버전이 있으면 물어본 뒤, Tabby 를 닫고 → 설치하고 → **스스로 다시 켠다**. 개발 설치(소스 링크)에는 손대지 않는다 |
 | **입력 보정** | `Ctrl+V` 이미지 붙여넣기, `Ctrl+Enter`/`Shift+Enter` 줄바꿈, 우클릭 복사/붙여넣기 |
-| **화면 복구** | 깨진 TUI 를 지우고 다시 그리게 한다. 사이드바 `↻` / 탭 우클릭 / `agentdeck-repair` 핫키 |
+| **화면 복구** | 깨진 TUI 의 **입력창 잔상만** 지우고 크기를 맞춰 다시 그리게 한다 — 보고 있던 대화는 건드리지 않는다. 사이드바 `↻` / 탭 우클릭 / `agentdeck-repair` 핫키 |
 
 ## 설치
 
@@ -51,6 +67,57 @@ powershell -NoProfile -ExecutionPolicy Bypass -File install.ps1
 `install.ps1` 은 Tabby 플러그인 디렉토리(`%APPDATA%\tabby\plugins\node_modules\tabby-agentdeck`)에
 이 폴더를 가리키는 junction 을 건다. 소스를 고치고 `npm run build` 하면 Tabby 재시작으로 반영된다.
 
+### 자동 업데이트
+
+기동하고 8초 뒤, npm 레지스트리에 `tabby-agentdeck` 의 최신 버전을 묻는다.
+새 버전이 있으면 **물어본다** — `지금 업데이트` / `나중에` / `다시 묻지 않기`.
+승낙하면 이렇게 흐른다:
+
+```
+Tabby 가 닫힌다  →  (밖에서) npm install  →  Tabby 가 스스로 다시 켜진다
+```
+
+**사람이 할 일은 처음 한 번 누르는 것뿐이다.** 설치가 끝나면 알아서 다시 켜진다.
+설치가 실패해도 Tabby 는 반드시 다시 켠다 — 업데이트를 고르느라 터미널을 잃는 일은 없어야 한다.
+기록은 `%LOCALAPPDATA%\tabby-agentdeck\update.log` 에 남는다.
+
+| 설정 | 기본값 | |
+|---|---|---|
+| `autoUpdate` | `true` | 끄면 확인도 하지 않는다 |
+| `updateCheckIntervalHours` | `6` | 기동마다 묻지 않는다 |
+| `updateRegistry` | `https://registry.npmjs.org` | 사내 미러를 쓰면 바꾼다 |
+| `updateSkipVersion` | — | `다시 묻지 않기` 를 누른 버전. **그 버전만** 건너뛰고 다음 버전은 다시 묻는다 |
+
+> **왜 Tabby 를 닫고 까나.** 두 가지 때문이다. ① 돌고 있는 플러그인은 자기를 갈아끼울 수 없다 —
+> Tabby 는 기동할 때 `dist/index.js` 를 한 번 읽어 메모리에 올리므로, 디스크를 바꿔도 돌던 코드는
+> 옛것 그대로다. ② Windows 는 로드된 파일을 잡고 있어서, 떠 있는 동안 npm 이 그 폴더를 지우려 들면
+> 반쯤 지운 채 실패할 수 있다 — 플러그인이 깨진 채 남는 것이 가장 나쁜 결과다.
+> 그래서 설치는 임시 폴더로 떼어낸 `updater/agentdeck-update.ps1` 이 **Tabby 종료를 확인한 뒤** 한다.
+
+> **개발 설치에는 설치하지 않는다.** 플러그인 폴더의 `tabby-agentdeck` 이 소스 트리를 가리키는
+> 링크일 때(`install.ps1` 로 깐 개발 환경), 거기에 `npm install` 이 돌면 **작업 중인 소스를 덮어쓴다.**
+> `src/`·`.git`·`webpack.config.js` 중 하나라도 보이거나 항목이 링크면 새 버전이 있다는 것만 알리고
+> 손대지 않는다 (판정은 `update.ts` 의 `canSelfUpdate`).
+
+### 버전은 한 곳에만 적는다
+
+**`package.json` 의 `version` 이 유일한 출처다.** 나머지는 전부 거기서 파생된다 —
+`npm run build` 가 매번 `tools/sync-version.js` 를 먼저 돌려(`prebuild`) `package-lock.json` 과
+사용설명서(`docs/guide/index.html` 의 `<span class="ad-version">`)를 맞추고,
+진단 로그의 `plugin=` 은 런타임에 `package.json` 을 읽는다(`diag.ts` `pluginVersion`).
+
+```powershell
+npm run sync-version              # 지금 맞추기
+node tools/sync-version.js --check  # 어긋난 곳만 알리기 (어긋나면 종료코드 1)
+```
+
+`test/version.test.js` 가 어긋남을 잡으므로 빌드를 안 거친 수정도 `npm test` 에서 걸린다.
+**문서·주석의 `0.18.0 부터 …` 같은 이력 표기는 대상이 아니다** — 그건 "지금 버전" 이 아니라
+그 기능이 들어온 시점이라 갱신하면 오히려 거짓이 된다.
+
+> 이 규칙이 생긴 이유: 2026-09-11 에 같은 버전을 네 곳이 각자 적고 있었고 **전부 달랐다**
+> (`package.json` 1.0.0 / `package-lock.json` 0.3.0 / 사용설명서 0.17.0 / 커밋된 값 0.17.0).
+
 ## 작업 이름과 상태
 
 사이드바 한 줄은 **작업 이름(라벨)** 과 **상태 배지** 로 이루어진다.
@@ -79,6 +146,18 @@ Shift+Enter / Ctrl+Enter 는 줄바꿈이라 라벨을 바꾸지 않고, 입력
   훅 보고는 플러그인이 탭 셸에 심은 `AGENTDECK_TAB` 환경변수로 어느 탭인지 확정한다
   (0.2.2 이전에 열린 탭·재시작으로 복원된 탭은 프로세스 계보로 폴백).
 
+### 어느 에이전트인지 알아내는 법
+
+탭마다 **어떤 CLI 가 도는지** 알아내고(자식 프로세스 이름 → 안 잡히면 탭 제목), 그 에이전트의 규칙을 쓴다.
+지금 아는 것은 Claude Code · Codex CLI · Gemini CLI 셋이고, 새 CLI 는 프로필 한 덩이를 더하면 된다.
+
+프로필이 정하는 것 — 상태 문구(대기·작업중), 제목 스피너, **이미지 붙여넣기 키**(Claude=`ESC v` / Codex=`0x16`),
+입력창 머리글자. 셸만 떠 있는 탭은 `알 수 없음` 이고, 그때는 아는 규칙을 모두 합쳐 판정한다.
+
+> **관측된 값만 좁게 쓴다.** Codex·Gemini 의 화면 문구는 이 리포에서 관측된 바가 없어, 그 두 에이전트는
+> 상태 판정에 합집합(= 예전과 같은 규칙)을 쓴다. 프로필을 붙였다는 이유로 판정이 예전보다 나빠지면
+> 개선이 아니기 때문이다. 실측이 생기면 그 프로필의 `patternsProven` 을 켜면 된다.
+
 ### 직접 지정
 
 - 사이드바에서 **우클릭 → 상태 고르기**, **더블클릭 → 이름 편집**.
@@ -92,6 +171,24 @@ Shift+Enter / Ctrl+Enter 는 줄바꿈이라 라벨을 바꾸지 않고, 입력
   직접 지정한 상태는 **고정**되어 자동 감지가 덮어쓰지 않는다(배지에 점선 밑줄). 우클릭 → `↺ 자동 감지로` 로 해제한다.
   이 경로는 셸 안에서 직접 실행할 때만 통한다 — 에이전트 훅에서는 콘솔 제목이 터미널까지 오지 않는다.
 
+### 서브에이전트 몇 개 돌고 있나
+
+Claude Code 가 백그라운드로 에이전트를 띄우면 그 개수가 줄에 `❖3` 으로 붙는다.
+줄에 마우스를 올리면 무엇이 도는지 목록과 가장 오래된 것의 경과가 나온다.
+
+세는 방법은 **그 세션의 대화 기록에서 띄운 것과 끝난 것을 대조**하는 것이다
+(`~/.claude/projects/*/<세션 id>.jsonl`). 훅이 알려 주는 값이 아니라 기록이 근거이므로,
+훅이 상태를 안 보내는 동안에도 개수는 맞는다. 세션과 탭을 잇는 것은 훅이 쓰는 상태 파일이라
+**훅을 설치하지 않으면 이 표시도 나오지 않는다**(`notifyChannel` 이 꺼져 있어도 마찬가지다).
+
+기록 파일은 수십 MB까지 자라므로 **자란 만큼만** 읽는다 — 2초에 한 번 크기만 확인하고,
+커진 경우에만 그 뒤쪽을 읽어 누적한다. 처음 붙는 세션은 한 번 전체를 훑어야 해서
+개수가 몇 초 늦게 나타날 수 있다.
+
+한 가지 알아 둘 것 — 에이전트를 Esc 로 취소하거나 CLI 가 죽으면 **끝났다는 기록이 안 남아**
+개수가 줄지 않을 수 있다. 그걸 시간으로 감추지 않는다(진짜 오래 도는 것을 지우게 된다).
+대신 툴팁의 경과가 계속 늘어나므로 그것으로 알아볼 수 있다.
+
 ### 알림
 
 창이 다른 앱 뒤에 가 있을 때(포커스 없음) 어느 탭이 `승인대기` · `오류` · `한도 도달` 로 넘어가면 OS 쪽에 알린다 —
@@ -100,6 +197,157 @@ Shift+Enter / Ctrl+Enter 는 줄바꿈이라 라벨을 바꾸지 않고, 입력
 OS 토스트(`alertToast`)는 기본으로 꺼져 있다 — 켜면 토스트를 눌러 바로 그 탭으로 갈 수 있다.
 창이 앞에 있을 때는 셋 다 아무 일도 하지 않는다. 사이드바가 이미 보이고 있기 때문이다.
 
+## 지난 세션 이어받기
+
+Tabby 가 꺼져도 **Claude Code 대화는 디스크에 남는다** (`~/.claude/projects/<프로젝트>/<세션id>.jsonl`).
+`claude --resume <세션id>` 로 그대로 이어받을 수 있는데, 실제로 막히는 곳은 명령이 아니라
+**UUID 목록에서 내 작업을 찾는 것**이다.
+
+agentdeck 은 그 답을 이미 갖고 있다 — Enter 를 칠 때 입력창에서 주운 프롬프트 원문.
+그래서 그룹 끝에 서랍을 하나 둔다:
+
+```
+▾ Root                          ⏸1 ●2
+   ● Agent Root      진행중 ❖2
+     시즌패스 보상 지급경로 정리     3분
+   ⟲ 지난 세션  5              ▸        ← 기본 접힘. 누르면 펴진다
+```
+
+편 모습:
+
+```
+   ⟲ 지난 세션  5              ▾
+      백그라운드에서 뭐 돌고있나본데 이거 뭐야
+        완료                        14:12
+      시즌패스 미수령 보상 우편지급 전환
+        한도 도달                     어제
+```
+
+| 조작 | 하는 일 |
+|---|---|
+| 클릭 | **그 세션의 작업 폴더**에서 새 탭을 열고 `claude --resume <세션id>` 를 보낸다 |
+| 우클릭 → `분기해서 이어받기` | `--fork-session`. 원본 기록을 그 시점 그대로 두고 **복사본**에서 이어간다 — 같은 지점에서 다른 방향을 시도할 때만 쓴다 (매번 쓰면 기록이 불어난다) |
+| 우클릭 → `세션 ID 복사` · `목록에서 숨기기` | 목록에서만 감춘다. 기록 파일은 건드리지 않는다 |
+
+알아 둘 것:
+
+- **작업 폴더가 다르면 목록에 없다.** `--resume` 은 cwd 로 세션을 묶으므로 이어받기도 그 폴더에서 연다.
+- **이미 열려 있는 세션**은 `● 열림` 으로 보이고, 누르면 이어받지 않고 그 탭으로 간다 —
+  같은 세션을 두 탭에서 이어받으면 두 프로세스가 한 기록 파일에 덧쓴다.
+- **대화만 돌아온다.** 그때 띄워 둔 로컬 서버나 백그라운드 프로세스는 되살아나지 않는다.
+- 죽은 줄은 색이 아니라 **형태**(점선 바 + 흐림)로 구분한다. 상태 6색은 이미 살아 있는 탭이 쓰고 있어서,
+  일곱 번째 색을 들이면 배지가 뜻하는 바가 흐려진다.
+- 라벨은 두 곳에서 온다 — 살아 있을 때 주운 프롬프트(원장, `%LOCALAPPDATA%\tabby-agentdeck\sessions.json`)와
+  기록 파일 앞부분에서 읽은 첫 프롬프트. 앞엣것이 우선이고, 플러그인을 깔기 전 세션이나 다른 터미널에서
+  띄운 세션은 뒤엣것으로 잡힌다.
+- 기록 파일이 사라진 세션은 목록에서도 원장에서도 지운다. 이어받아도 복원할 것이 없기 때문이다.
+
+이 기능이 있는 이유는 아래 `기동 시 탭 복원 끄기` 와 한 쌍이다 — 순정 복원은 **셸만** 되살리고
+그 안의 세션은 이미 죽어 있어서 빈 프롬프트 탭만 줄줄이 남는다. 그래서 그쪽은 끄고, 진짜 복원을 여기 둔다.
+
+## 결과물 미리보기 패널
+
+에이전트가 만든 것이 문서나 그림이면 터미널 안에서는 확인할 수 없다. 그래서 탐색기로 나가서 열게 되고,
+그 왕복 때문에 결과물을 안 보고 넘어간다. 그 자리를 메우는 패널이다 — 사이드바의 **▤** 버튼이나
+`agentdeck-view` 단축키로 여닫는다. 여닫은 상태는 다음 기동에도 복원된다.
+
+**보여주는 것**
+
+| 종류 | 어떻게 |
+|---|---|
+| `md` `markdown` `mdx` | 제목·표·목록·코드·인용·체크박스·이미지까지 그려서 보여준다. 문서 안의 이미지도 같이 뜬다 |
+| `png` `jpg` `gif` `webp` `svg` `bmp` `ico` `avif` | 원본 크기로(패널보다 크면 폭에 맞춰) 그린다 |
+| `csv` `tsv` | 표로 그린다. 따옴표로 감싼 칸(`"a,b"`)을 한 칸으로 읽는다 |
+| 코드·텍스트 (`.ts` `.cs` `.py` `.json` `.log` …) | 줄 번호를 붙여 보여준다 |
+
+**파일이 패널에 올라오는 세 경로**
+
+1. **화면에 찍힌 경로를 줍는다** — `Edited src/hero.tsx`, `Wrote D:\a\b.md`, `Read build.py` 처럼
+   에이전트가 만진 파일을 찍으면 그것을 최근 목록(위쪽 칩)에 쌓는다. **어느 에이전트든 통한다** —
+   훅이 있는 Claude Code 뿐 아니라 Codex·Gemini 도 경로는 화면에 찍기 때문이다.
+   상대경로는 그 탭의 작업 폴더로 풀고, 실제로 있는 파일만 올린다. 최근 목록은 **탭마다 따로**다.
+2. **끌어다 놓기** — 탐색기·에디터에서 파일을 패널에 떨어뜨린다.
+3. **경로 직접 입력** — **＋** 를 눌러 경로를 넣는다(`Enter` 로 열고 `Esc` 로 접는다).
+   **없는 파일이면 만들어 준다** — `Enter` 를 한 번 더 치면 (필요하면 상위 폴더까지) 만들고
+   곧바로 편집으로 들어간다. 메모 한 장 시작하려고 탐색기로 나갈 일이 없다. 두 번 치게 한 이유는
+   오타로 친 경로에 빈 파일이 조용히 생기면 나중에 그 오타를 찾는 값이 더 크기 때문이다.
+
+열어 둔 파일이 바뀌면 **스스로 다시 읽는다** — 에이전트가 문서를 고치는 동안 옆에서 따라간다.
+패널이 닫혀 있어도 **읽어는 둔다**(`문서 패널에 읽어두기`, 기본 켬) — 그리지만 않고 최근 칩과
+"다음에 열면 보여줄 파일" 을 계속 갈아 두므로, 작업이 한창일 때 `▤` 를 누르면 **그때까지 건드린
+파일들이 칩으로 쌓여 있고 본문은 가장 최근 파일**이다(`변경` 을 보고 있었으면 그 자리에서 diff 를
+다시 읽는다). 같은 파일이라도 여는 김에 다시 읽는다 — 닫힌 동안에는 파일 감시가 꺼져 있어서다.
+**여닫기는 사람 몫이 기본**이다 — 결과물이 나오는 순간 패널까지 저절로 열리기를 원하면
+**설정 → 미리보기 패널 → `패널 자동으로 열기`** 를 켠다(기본 꺼짐). 반대로 `읽어두기` 를 끄면
+아무것도 자동으로 하지 않는다 — 경로는 최근 칩에만 쌓이고 무엇을 볼지는 사람이 고른다.
+문서 안의 링크는 웹이면 브라우저로, 로컬 파일이면 이 패널에서 연다.
+
+**탭을 옮기면 패널도 그 탭 것으로 바뀐다** — 최근 칩과 `변경` 탭뿐 아니라 **본문도** 그 세션이
+마지막으로 보던 파일로 돌아간다. 아무것도 안 본 탭에서는 빈 화면이다. 옆에 남의 탭 문서가 떠 있으면
+그것이 지금 탭의 것이라고 착각하기 때문이다. 탭을 옮기는 것만으로 패널이 **열리지는 않는다** —
+닫혀 있으면 다음에 열 때 맞춰진다.
+
+**고쳐서 저장한다 — `✎`**
+
+읽기만 되면 오타 하나에도 에디터를 따로 열어야 하고, 그 왕복이 이 패널이 없애려던 것과 같다.
+`✎` 를 누르면 본문 자리가 편집기가 된다. `저장`(`Ctrl+S`) · `취소`(`Esc`).
+
+- 글자 파일(`md` · 코드 · 텍스트 · `csv`)만 편집한다. 이미지·바이너리에서는 버튼이 흐려진다.
+- **너무 큰 파일은 열지 않는다** (1.5MB 넘음). 보기는 앞부분만 읽어도 되지만 저장은 파일을 통째로
+  다시 쓰므로, 앞부분만 들고 저장하면 뒷부분이 사라진다. 그래서 전체를 읽을 수 있을 때만 연다.
+- **BOM 과 개행(CRLF/LF)을 원본 그대로 되돌린다.** 안 그러면 한 줄만 고쳐도 P4·git diff 가
+  파일 전체를 바뀐 것으로 본다.
+- 편집하는 동안에는 **아무도 화면을 덮지 못한다** — 파일 감시의 자동 재읽기도, 새 파일 따라가기도
+  비켜 간다. 그 사이 파일이 밖에서 바뀌었으면 저장할 때 한 번 더 묻는다(두 번째 누름이 덮어쓴다).
+- **읽기 전용 파일은 열자마자 알린다** (`읽기 전용` 표시). 다 쳐 놓고 저장할 때 알면 그 타이핑이
+  헛일이 되기 때문이다. 저장을 누르면 `읽기 전용이다 (P4 면 p4 edit 먼저) — 다시 누르면 속성을
+  풀고 저장한다` 로 한 번 막는다. **말없이 속성을 풀지 않는 이유** — 이 환경에서 읽기 전용의
+  정체는 대개 P4 에서 체크아웃하지 않은 파일이고, 체크아웃 없이 쓴 내용은 다음 `p4 sync` 에
+  조용히 덮인다.
+- 저장하지 않은 편집이 있으면 다른 파일이나 `변경` 탭으로 넘어가지 않는다.
+
+**찾는다 — `🔍` / `Ctrl+F`**
+
+대소문자를 가리지 않고 본문에서 찾아 표시하고, `Enter`(다음) · `Shift+Enter`(이전) 로 오간다.
+`Esc` 로 닫으면 표시만 걷히고 본문 글자는 그대로다. 편집 중이면 편집기 안에서 찾아 그 자리를
+선택한다. **`Ctrl+F` 는 패널 안에서만 듣는다** — 터미널의 `Ctrl+F`(less·vim)를 뺏지 않으려는 것이라,
+본문을 한 번 누른 뒤에 쓴다.
+
+패널 폭은 터미널과 닿는 경계선을 끌어 바꾼다. **패널을 열면 4:3 이 완화되고 터미널이 그만큼 좁아진다** —
+사이드바는 줄지 않는다. 울트라와이드에서는 패널을 열어도 4:3 이 그대로 유지된다.
+
+> 문서 안의 원문 HTML 은 **글자로만** 보여준다(태그로 만들지 않는다). 참조 링크(`[a][1]`)와 각주는 지원하지 않는다.
+
+### `변경` 탭 — 작업트리의 diff
+
+헤더 아래 `파일` / `변경` 스위치로 바꾼다. `변경` 은 그 탭의 작업 폴더에서 `git diff HEAD` 를 읽어
+
+- `3개 파일 · +716 -15` 요약과 파일 목록(상태 딱지 + `+N -M`). 파일명을 누르면 그 파일 diff 로 스크롤한다
+- 파일별 유니파이드 diff — 구/신 줄번호를 양쪽에 붙이고 추가·삭제·문맥·헝크를 색으로 가른다
+- 추적되지 않은 파일은 이름만 따로 (내용 diff 는 하지 않는다)
+
+를 보여준다. **에이전트를 가리지 않는 이유가 미리보기와 같다** — 근거가 훅이 아니라 git 작업트리라서
+누가 고쳤든 성립한다. 저장소가 아니거나 git 이 없거나 작업 폴더를 아직 모르면 그 사실을 한 줄로 알린다.
+
+#### 스테이지 · 커밋
+
+파일 줄 왼쪽의 딱지가 **스테이지 상태**다 — `unstaged` / `staged` / `both`(일부만 올라감) /
+`untracked` / `conflict`. 누르면 그 파일을 `git add` 하거나 되돌린다(`git reset`). 아래 줄에
+`staged N · unstaged M` 요약과 메시지 입력창, 커밋 버튼이 있다.
+
+**우발 커밋을 막는 네 겹 —**
+
+1. 메시지가 비어 있으면 버튼이 잠긴다
+2. 공백만 넣으면 거부하고 이유를 적는다
+3. 첫 누름은 커밋하지 않고 `커밋 확인` 으로 바뀐다(색도 경고색). **두 번째 누름**에 실행된다
+4. 확인 대기 중에 메시지를 고치면 그 대기가 풀린다 (다른 메시지로 잘못 커밋되지 않게)
+
+스테이지된 것이 없으면 커밋하지 않는다 — `git commit -a` 로 넓히지 않는다.
+
+> 작업 폴더는 **탭이 열릴 때의 cwd** 다. 셸에서 `cd` 로 옮겨도 Tabby 가 알려주는 값은 바뀌지 않으므로
+> (Windows 로컬 세션 실측), 다른 저장소를 보려면 그 폴더에서 새 탭을 연다.
+> `git` 은 상위 폴더로 올라가며 저장소를 찾는다 — 홈 디렉토리가 저장소면 아무 폴더에서나 그것이 잡힌다.
+
 ## 키
 
 | 키 | 동작 |
@@ -107,23 +355,92 @@ OS 토스트(`alertToast`)는 기본으로 꺼져 있다 — 켜면 토스트를
 | `Ctrl+Enter` / `Shift+Enter` | 줄바꿈 (`0x0A` 전송). `agentdeck-newline` |
 | `Ctrl+V` | 붙여넣기. 클립보드에 **이미지만** 있으면 텍스트 대신 이미지 붙여넣기 키를 앱에 넘긴다 — Claude Code·Codex 가 클립보드를 직접 읽는다. `agentdeck-paste` |
 | 우클릭 | 선택이 있으면 복사, 없으면 붙여넣기. 길게(기본 250ms) 누르면 컨텍스트 메뉴 |
+| `Ctrl+Shift+L` | 사이드바 목록에 포커스를 준다 / 같은 키로 터미널로 돌아온다. `agentdeck-focus-list` |
+| `Ctrl+W` | 지금 탭을 닫는다 — 터미널에서 누르면 **활성 탭**, 목록이 키보드를 가졌으면 **포커스 줄의 탭**. `keyboardNav` + `keyboardCloseTab` 이 켜져 있을 때만이고, 끄면 터미널의 앞 단어 지우기(`0x17`)로 그대로 흐른다 |
 | (미배정) | `agentdeck-toggle` — 사이드바/4:3 즉시 on-off |
 | (미배정) | `agentdeck-repair` — 화면 복구 |
+| (미배정) | `agentdeck-view` — 미리보기 패널 여닫기 (사이드바 `▤` 와 같다) |
+| (미배정) | `agentdeck-view-mode` — 패널의 `파일` / `변경` 모드 전환 |
 
 키 배정은 Tabby 설정 → 단축키의 `agentdeck-*` 항목에서 바꾼다.
-`Ctrl+V` 는 플러그인이 기동할 때 `agentdeck-paste` 에 넣고 순정 `hotkeys.paste` 에서는 뺀다(둘 다 있으면 두 번 붙는다).
-터미널 앱에 리터럴 `Ctrl+V`(0x16)를 보내야 하면 `claimCtrlV: false`.
+`Ctrl+V` 는 **핫키가 아니라 캡처 단계에서 한 번만** 처리한다. 그래서 기동할 때 순정 `hotkeys.paste` 와
+`agentdeck-paste` **양쪽에서** `Ctrl-V` 를 뺀다 — 핫키에 남겨 두면 Tabby 가 같은 키를 두 경로로 밀어 넣어
+한 번 눌러 두 번 붙는 일이 있었다(`docs/DEVELOPMENT.md` 에 원인).
+
+터미널 앱에 리터럴 `Ctrl+V`(0x16, quoted-insert)를 보내야 하면 `claimCtrlV: false`.
+그러면 우리도 잡지 않고 핫키에도 없으므로 xterm 이 0x16 을 그대로 PTY 로 흘린다 —
+**대신 그 상태에서는 `Ctrl+V` 붙여넣기 자체가 안 된다**(그게 이 설정의 목적이다).
+붙여넣기는 `Ctrl+Shift+V`·`Shift+Insert`(Tabby 순정) 또는 우클릭으로 한다.
+
+### 키보드로 사이드바 다루기
+
+`Ctrl+Shift+L` 로 목록에 들어간다. 마우스 없이 탭을 훑어보려고 만든 것이고, 규칙은 이렇다.
+
+| 키 | 하는 일 |
+|---|---|
+| `↑` `↓` | 줄 사이 이동. **활성 탭은 바뀌지 않는다** |
+| `Home` `End` | 첫 줄 / 마지막 줄 |
+| `Enter` | 탭 줄이면 그 탭으로 전환하고 키를 터미널에 돌려준다. 그룹 헤더면 접기/펴기 |
+| `Esc` | 검색어·필터가 걸려 있으면 **먼저 그것을 지운다**. 지울 게 없을 때 터미널로 나간다 |
+| `Tab` `Shift+Tab` | 검색창으로 |
+| `Ctrl+W` | 포커스 줄의 탭을 닫는다 (그룹 헤더에서는 아무 일도 하지 않는다). 목록 밖 — 터미널에서 누르면 활성 탭이다 |
+
+**포커스와 선택을 가른 이유** — 줄을 지날 때마다 탭이 바뀌면 그 탭의 출력이 화면을 덮고
+터미널 폭이 매번 다시 적용되어 화면이 튄다. 그러면 "어느 탭이었나" 를 훑어볼 수가 없다.
+그래서 `↑↓` 는 테두리(키보드 포커스)만 옮기고, 탭을 실제로 여는 것은 `Enter` 하나다.
+
+검색창과 목록은 `↓`(검색창 → 결과 첫 줄)와 `↑`(첫 줄 → 검색창)로 오간다.
+검색창의 `↑` 는 가로채지 않는다 — 한 줄 입력에서 `↑` 는 커서를 맨 앞으로 보내는
+편집 동작이고, 치던 검색어를 고칠 때 실제로 쓴다.
+
+포커스가 사이드바에 없는 동안에는 **키를 한 개도 가로채지 않는다**(리스너가 목록
+엘리먼트에 걸려 있어서 이벤트가 아예 오지 않는다). 그래도 끄고 싶으면 `keyboardNav: false`.
+
+`Ctrl+W` 만 예외다 — 그건 터미널에서도 받아야 하므로 **document 캡처 단계**에서 잡는다.
+대신 **닫을 탭이 정해졌을 때만** 키를 먹는다: 그룹 헤더에 포커스가 있거나 설정 화면 입력창이면
+그대로 흘린다. 핫키 테이블에 넣지 않은 이유도 그것이다 — Tabby 핫키는 등록만으로 키를 먹어서
+설정을 꺼도 터미널의 `Ctrl+W`(앞 단어 지우기)가 죽는다. 그 키를 그대로 쓰려면
+`keyboardCloseTab: false`(설정 창의 `Ctrl+W 로 탭 닫기`)로 끄면 되고 목록 조작은 남는다.
+닫기는 사이드바 `✕` 와 같은 경로라 돌아가는 프로세스가 있으면 Tabby 가 평소처럼 한 번 물어본다.
+
+### 한글 입력 — 조합 중인 음절이 커서를 따라가지 않게
+
+한글을 치다가 `Home` · `End` · `Shift+Enter` 를 누르면 **조합 중인 마지막 음절이 옮겨간 자리로 따라가는**
+문제가 있었다. 방향키만 멀쩡한데 그 차이가 원인이다 — xterm 은 자기 키 경로로 들어온 키에 대해서는
+조합을 **먼저 확정**하고 키를 보내지만, 그 경로를 거치지 않고 pty 에 바이트를 직접 쓰면
+(터미널 핫키·플러그인의 줄바꿈 전송) 확정이 `setTimeout` 으로 밀려 **바이트가 먼저, 음절이 나중**에 나간다.
+
+그래서 pty 에 쓰는 지점을 한 곳으로 모아, 쓰기 직전에 조합 상태를 보고
+
+- 조합 중이면 **조합이 끝나기를 기다렸다가** 쓴다
+- 확정 전송이 이미 예약돼 있으면 우리가 한 틱 물러난다
+- 상태를 못 읽으면 그냥 쓴다 (이 보정이 정상 입력을 막는 일은 없어야 한다)
+
+로 갈라 준다. 조합이 끝나지 않으면 0.4초 뒤에는 확정시키고 쓴다 — 입력이 안 나가는 것이 최악이다.
+
+> **왜 기다리나 (0.6.3).** 예전에는 조합 중이면 우리가 확정을 재촉하고 바로 썼다. 그런데 우리가
+> 확정시켜도 IME 는 자기 일정대로 확정을 한 번 더 알리고, 그때 음절이 **또** 나간다 — 그 두 번째가
+> 개행 뒤에 붙어 **문자가 새 줄로 내려갔다.** 지금은 IME 의 순서를 건드리지 않으므로 음절이 한 번만,
+> 개행보다 먼저 나간다.
+
+끄려면 `imeOrderGuard: false`.
 
 ### 화면 복구 (`↻`)
 
 statusline 이 사라지거나 입력창 구분선이 화면 중간에서 끊기는 등 화면이 깨졌을 때 누른다.
-폭 재계산 → pty 크기 동기화 → 터미널 상태 초기화 → 앱에 전체 재렌더 요청(`Ctrl+L`) 순으로 진행한다.
-기본값은 스크롤백을 보존한다(`repairHard: false`). 잔상까지 지우려면 `repairHard: true`.
+폭 재계산 → pty 크기 동기화 → **입력창 자리의 잔상만** 지우기 → 흔들어 SIGWINCH 주기 순으로 진행한다.
+지운 자리는 앱이 자기 렌더 주기에 다시 그린다.
+
+**보고 있던 화면은 지우지 않는다.** 예전에는 마지막에 `Ctrl+L` 을 보내 "전부 다시 그려라" 를 시켰는데,
+Claude Code 는 그걸 **화면 지우기**로 받아 대화가 통째로 스크롤백으로 밀려났다
+(2026-09-11 채증: 정상 화면을 복구했더니 78행 중 0~72행이 비고 입력창만 남았다).
+그래서 `repairSendRedrawKey` 는 기본으로 꺼져 있다 — 실제로 고치는 것은 잔상 지우기와 크기 정합이라
+없어도 복구된다. 스크롤백까지 비우는 `repairHard: true` 도 기본은 꺼져 있다.
 
 ## 설정
 
 **설정 창(설정 → AgentDeck)** 에는 실제로 바꿀 일이 있는 것만 있다 — 레이아웃 on/off, 마우스로 바꾼 배치 초기화,
-기동 시 탭 복원 끄기, Claude Code 훅 설치/제거, 작업 루트 프로필. 나머지는 Tabby 설정 파일(`%APPDATA%\tabby\config.yaml`)의
+기동 시 탭 복원 끄기, 미리보기 패널(열기 · 경로 자동 수집 · 새 파일 따라가기), Claude Code 훅 설치/제거, 작업 루트 프로필. 나머지는 Tabby 설정 파일(`%APPDATA%\tabby\config.yaml`)의
 `agentDeck` 아래에서 조절한다.
 
 | 키 | 기본값 | 설명 |
@@ -134,18 +451,38 @@ statusline 이 사라지거나 입력창 구분선이 화면 중간에서 끊기
 | `sidebarWidth` | `0` | 좌/우 도킹 시 폭(px). 0 = 화면비로 자동 계산 |
 | `sidebarHeight` | `200` | 상/하 도킹 시 높이(px) |
 | `sidebarMin` / `sidebarMax` | `200` / `560` | 자동 계산 폭의 범위(px). 넓은 모니터에서 정확히 4:3 을 원하면 `sidebarMax` 를 `창 너비 − 창 높이 × 4/3` 으로 |
+| `sortByStatus` | `false` | 급한 순서(승인대기 → 오류 → 한도 → 진행중 → 완료 → 대기)로 정렬한다. 켜면 **드래그 재정렬은 막힌다** — 옮겨도 다음 렌더에 제자리로 돌아가기 때문 |
+| `collapsedGroups` | `[]` | 접어 둔 그룹 키. 헤더를 누르면 여기 쌓인다. 설정 창의 `모두 펼치기` 로 비운다 |
+| `viewerOpen` | `false` | 미리보기 패널이 열려 있나. `▤` / `agentdeck-view` 로 토글하거나 **새 파일을 주워 저절로 열리면** 여기 남아 다음 기동에 복원된다. 열림을 사람이 켜 두는 값이 아니다 |
+| `viewerDock` | `right` | 패널이 붙는 방향 `left` / `right`. 사이드바와 같은 쪽이면 사이드바가 창 가장자리(바깥) |
+| `viewerWidth` | `420` | 패널 폭(px). 경계선 드래그로 바뀐다. 좁은 창에서는 `창폭 − 320 − 140` 까지만 |
+| `searchBox` | `true` | 사이드바에 검색 줄을 보인다. 끄면 걸려 있던 필터도 함께 지운다(감춰진 필터는 만들지 않는다) |
+| `keyboardNav` | `true` | `Ctrl+Shift+L` 로 목록에 들어가 `↑↓`·Enter·Esc 로 다룬다. 포커스가 사이드바에 없으면 아무 키도 가로채지 않으므로 켜 둬서 잃는 것이 없다 |
+| `keyboardCloseTab` | `true` | `Ctrl+W` 로 탭을 닫는다 — 터미널에서는 활성 탭, 목록이 키보드를 가졌으면 포커스 줄의 탭. `keyboardNav` 를 끄면 이 값과 무관하게 꺼진다. 끄면 `Ctrl+W` 가 터미널로 그대로 간다(셸의 앞 단어 지우기) |
+| `keyboardNavWrap` | `false` | 목록 끝에서 `↑↓` 가 반대쪽으로 감긴다. 끄면 끝에서 멈춘다 — "맨 아래에 왔다" 가 보이고 목록이 통째로 튀지 않는다. 끝↔끝은 Home/End 로 |
+| `viewerScrape` | `true` | 화면에 찍힌 파일 경로를 주워 최근 목록에 쌓는다. 끄면 끌어다 놓기·경로 입력만 |
+| `viewerDropOpen` | `ask` | 터미널 위에 파일을 끌어다 놓았을 때 — `ask` 물어본다 / `always` 패널에 띄운다 / `paste` 경로를 붙여넣는다 / `never` 개입하지 않는다(순정) |
+| `viewerPreload` | `true` | 에이전트가 만진 파일을 **닫혀 있는 동안에도** 패널에 얹어 둔다(최근 칩 + 다음에 열 때 띄울 파일). 끄면 아무것도 자동으로 하지 않는다. 설정 창의 `문서 패널에 읽어두기` |
+| `viewerAutoOpen` | `false` | 새 파일을 주우면 **닫힌 패널을 스스로 연다.** 기본 꺼짐 — 여닫기는 사람 몫이고, 내용은 위 `viewerPreload` 가 채워 둔다. 설정 창의 `패널 자동으로 열기` |
+| `viewerFollowMode` | `''` | (옛 값) 0.18.0 부터 위 토글 두 개로 갈랐다. `open`/`show`/`manual` 이 적혀 있으면 기동 때 한 번 두 토글로 옮기고 비운다 |
+| `viewerFollow` | `true` | (더 옛 값) 0.17.0 에 `viewerFollowMode` 로 옮겼다. `false` 였으면 마이그레이션이 `viewerPreload: false` 로 읽고 기본값으로 되돌린다 |
+| `viewerRecentMax` | `12` | 최근 목록에 남겨 두는 파일 수 |
+| `imeOrderGuard` | `true` | pty 에 바이트를 쓰기 전에 조합 중인 한글 음절을 먼저 확정한다 (아래 "한글 입력") |
+| `releaseHomeEnd` | `true` | Home / End 를 Tabby 핫키에서 걷어내 xterm 순정 경로로 돌려준다 |
 | `idleAfterMs` | `2500` | 이 시간 동안 출력이 없으면 `대기` 로 |
 | `autoDetect` | `true` | 출력·제목 패턴으로 상태 추론 |
 | `showElapsed` | `true` | 경과 시간 표시 |
 | `sortByStatus` | `false` | 사이드바 탭을 상태 우선순위(승인대기 → 오류 → 한도 도달 → 진행중 → 완료 → 대기)로 정렬한다. 같은 상태끼리는 탭 순서 유지. 끄면 순정 탭바와 같은 순서 |
+| `dragAutoScroll` | `true` | 줄을 끌 때 목록 끝에서 저절로 스크롤된다. 끄면 손을 뗀 뒤 스크롤하고 다시 끌어야 하지만, 그 대신 **맨 끝 줄 뒤에 놓는 조작이 미끄러지지 않는다** |
 | `keepRenderingWhenHidden` | `true` | 창이 가려져 있어도 사이드바를 갱신한다. 끄면 상태 변화가 최대 1분까지 늦게 보일 수 있다 |
+| `subagentCount` | `true` | 사이드바 줄에 도는 서브에이전트 개수를 보인다. 0 개면 아무것도 그리지 않으므로 켜 둬서 잃는 것이 없다. 끄면 대화 기록을 **읽지도 않는다** |
 | `enterAsLabel` | `true` | Enter 로 프롬프트를 보낼 때 입력창 원문을 작업 라벨로 삼는다 |
 | `labelAsTitle` | `true` | 사이드바 제목 줄에 탭 제목 대신 작업 라벨을 쓴다. Tabby 의 탭 제목 자체는 건드리지 않는다 |
 | `noTabRecovery` | `false` | 기동 시 지난 탭을 복원하지 않는다 — Tabby `recoverTabs` 를 false 로 강제. 복원되는 건 셸뿐이고 안의 Claude 세션은 죽어 있어 의미가 없다 (설정 창에서 켠다) |
 | `notifyChannel` | `true` | 훅이 보낸 상태를 받는 통로(로컬 TCP + 상태 파일). 훅을 설치하면 자동으로 켜진다 |
 | `notifyPort` | `47500` | 그 TCP 포트(127.0.0.1 전용). 물려 있으면 임의 포트로 물러나고 실제 번호는 `%LOCALAPPDATA%\tabby-agentdeck\port` 에 적힌다 |
 | `hookPromptDismissed` | `false` | 기동 시 뜨는 훅 설치 안내를 다시 띄우지 않는다 |
-| `claimCtrlV` | `true` | 기동 시 `agentdeck-paste` 에 `Ctrl-V` 를 넣고 순정 `hotkeys.paste` 에서는 뺀다 |
+| `claimCtrlV` | `true` | `Ctrl+V` 를 캡처 단계에서 직접 처리한다. 기동 시 `hotkeys.paste`·`agentdeck-paste` **양쪽에서** `Ctrl-V` 를 뺀다(두 번 붙는 것 방지). `false` 면 리터럴 0x16 이 앱으로 가고 **붙여넣기는 안 된다** |
 | `pasteImageWithCtrlV` | `true` | 클립보드에 이미지만 있으면 텍스트 붙여넣기 대신 이미지 붙여넣기 키를 보낸다 |
 | `imagePasteKey` | `alt-v` | 그때 보낼 키. `ctrl-v`(0x16) 는 Claude Code·Codex 둘 다, `alt-v`(ESC v) 는 Claude Code 전용 |
 | `claimRightClick` | `true` | 우클릭을 플러그인이 처리한다 (Tabby 의 `terminal.rightClick` 은 `off` 로) |
@@ -153,13 +490,13 @@ statusline 이 사라지거나 입력창 구분선이 화면 중간에서 끊기
 | `terminalOpacity` | `75` | 터미널 배경 불투명도(%). 100 미만이면 `tabby-background` 의 배경 이미지가 비친다. 100 = 순정 |
 | `sidebarOpacity` | `75` | 사이드바 / 창 여백 불투명도(%) |
 | `clipBackgroundToTerminal` | `true` | `tabby-background` 이미지를 터미널 영역으로 잘라 사이드바 밑까지 비치지 않게 한다 |
-| `screenWatch` | `true` | 2초마다 화면이 깨졌는지 판정해 `~/.agentdeck-screen.log` 에 기록만 한다 (복구는 하지 않음) |
+| `screenWatch` | `true` | 2초마다 화면이 깨졌는지 판정해 `~/.agentdeck-screen.log` 에 기록만 한다 (복구는 하지 않음). 4MB 를 넘으면 `.1` 로 밀린다 |
 | `autoRepairScreen` | `false` | 깨졌다고 판정되면 조용히 화면 복구까지 한다 |
 | `autoRepairMinStreak` | `2` | 깨짐이 이만큼 연속으로 보여야 복구한다 (그리는 도중의 중간 프레임 오탐 방지) |
 | `autoRepairCooldownMs` | `10000` | 자동 복구 후 이만큼은 다시 하지 않는다 |
 | `autoRepairMaxPerTab` | `3` | 한 탭에서 자동 복구 최대 횟수. 0 = 무제한 |
 | `repairHard` | `false` | 화면 복구가 `xterm.reset()` 까지 한다 (스크롤백도 지워진다) |
-| `repairSendRedrawKey` | `true` | 화면 복구 마지막에 `Ctrl+L` 을 보내 전체 재렌더를 시킨다 |
+| `repairSendRedrawKey` | `false` | 화면 복구 마지막에 `Ctrl+L` 을 보낸다. **끄는 것이 기본** — Claude Code 는 이걸 재렌더가 아니라 **화면 지우기**로 받아 보고 있던 대화를 스크롤백으로 밀어낸다 (2026-09-11 채증). 켜면 자동 복구에도 적용된다 |
 | `rootProfile` | `false` | 작업 루트 프로필을 만들어 기본 프로필로 삼는다 (설정 창에서 켠다) |
 | `rootProfileName` | `Agent Root` | 그 프로필 이름 |
 | `rootProfileCwd` | `''` | 새 탭이 열릴 경로. 비우면 프로필을 만들지 않는다. 슬래시로 적는다 (예: `D:/Project`) |
@@ -170,6 +507,27 @@ statusline 이 사라지거나 입력창 구분선이 화면 중간에서 끊기
 | `alertBadge` | `true` | 작업표시줄 아이콘 위에 `승인대기`+`오류`+`한도 도달` 탭 개수를 뱃지(원+숫자)로 얹는다. 0 이면 지운다 |
 | `alertToast` | `false` | 그때 OS 토스트도 띄운다. 누르면 창을 앞으로 가져오고 그 탭을 고른다 |
 
+## 문제 신고
+
+버그를 만났으면 **설정 → AgentDeck → 문제 신고 → `모으기`** 를 누른다.
+진단 로그를 zip 하나로 묶고 그 파일이 있는 폴더를 열어 주므로, 그 zip 을 이슈에 붙이면 된다.
+
+담기는 것
+
+| 파일 | 내용 |
+|---|---|
+| `report.txt` | 플러그인/Tabby/Electron 버전, OS, 설정 값(도킹·화면비·`useConPTY` 등), 이 세션의 최근 진단 200줄 |
+| `agentdeck-diag.log` | `~/.agentdeck-diag.log` — 세션 머리말, 배치·입력·pty 판정, 잡히지 않은 예외와 스택, 삼켜진 실패(`CATCH …`) |
+| `agentdeck-diag.log.1` | 그 직전 분량 (2MB 를 넘겨 밀려난 것) |
+| `agentdeck-screen.log` | **"화면 원문까지 넣기" 를 켤 때만.** 깨진 순간의 터미널 화면이 글자 그대로 들어간다 |
+
+알아 둘 것
+
+- 로그는 **기동해도 지워지지 않는다.** 2MB 를 넘길 때 `.1` 로 한 세대 밀리므로, 어제 겪은 문제도 대개 남아 있다.
+- 로그에는 **탭 제목과 열어 본 파일 경로**가 들어간다. 보내기 전에 열어 봐도 되고, 화면 원문은 기본으로 빠진다.
+- 설정 창을 열 수 없을 만큼 깨졌으면 devtools 콘솔에서 `__agentdeck.collectDiag()` — 같은 zip 을 만들고 경로를 돌려준다.
+  최근 진단 줄만 보려면 `__agentdeck.kickLog`.
+
 ## 알려진 문제
 
 ### Tabby 1.0.235 에서 새 탭이 열리지 않음