claude-token-saver 3.27.1 → 3.28.0

package/README.en.md

@@ -4,23 +4,26 @@
 
 # claude-token-saver
 
-**Moves the easy work your expensive model keeps repeating onto cheaper ones, and shows what that actually saved — measured, in your statusline.** Zero dependencies, one-line install.
+**Shows what it saved, on two lines.** It moves the easy work your expensive model keeps repeating onto cheaper ones, and turns documents the model cannot read into Markdown. Both figures are ledger entries rather than estimates, and whichever saved more takes the top line. Zero dependencies, one-line install.
 
-![statusline example — routing savings on row 1, diagnostics on row 2](./docs/statusline.png)
+![statusline example — routing savings on row 1, document conversion savings on row 2, diagnostics on row 3](./docs/statusline.png)
 
 ```bash
 npm i -g claude-token-saver
 ```
 
-## Three parts, working together
+## Four parts, working together
 
 | | What it does | Effect |
 |---|---|---|
 | 🔀 **Routing** | Delegates recurring easy work to cheaper models | Savings recorded per run in a ledger |
+| 📄 **Document conversion** | Turns pptx/xlsx/pdf/docx/fig into Markdown before the model reads them | **510,000 tokens** saved on one deck ([below](#-doc2md--documents-become-markdown-before-the-model-reads-them)) |
 | 🅷 **Harness** | Blocks the token-burning habits: unevidenced "done", skipped verification (5 principles) | **−18.6% cost** ([measured](#real-world-impact--beforeafter-report)) |
 | ⚙️ **Ratchet** | Freezes each error you hit into a rule | Same mistake stops recurring |
 
-One install sets up all three. The measured −18.6% comes from the harness and ratchet; routing savings sit on top of it.
+One install sets up all four. The measured −18.6% comes from the harness and ratchet; routing and conversion savings sit on top of it.
+
+The two savings figures are never added together, because they answer different questions. Routing says "the same work ran on a cheaper model". Conversion says "a file you could not read became readable, without pushing the original through the context window". The statusline gives each its own line and puts the larger one first.
 
 ## 🔀 The savings figure is a ledger entry, not an estimate
 
@@ -62,7 +65,6 @@ By run (newest first):
 | 🚨 **No surprise rate limits** | Warns when the 5H/7D window hits 90%; `handoff` backs up your work |
 | 🧠 **Cache waste detection** | Hit rate, TTL, 1M-context detection — spikes diagnosed with issue codes |
 | 🇰🇷 **Korean writing guidance** | Offered at install time, defaulting to your locale ([below](#-korean-writing-guidance)) |
-| 📄 **Document conversion** | pptx/xlsx/pdf/docx become Markdown before the model reads them, so unreadable bytes never reach the context window ([below](#-doc2md--attached-documents-become-markdown-before-the-model-reads-them)) |
 
 ## Not a router — 60 seconds
 
@@ -378,7 +380,7 @@ Installs with nobody attached — npm `postinstall`, CI, piped stdin — skip th
 > The guidance text comes from [fluent-korean](https://github.com/snflkd/fluent-korean). Copyright (c) 2026 snflkd, MIT License.
 > The wording is unmodified; only the output-style frontmatter was removed. The full license ships with the package at `presets/korean-style/LICENSE-fluent-korean`.
 
-## 📄 doc2md — attached documents become Markdown before the model reads them
+## 📄 doc2md — documents become Markdown before the model reads them
 
 `Read` a pptx, xlsx, pdf or docx and the raw bytes go into the context window, where the model cannot read them. This intercepts that `Read`, converts the file once, and hands over the Markdown instead.
 
@@ -389,13 +391,13 @@ Three situations, three different interception points:
 | Situation | Where it is caught |
 |---|---|
 | A document path typed in the prompt (`@path`, quoted, or relative) | `UserPromptSubmit`: converted, and the conversion's path is handed back as context |
-| A document opened with `Read` mid-task | PDFs are caught by `PreToolUse(Read)`. pptx/xlsx/docx are not: Claude Code refuses them as binary *before* any hook runs, so the session-start note tells the model to run `doc2md <path>` instead |
+| A document opened with `Read` mid-task | PDFs are caught by `PreToolUse(Read)`. pptx/xlsx/docx/fig are not: Claude Code refuses them as binary *before* any hook runs, so the session-start note tells the model to run `doc2md <path>` instead |
 | A document attached to the message | **Not catchable.** No hook event receives attachment content. The session-start note has the model ask for a path next time |
 
 That second row is measured, not assumed: a `.pdf` Read fires the hook, and a `.pptx` Read in the same session leaves no hook log entry at all.
 
 ```bash
-claude-token-saver doc2md install-converter   # markitdown into a dedicated venv
+claude-token-saver doc2md install-converter   # markitdown + editing libs + the .fig parser
 claude-token-saver doc2md on                  # register the Read hook
 claude-token-saver doc2md                     # check converter + hook registration
 claude-token-saver doc2md report.pptx         # convert by hand and see the result
@@ -413,6 +415,46 @@ Several things it deliberately does not do:
 - **Zip bombs are refused.** pptx/xlsx/docx are zip containers: the declared sizes are checked first, and since those are written by whoever built the file, the real decompressed bytes are counted against a ceiling too.
 - **Spreadsheets are capped by rows, not bytes.** Conversion time tracks row count (measured: a 6.3MB PDF in 0.9s, a 5.8MB workbook in 47.75s). Past 50,000 rows only the head is converted, and **the truncation and the true row count are both stated** in what the model is told.
 
+### What a conversion saves
+
+Every conversion is stamped with a provenance header: which original, when, how many tokens. Savings show up on the statusline's own `📄 Doc2md saved` line.
+
+The baseline is what you would have done without a converter, and that differs by format. Both were measured on 2026-09-06.
+
+**PDF is priced against attaching it.** The same one-line prompt was sent through `claude --print --input-format stream-json` with and without the file as a document block. The control turn cost 42,204 tokens, twice, to the token.
+
+| Attached file | Size | Extra tokens | Per page |
+|---|---|---|---|
+| Résumé PDF | 7 pages | +20,537 | 2,934 |
+| Résumé PDF | 5 pages | +12,709 | 2,542 |
+
+An attached PDF is read whole, but every page costs 2,500–2,900 tokens against 5,531 for the conversion. The coefficient used is 2,500 per page — below both measurements, so the figure understates rather than flatters.
+
+**pptx/xlsx/docx are priced against unpacking the container.** These never reach the model as attachments at all: the same probe on a docx added 78 tokens and the model replied that it had no file, and `Read` refuses the format outright. What you actually do without a converter is unzip the archive and read its XML, where tags and style attributes outweigh the words.
+
+| Original | Body XML | Conversion | Ratio |
+|---|---|---|---|
+| Deck, pptx (31.8MB) | ~540,429 tokens | ~22,610 tokens | 23.8× |
+| Résumé, docx (189KB) | ~79,621 tokens | ~1,684 tokens | 47.3× |
+
+This baseline is measured per file from the real XML size, not applied as a per-format ratio. `.xls` is not a zip container and has no markup to measure, so it claims nothing.
+
+### Figma `.fig` converts too
+
+Planning documents are moving from PowerPoint to Figma, so the same hook catches `.fig`. A `.fig` is a zip, but the `canvas.fig` inside it is Figma's private binary (kiwi format), which markitdown cannot open — so this one format is converted in Node with [openfig-core](https://github.com/OpenFig-org/openfig-core) (MIT). `doc2md install-converter` places it beside markitdown in the tool's state directory; the package itself still ships zero dependencies.
+
+The result is an outline: pages and frames become headings, text nodes become body lines, and shapes are counted rather than listed — in a planning document the words are the content, and two hundred `Rectangle 173` lines would drown them. A file with no text at all is refused rather than dressed up as an empty document.
+
+Verified against real files: a community Bootstrap UI kit (8.1MB, 4,155 nodes, 1,312 of them text) and a 52MB Tailwind kit, each converting in under a second. Both `.fig` vintages parse — the current zip container and the older bare fig-kiwi stream. No savings are claimed: a `.fig` unzips to another binary, so there is no readable fallback to price against.
+
+### Editing a document: copy, then script
+
+Conversion is one-way — editing the cached `.md` changes nothing in the source. The hook refuses `Edit`/`Write` on both the cache and the original binary, and points at the right path instead: copy the original, edit the copy with a script, re-convert the copy to verify.
+
+`install-converter` puts the editing libraries (python-pptx, python-docx, openpyxl) in the same venv, so a structural request like "swap the chart on slide 23 for a line chart" is a short script the agent writes on the spot. `.fig` edits go through openfig-core, which encodes as well as parses.
+
+All four formats were exercised end to end on 2026-09-06: 10 docx run replacements plus three consecutive re-saves, a pptx bar-to-line chart swap with an added data point, xlsx value edits and a new row, and a fig text edit with re-encode and re-parse. In every case the original was byte-identical afterwards and the re-converted copy showed the change. One caveat: removing a chart shape from a pptx leaves the old chart XML part orphaned — PowerPoint ignores it, but delete the part and its rels for a clean file. Charts and images never appear in a conversion, so visual edits must be confirmed in the application itself.
+
 `claude-token-saver doc2md --clean` empties the conversion cache; `doc2md off` removes the hook. Removal filters for this tool's own entry, so anything else you registered under `PreToolUse` stays.
 
 ## 🌐 Behind a gateway (Bedrock / Vertex)
@@ -523,7 +565,7 @@ Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-s
 - **An unknown subcommand under `--hook` prints nothing.** A 3.25.0 global install meeting a settings.json written by 3.26.0 did not recognise `doc2md`, fell through to the default report, and pushed a full statistics table into the hook stream on every `Read`.
 
 ### v3.26.0 (2026-09-04)
-- **Attached documents are converted to Markdown before the model reads them.** Reading a pptx/xlsx/pdf/docx put unreadable bytes into the context window. `doc2md on` registers a `Read` hook that converts the file once, caches it outside your project, and points the model at the Markdown. A missing converter is announced once and then gets out of the way, zip bombs are refused, and workbooks past 50,000 rows are converted head-first with the truncation stated. See [doc2md](#-doc2md--attached-documents-become-markdown-before-the-model-reads-them).
+- **Attached documents are converted to Markdown before the model reads them.** Reading a pptx/xlsx/pdf/docx put unreadable bytes into the context window. `doc2md on` registers a `Read` hook that converts the file once, caches it outside your project, and points the model at the Markdown. A missing converter is announced once and then gets out of the way, zip bombs are refused, and workbooks past 50,000 rows are converted head-first with the truncation stated. See [doc2md](#-doc2md--documents-become-markdown-before-the-model-reads-them).
 - **TTL display fixed for Bedrock/Vertex sessions.** Gateways never report the per-bucket split, and the fallback assumed an hour — twelvefold too long for a 5-minute-only backend. The gateway is now detected from the model ids, the fallback follows that evidence, and the label reads `5m?` to mark it as inferred. Pin it manually with `mode ttl=5m` if the detection is wrong.
 - **Delegated runs are no longer discarded in silence.** Runs excluded for an unpriceable model id surface as `🔀 N unresolved` on the statusline; previously that was indistinguishable from never having delegated, so an entire tier of rules could report zero with no way to find out why. Environment variables set to a `foundation-model` ARN now resolve as well.
 - **The Korean guidance stopped contradicting itself.** The injected scope claimed code comments while the vendored text disclaimed them twice, leaving the model nothing to decide on. The vendored wording is untouched; the block now states which side wins. The em dash in the attribution line — a mark that guidance itself forbids — became a colon.

package/README.md

@@ -4,23 +4,26 @@
 
 # claude-token-saver
 
-**비싼 모델이 반복하던 쉬운 작업을 싼 모델로 내려보내고, 그렇게 아낀 금액을 statusline에 실측으로 보여 줍니다.** 의존성 0, 설치 한 줄.
+**아낀 돈을 두 줄로 보여 줍니다.** 비싼 모델이 반복하던 쉬운 작업을 싼 모델로 내려보내고, 모델이 읽지 못하는 문서를 Markdown 으로 바꿉니다. 두 절감액 모두 추정이 아니라 원장 기록이고, 더 많이 아낀 쪽이 첫 줄을 차지합니다. 의존성 0, 설치 한 줄.
 
-![statusline 예시. 첫째 줄은 라우팅 절감액이고 둘째 줄은 진단 칩입니다](./docs/statusline.png)
+![statusline 예시. 첫 줄은 라우팅 절감액, 둘째 줄은 문서 변환 절감액, 셋째 줄은 진단 칩입니다](./docs/statusline.png)
 
 ```bash
 npm i -g claude-token-saver
 ```
 
-## 세 가지가 함께 돌아갑니다
+## 네 가지가 함께 돌아갑니다
 
 | | 하는 일 | 효과 |
 |---|---|---|
 | 🔀 **라우팅** | 반복되는 쉬운 작업을 더 싼 모델에 위임 | 절감액을 원장에 실측 기록 |
+| 📄 **문서 변환** | pptx·xlsx·pdf·docx·fig 를 읽기 전에 Markdown 으로 변환 | 발표자료 한 건에 **51만 토큰** 절약 ([아래](#-doc2md-문서를-읽기-전에-markdown-으로-바꿉니다)) |
 | 🅷 **Harness** | 증거 없는 완료 보고·검증 생략 차단 (5원칙) | **비용 −18.6%** ([실측](#실제-효과-도입-전후-리포트)) |
 | ⚙️ **Ratchet** | 한 번 겪은 에러를 룰로 고정 | 같은 실수 재발 차단 |
 
-설치 한 번이면 셋 다 적용됩니다. 실측 −18.6%는 Harness와 ratchet의 몫이고, 라우팅 절감액은 그 위에 얹힙니다.
+설치 한 번이면 넷 다 적용됩니다. 실측 −18.6%는 Harness와 ratchet의 몫이고, 라우팅과 문서 변환 절감액은 그 위에 얹힙니다.
+
+두 절감액은 성격이 달라서 한 숫자로 합치지 않습니다. 라우팅은 "같은 일을 더 싼 모델이 했다"이고, 문서 변환은 "읽을 수 없던 파일을 읽었고 그 과정에서 원본을 통째로 밀어 넣지 않았다"입니다. statusline 은 둘을 각각의 줄로 보여 주고, 금액이 큰 쪽을 위에 놓습니다.
 
 ## 🔀 절감액은 추정이 아니라 원장 기록입니다
 
@@ -62,7 +65,6 @@ $ claude-token-saver route-scan savings      # 모든 금액을 룰 단위까지
 | 🚨 **한도 초과 예방** | 5시간·7일 rate-limit 윈도가 90%에 닿으면 경고하고, `handoff`로 작업을 백업합니다 |
 | 🧠 **캐시 낭비 감지** | 히트율·TTL·1M 컨텍스트를 감지해 토큰 급증 원인을 코드로 진단합니다 |
 | 🇰🇷 **한국어 문체 교정** | 한국어 환경이면 자동으로 켜집니다 ([아래](#-한국어-문체-지침)) |
-| 📄 **문서 자동 변환** | pptx·xlsx·pdf·docx 를 읽기 전에 Markdown 으로 바꿔 읽지 못하는 바이트가 컨텍스트에 올라가지 않게 합니다 ([아래](#-doc2md-첨부-문서를-읽기-전에-markdown-으로-바꿉니다)) |
 
 ## 라우터가 아닙니다: 60초 설명
 
@@ -368,9 +370,11 @@ npm의 `postinstall`이나 CI처럼 사람이 붙어 있지 않은 설치에서
 > 지침 원문은 [fluent-korean](https://github.com/snflkd/fluent-korean)에서 가져왔습니다. Copyright (c) 2026 snflkd, MIT License.
 > 원문은 수정하지 않았고 output style 프런트매터만 제거했습니다. 라이선스 전문은 패키지의 `presets/korean-style/LICENSE-fluent-korean`에 함께 배포합니다.
 
-## 📄 doc2md: 첨부 문서를 읽기 전에 Markdown 으로 바꿉니다
+## 📄 doc2md: 문서를 읽기 전에 Markdown 으로 바꿉니다
+
+기획서와 보고서는 대부분 pptx·xlsx·pdf·docx·fig 로 옵니다. 이 형식들을 그대로 다루면 두 가지 중 하나가 일어납니다. Claude Code 가 이진 파일이라며 거부해서 아무것도 못 읽거나, 압축을 풀어 본문 XML 을 읽느라 토큰을 태우거나. 30MB 짜리 발표자료 하나가 XML 로는 **54만 토큰**이고, 200k 컨텍스트에는 들어가지도 않습니다.
 
-pptx·xlsx·pdf·docx 를 그대로 `Read` 하면 모델이 읽지 못하는 바이트가 컨텍스트에 그대로 올라갑니다. 이 기능은 그 `Read` 를 가로채 파일을 한 번 변환해 두고, 원본 대신 변환본을 읽게 합니다.
+doc2md 는 그 파일을 한 번 변환해 두고 원본 대신 변환본을 읽게 합니다. 같은 발표자료가 22,610 토큰이 됩니다.
 
 **이 기능은 옵트인입니다.** 설치만으로는 켜지지 않고, 아래 두 명령을 모두 실행해야 동작합니다. 훅만 등록하고 변환기가 없으면 아무 일도 일어나지 않습니다.
 
@@ -385,7 +389,7 @@ pptx·xlsx·pdf·docx 를 그대로 `Read` 하면 모델이 읽지 못하는 바
 두 번째 줄의 제약은 실측으로 확인한 것입니다. `.pdf` 를 Read 하면 훅이 실행되고, 같은 세션에서 `.pptx` 를 Read 하면 훅 로그에 아무 기록도 남지 않습니다.
 
 ```bash
-claude-token-saver doc2md install-converter   # 전용 venv에 markitdown 설치
+claude-token-saver doc2md install-converter   # markitdown·편집 라이브러리·.fig 파서 설치
 claude-token-saver doc2md on                  # Read 훅 등록
 claude-token-saver doc2md                     # 변환기·훅 등록 상태 확인
 claude-token-saver doc2md 보고서.pptx          # 직접 변환해 결과 확인
@@ -403,6 +407,50 @@ claude-token-saver doc2md 보고서.pptx          # 직접 변환해 결과 확
 - **압축 폭탄은 막습니다.** pptx·xlsx·docx 는 zip 컨테이너입니다. 선언된 크기를 먼저 걸러 내고, 선언은 조작될 수 있으므로 실제 해제 바이트도 상한과 대조합니다.
 - **엑셀은 행 수로 자릅니다.** 변환 시간은 파일 크기가 아니라 행 수를 따릅니다(실측: PDF 6.3MB 0.9초, 엑셀 5.8MB 47.75초). 5만 행을 넘으면 앞부분만 변환하고, **잘랐다는 사실과 전체 행 수를 안내에 함께 적습니다.**
 
+### 변환이 얼마를 아끼는지
+
+변환본은 첫머리에 출처 주석을 답니다. 어떤 원본을 언제 변환했고 몇 토큰인지가 파일을 여는 순간 보입니다. 절감액은 스테이터스라인의 절감 줄 끝에 `📄 Doc2md saved` 로 붙습니다.
+
+절감액의 기준은 변환기가 없을 때 실제로 하게 되는 일이고, 그 일이 형식마다 다릅니다. 두 경우 모두 2026-09-06 에 실측했습니다.
+
+**PDF 는 첨부와 비교합니다.** `claude --print --input-format stream-json` 으로 같은 한 줄 프롬프트를 첨부 있이·없이 보내고 입력 토큰을 비교했습니다. 대조군은 42,204 토큰이었고 두 번 반복해 값이 같았습니다.
+
+| 첨부 파일 | 분량 | 첨부가 더 든 토큰 | 페이지당 |
+|---|---|---|---|
+| 이력서 PDF | 7페이지 | +20,537 | 2,934 |
+| 이력서 PDF | 5페이지 | +12,709 | 2,542 |
+
+PDF 는 첨부하면 모델이 내용을 그대로 읽습니다. 대신 페이지마다 2,500~2,900 토큰이 붙어서, 변환본(5,531 토큰)의 서너 배가 듭니다. 계수는 두 실측치보다 낮은 페이지당 2,500 을 씁니다. 넉넉히 잡아 부풀리는 것보다 낮게 잡아 밑도는 편이 낫습니다.
+
+**pptx·xlsx·docx 는 압축을 푸는 경우와 비교합니다.** 이 형식들은 애초에 첨부로 모델에 닿지 않습니다. 같은 방식으로 docx 를 보냈더니 78 토큰만 늘었고 모델은 파일이 없다고 답했으며, `Read` 도 이진 파일이라며 거부합니다. 그래서 변환기가 없을 때 실제로 하게 되는 일은 압축을 풀고 본문 XML 을 읽는 것입니다. 태그와 스타일 속성이 글자 수의 대부분을 차지하는 그 XML 말입니다.
+
+| 원본 | 본문 XML | 변환본 | 차이 |
+|---|---|---|---|
+| 발표자료 pptx (31.8MB) | 약 540,429 토큰 | 약 22,610 토큰 | 23.8배 |
+| 이력서 docx (189KB) | 약 79,621 토큰 | 약 1,684 토큰 | 47.3배 |
+
+30MB 짜리 발표자료 하나가 XML 로는 54만 토큰입니다. 200k 컨텍스트에는 들어가지도 않습니다. 이 기준은 형식별 계수가 아니라 파일마다 실제 XML 크기를 재서 씁니다.
+
+`.xls` 는 zip 컨테이너가 아니라 재어 볼 마크업이 없으므로 절감을 0 으로 둡니다.
+
+클라이언트 동작이 바뀌면 `scripts/doc2md-baseline.mjs` 로 첨부 쪽을 다시 재고, `src/doc2md-ledger.cjs` 의 `ATTACHMENT_BASELINE` 표에 값만 갈아 끼우면 됩니다.
+
+### 피그마 `.fig` 도 변환합니다
+
+기획서가 PPT 에서 피그마로 옮겨 가는 추세를 따라, `.fig` 파일도 같은 훅이 잡습니다. `.fig` 는 zip 컨테이너지만 안에 든 `canvas.fig` 가 피그마의 비공개 바이너리(kiwi 포맷)라 markitdown 이 열지 못하므로, 이 형식만 Node 파서([openfig-core](https://github.com/OpenFig-org/openfig-core), MIT)로 변환합니다. `doc2md install-converter` 가 markitdown 과 함께 도구 상태 디렉터리에 설치하며, 패키지 자체는 여전히 무의존성입니다.
+
+변환 결과는 페이지·프레임 계층을 헤딩으로, 텍스트 노드를 본문으로 정리한 아웃라인입니다. 도형·벡터 같은 시각 요소는 나열하지 않고 개수만 남깁니다. 기획서에서 내용은 글이고, `Rectangle 173` 이 이백 줄 나오면 글이 묻히기 때문입니다. 텍스트가 하나도 없는 파일(순수 그래픽)은 빈 문서로 꾸미지 않고 변환 불가로 알립니다.
+
+실제 파일로 검증했습니다: 피그마 커뮤니티의 Bootstrap UI kit(8.1MB, 노드 4,155개, 텍스트 1,312개)와 Tailwind kit(52MB)이 각각 0.2초 안에 71.9KB·44KB 아웃라인으로 변환됐고, 한국어 텍스트 왕복도 무손실이었습니다. `.fig` 는 두 세대가 있습니다. 요즘 익스포트는 zip 컨테이너, 옛 익스포트는 fig-kiwi 바이너리 원형인데 둘 다 처리합니다. 절감액은 청구하지 않습니다. `.fig` 는 압축을 풀어도 또 바이너리라 비교할 대안 자체가 없고, 변환이 유일한 읽기 경로입니다.
+
+### 문서를 수정해야 할 때: 복사본 + 스크립트
+
+변환은 단방향이라 변환본 .md 를 고쳐도 원본에는 반영되지 않습니다. 훅이 변환 캐시와 원본 이진 파일에 대한 Edit/Write 를 거부하면서 올바른 경로를 안내합니다. 원본을 복사하고, 복사본을 스크립트로 수정하고, 수정본을 doc2md 로 재변환해 검증하는 순서입니다.
+
+`install-converter` 가 편집 라이브러리(python-pptx·python-docx·openpyxl)를 변환기 venv 에 함께 설치하므로, "23번 슬라이드 차트를 꺾은선으로 바꿔줘" 같은 구조 편집도 에이전트가 그 자리에서 스크립트로 처리할 수 있습니다. `.fig` 는 openfig-core 가 인코더까지 제공해 텍스트 수정 후 재인코드가 됩니다.
+
+네 형식 모두 실제로 몇 바퀴 돌려 검증했습니다(2026-09-06): docx 텍스트 치환 10건과 3회 연속 재저장, pptx 막대→꺾은선 차트 교체와 데이터 행 추가, xlsx 값 정정·행 추가, fig 텍스트 수정·재인코드·재파싱. 전 케이스에서 원본은 바이트 그대로였고, 수정본 재변환에 변경 내용이 반영됐습니다. 한 가지 주의: pptx 에서 차트 도형을 제거하면 옛 차트 XML 파트가 고아로 남습니다. PowerPoint 는 무시하지만, 깔끔히 하려면 파트와 rels 도 지우십시오. 차트·이미지 같은 시각 요소는 변환본에 잡히지 않으므로, 시각 편집의 최종 확인은 해당 프로그램에서 해야 합니다.
+
 `claude-token-saver doc2md --clean` 으로 변환 캐시를 비우고, `doc2md off` 로 훅을 제거합니다. 훅 해제는 자기 항목만 골라 지우므로 `PreToolUse` 에 등록해 둔 다른 훅은 그대로 남습니다.
 
 ## 🌐 Bedrock·Vertex 경유 환경
@@ -489,7 +537,7 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 - **모르는 서브커맨드를 `--hook` 으로 부르면 아무것도 출력하지 않습니다.** 3.25.0 전역 설치본이 3.26.0 이 쓴 `settings.json` 을 만나면 `doc2md` 를 인식하지 못하고 기본 리포트로 흘러가, `Read` 할 때마다 통계 표 전문을 훅 스트림에 밀어 넣었습니다.
 
 ### v3.26.0 (2026-09-04)
-- **첨부 문서를 읽기 전에 Markdown 으로 변환합니다.** pptx·xlsx·pdf·docx 를 그대로 `Read` 하면 모델이 읽지 못하는 바이트가 컨텍스트에 올라갑니다. `doc2md on` 으로 `Read` 훅을 등록하면 파일을 한 번 변환해 캐시에 두고 변환본을 읽게 합니다. 변환기가 없으면 안내를 한 번만 하고 원본 `Read` 를 통과시키며, 압축 폭탄은 막고, 5만 행이 넘는 엑셀은 앞부분만 변환한 뒤 잘랐다는 사실을 함께 알립니다. 자세한 내용은 [doc2md](#-doc2md-첨부-문서를-읽기-전에-markdown-으로-바꿉니다) 절을 참고하십시오.
+- **문서를 읽기 전에 Markdown 으로 변환합니다.** pptx·xlsx·pdf·docx·fig 를 그대로 `Read` 하면 모델이 읽지 못하는 바이트가 컨텍스트에 올라갑니다. `doc2md on` 으로 `Read` 훅을 등록하면 파일을 한 번 변환해 캐시에 두고 변환본을 읽게 합니다. 변환기가 없으면 안내를 한 번만 하고 원본 `Read` 를 통과시키며, 압축 폭탄은 막고, 5만 행이 넘는 엑셀은 앞부분만 변환한 뒤 잘랐다는 사실을 함께 알립니다. 자세한 내용은 [doc2md](#-doc2md-문서를-읽기-전에-markdown-으로-바꿉니다) 절을 참고하십시오.
 - **Bedrock·Vertex 경유 환경의 TTL 표시를 바로잡았습니다.** 게이트웨이는 버킷별 분해 값을 내려보내지 않는데, 판정 불가일 때 1시간을 기본값으로 잡고 있었습니다. 5분 버킷만 제공하는 환경에서 남은 시간이 최대 12배로 부풀어 보였습니다. 이제 모델 ID로 게이트웨이를 감지해 5분을 기본값으로 쓰고, 라벨을 `5m?` 로 적어 추정임을 밝힙니다. `mode ttl=5m` 으로 직접 지정할 수도 있습니다.
 - **위임 집계가 조용히 버려지지 않습니다.** 모델 ID를 해석하지 못해 제외된 위임이 있으면 statusline 에 `🔀 N unresolved` 로 알립니다. 이전에는 "위임한 적 없음"과 화면상 구별되지 않아, 집계가 통째로 사라져도 알 방법이 없었습니다. `foundation-model` ARN 으로 지정된 환경변수도 이제 해석합니다.
 - **한국어 지침의 적용 범위 충돌을 해소했습니다.** 주입문은 코드 주석을 검사 대상에 넣는데 벤더링한 원문은 두 번에 걸쳐 제외한다고 적고 있어서, 모델이 어느 쪽을 따를지 판단할 근거가 없었습니다. 원문은 그대로 두고 어느 쪽이 우선인지 명시하는 한 줄을 추가했습니다. 출처 표기에 들어 있던 엠대시도 지침 스스로 금지하는 표기였으므로 콜론으로 바꿨습니다.

package/bin/cli.js

@@ -534,6 +534,16 @@ async function main() {
   } catch (e) {
     debug('savings-ledger:totals', e);
   }
+  // Document conversions, same shape as the delegation totals: a lifetime sum
+  // plus a document count. A lookup of a small JSON file, never a scan.
+  let doc2mdTotals = null;
+  try {
+    const { doc2mdSavedTotals } = await import('../src/doc2md-ledger.cjs');
+    const { userDataDir } = await import('../src/paths.js');
+    doc2mdTotals = doc2mdSavedTotals(userDataDir());
+  } catch (e) {
+    debug('doc2md-ledger:totals', e);
+  }
   // Delegated runs route-scan had to throw away because their model id could
   // not be priced. Also a lookup of the cached scan, never a scan. Without it
   // the statusline shows the same blank for "no delegation happened" and for
@@ -574,6 +584,7 @@ async function main() {
     model,
     delegationSaved,
     delegationTotals,
+    doc2mdTotals,
     unresolvedRuns,
     ttlBucket,
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "3.27.1",
+  "version": "3.28.0",
   "description": "Route the easy work your expensive Claude model keeps repeating down to haiku/sonnet — post-hoc session analysis, no realtime router, no extra LLM calls.",
   "type": "module",
   "bin": {

package/presets/doc2md/convert.py

@@ -5,7 +5,8 @@ Invoked as a child process by src/doc2md.cjs. Everything it needs to say
 travels in the JSON on stdout, so the Node side never has to interpret a
 traceback:
 
-    {"ok": true,  "markdown": "...", "note": null, "truncated": false, "rows": 0}
+    {"ok": true,  "markdown": "...", "note": null, "truncated": false,
+     "rows": 0, "pages": 0, "markup_bytes": 0}
     {"ok": false, "reason": "no-text", "detail": "..."}
 
 Exit status is 0 whenever the JSON was written, including for a refusal. A
@@ -79,6 +80,53 @@ def check_zip(path):
     return None
 
 
+# Which entries inside a zip container hold the document's own text. The rest
+# of the archive is media, themes and relationship tables — bytes a reader
+# would never wade through even without a converter.
+BODY_XML = {
+    ".pptx": ("ppt/slides/", "ppt/notesSlides/"),
+    ".docx": ("word/document.xml", "word/footnotes.xml", "word/endnotes.xml"),
+    ".xlsx": ("xl/worksheets/", "xl/sharedStrings.xml"),
+}
+
+
+def markup_bytes(path, ext):
+    """Uncompressed size of the body markup inside a zip document, or 0.
+
+    This prices the alternative to converting. A model cannot read the binary,
+    so the fallback a reader actually reaches for is unzipping the container
+    and wading through its XML — where tags and style attributes outweigh the
+    text several times over.
+    """
+    prefixes = BODY_XML.get(ext)
+    if not prefixes:
+        return 0
+    try:
+        import zipfile
+        with zipfile.ZipFile(path) as z:
+            return sum(i.file_size for i in z.infolist()
+                       if i.filename.endswith(".xml")
+                       and any(i.filename.startswith(p) for p in prefixes))
+    except Exception:
+        return 0
+
+
+def pdf_pages(path):
+    """Page count of a PDF, or 0 when it cannot be counted.
+
+    The count is what prices the alternative to converting: attaching a PDF
+    to a message bills every page as an image, while the conversion bills
+    only the extracted text. pdfminer ships with markitdown's pdf extra, so
+    this costs no extra dependency.
+    """
+    try:
+        from pdfminer.pdfpage import PDFPage
+        with open(path, "rb") as fh:
+            return sum(1 for _ in PDFPage.get_pages(fh))
+    except Exception:
+        return 0
+
+
 def sheet_rows(path):
     """Total rows across every sheet, or None when openpyxl cannot say."""
     try:
@@ -149,6 +197,8 @@ def main():
     note = None
     truncated = False
     rows = 0
+    pages = pdf_pages(path) if ext == ".pdf" else 0
+    markup = markup_bytes(path, ext)
 
     if ext in (".xlsx", ".xls"):
         counted = sheet_rows(path)
@@ -161,7 +211,8 @@ def main():
             note = ("전체 %d행 가운데 앞 %d행만 변환했습니다. "
                     "전수 분석이 필요하면 원본을 직접 다루십시오." % (counted, ROW_CAP))
             json.dump({"ok": True, "markdown": text, "note": note,
-                       "truncated": True, "rows": counted}, sys.stdout)
+                       "truncated": True, "rows": counted, "pages": 0,
+                       "markup_bytes": markup}, sys.stdout)
             return
 
     try:
@@ -181,7 +232,8 @@ def main():
         fail("no-text", "converter returned nothing")
 
     json.dump({"ok": True, "markdown": text, "note": note,
-               "truncated": truncated, "rows": rows}, sys.stdout)
+               "truncated": truncated, "rows": rows, "pages": pages,
+               "markup_bytes": markup}, sys.stdout)
 
 
 if __name__ == "__main__":

package/src/commands/doc2md.js

@@ -48,7 +48,7 @@ export async function run({ args, hasFlag }) {
     if (!payload) return;
     let out = null;
     try {
-      out = doc2md.formatHookOutput(doc2md.decideForRead(payload));
+      out = doc2md.formatHookOutput(doc2md.decideForRead(payload) || doc2md.decideForWrite(payload));
     } catch {
       // A converter that throws must not take the Read down with it. Printing
       // nothing leaves Claude Code to run the tool call exactly as before.
@@ -62,10 +62,21 @@ export async function run({ args, hasFlag }) {
     const res = doc2md.installConverter({ onProgress: (m) => console.log(`  ${m}`) });
     if (res.ok) {
       console.log(`✓ converter ready: ${res.python}`);
-      return;
+    } else {
+      console.error(`✗ ${res.reason}: ${res.detail}`);
+      process.exitCode = 1;
+    }
+    // The .fig parser is a separate, Node-side install. A markitdown failure
+    // above must not block it — the two formats fail independently.
+    const fig2md = require('../fig2md.cjs');
+    const { userDataDir } = await import('../paths.js');
+    const figRes = fig2md.installFigParser(userDataDir(), { onProgress: (m) => console.log(`  ${m}`) });
+    if (figRes.ok) {
+      console.log('✓ .fig parser ready (openfig-core)');
+    } else {
+      console.error(`✗ .fig parser: ${figRes.reason}: ${figRes.detail || ''}`);
+      process.exitCode = 1;
     }
-    console.error(`✗ ${res.reason}: ${res.detail}`);
-    process.exitCode = 1;
     return;
   }
 

package/src/doc2md-ledger.cjs

@@ -0,0 +1,208 @@
+/**
+ * doc2md-ledger — one event per document conversion, with what it saved.
+ *
+ * Separate from delegation-ledger.json on purpose. Routing savings and
+ * conversion savings answer different questions ("work ran on a cheaper
+ * model" vs "a document was read as text instead of as an attachment"), and
+ * a statusline that folds them into one figure cannot tell the reader which
+ * habit earned the money.
+ *
+ * File: <userDataDir>/doc2md-ledger.json
+ *   { "version": 1,
+ *     "events": { "<source path>": { "ts", "usd", "ext", "tokens", "baseline" } } }
+ *
+ * Keyed by the source path so re-converting the same document after an edit
+ * updates its event instead of counting the file twice.
+ *
+ * # What "saved" means here, and what it deliberately does not
+ *
+ * The counterfactual is what the reader would have done without a converter,
+ * and it differs by format. Both were measured on 2026-09-06.
+ *
+ * PDF: attaching the file. The same one-line prompt was sent through
+ * `claude --print --input-format stream-json` with and without the file as a
+ * document block. The control turn cost 42,204 tokens, twice, to the token.
+ *
+ *   kohjuho_resume_kr.pdf   7 pages   +20,537 tokens   2,934 per page
+ *   xeoyoung_resume.pdf     5 pages   +12,709 tokens   2,542 per page
+ *
+ * A PDF is read whole: the model answered from its contents. Converting one
+ * to text is worth three to four times its own size.
+ *
+ * pptx/xlsx/docx: unpacking the container. These never reach the model as
+ * attachments at all — the same probe on a docx added 78 tokens and the model
+ * replied that it had no file, and Read refuses the format outright. What a
+ * reader does instead is unzip the archive and wade through its XML, where
+ * tags and style attributes outweigh the text many times over:
+ *
+ *   aws-summit-seoul.pptx   2.1MB of slide XML   ~540,429 tokens   23.8× the conversion
+ *   우리은행이력서.docx      312KB of body XML    ~78,113 tokens    ~46× the conversion
+ *
+ * So the baseline for these formats is the body markup the converter read,
+ * measured per file rather than assumed from a ratio. It is a real number for
+ * a real fallback — this very session unzipped a pptx to verify a conversion
+ * before this ledger existed.
+ *
+ * Erring low is deliberate throughout. A savings figure that flatters the
+ * tool is worth less than one the user can trust.
+ *
+ * `scripts/doc2md-baseline.mjs` re-measures the attachment side if the
+ * client's handling changes.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const WEEK_MS = 7 * 24 * 3600 * 1000;
+const MONTH_MS = 30 * 24 * 3600 * 1000;
+
+const LEDGER_VERSION = 1;
+
+/**
+ * Tokens an attached PDF costs per page, from the two measurements in the
+ * header: 2,934 and 2,542 per page. 2,500 sits below both, so the saving is
+ * understated for a dense document rather than overstated for a sparse one.
+ */
+const PDF_TOKENS_PER_PAGE = 2500;
+
+/**
+ * How each format's alternative is priced. `perPage` values an attached
+ * page-image document; `markup` values the body XML a reader would have had
+ * to wade through instead.
+ *
+ * `.xls` is the pre-2007 binary format, which is not a zip container and so
+ * has no markup to measure. It falls back to parity, recording no saving.
+ */
+const ATTACHMENT_BASELINE = {
+  '.pdf': { perPage: PDF_TOKENS_PER_PAGE },
+  '.pptx': { markup: true },
+  '.docx': { markup: true },
+  '.xlsx': { markup: true },
+  '.xls': { ratio: 1 },
+  // A .fig unzips to another binary (Figma's kiwi format), so unlike the
+  // office containers there is no readable markup to price the fallback
+  // against. Converting is the only way to read it at all; no money claimed.
+  '.fig': { ratio: 1 },
+};
+
+/**
+ * Input price per token used to value the difference, in USD. Sonnet's input
+ * rate, chosen as the mid tier: crediting the conversion at Opus rates would
+ * quietly triple every figure for anyone who never runs Opus.
+ */
+const INPUT_USD_PER_TOKEN = 3 / 1_000_000;
+
+/** Rough token count for text. Four bytes per token, the usual approximation. */
+function estimateTokens(text) {
+  return Math.ceil(Buffer.byteLength(String(text || ''), 'utf8') / 4);
+}
+
+/**
+ * What the conversion saved, in USD, and the two token figures behind it.
+ * `meta` is the conversion metadata: `pages` for PDFs, plus the markdown that
+ * was written.
+ */
+function estimateSaving({ ext, pages = 0, markupBytes = 0, markdown = '' }) {
+  const tokens = estimateTokens(markdown);
+  const rule = ATTACHMENT_BASELINE[String(ext).toLowerCase()] || { ratio: 1 };
+  let baseline;
+  if (rule.perPage && pages > 0) {
+    baseline = pages * rule.perPage;
+  } else if (rule.markup && markupBytes > 0) {
+    baseline = Math.ceil(markupBytes / 4);
+  } else {
+    baseline = Math.round(tokens * (rule.ratio || 1));
+  }
+  // Never below what the conversion actually produced. A dense PDF can cost
+  // more as text than its page count suggests, and a baseline under the real
+  // figure would show as a zero saving while understating the document.
+  baseline = Math.max(baseline, tokens);
+  const usd = Math.max(0, baseline - tokens) * INPUT_USD_PER_TOKEN;
+  return { tokens, baseline, usd: Math.round(usd * 10000) / 10000 };
+}
+
+function ledgerPath(userDataDir) {
+  return path.join(userDataDir, 'doc2md-ledger.json');
+}
+
+function loadLedger(userDataDir) {
+  try {
+    const data = JSON.parse(fs.readFileSync(ledgerPath(userDataDir), 'utf8'));
+    if (!data || typeof data.events !== 'object' || data.events === null) {
+      return { version: LEDGER_VERSION, events: {} };
+    }
+    if (data.version !== LEDGER_VERSION) return { version: LEDGER_VERSION, events: {} };
+    return data;
+  } catch {
+    return { version: LEDGER_VERSION, events: {} };
+  }
+}
+
+/**
+ * Record one conversion. Never throws: an unwritable ledger costs a
+ * statusline figure, which is not worth failing a conversion over.
+ */
+function recordConversion(userDataDir, event) {
+  if (!event || !event.key) return;
+  const data = loadLedger(userDataDir);
+  data.version = LEDGER_VERSION;
+  data.events[event.key] = {
+    ts: Number.isFinite(event.ts) ? event.ts : Date.now(),
+    usd: Math.max(0, Math.round((Number(event.usd) || 0) * 10000) / 10000),
+    ext: event.ext || '',
+    tokens: Number(event.tokens) || 0,
+    baseline: Number(event.baseline) || 0,
+  };
+  try {
+    fs.mkdirSync(userDataDir, { recursive: true });
+    fs.writeFileSync(ledgerPath(userDataDir), JSON.stringify(data) + '\n', { mode: 0o600 });
+  } catch {
+    /* best effort, like every other state file here */
+  }
+}
+
+/**
+ * Rolling totals plus `docs` (documents converted, lifetime) and `byExt` —
+ * the lifetime rollup per format, priciest first, then most-converted. Never
+ * throws; an unreadable ledger yields zeros, and the statusline hides the
+ * chip on a zero.
+ */
+function doc2mdSavedTotals(userDataDir, now = Date.now()) {
+  const empty = () => ({ week: 0, month: 0, total: 0, docs: 0, tokens: 0, byExt: [] });
+  const totals = empty();
+  const byExt = new Map();
+  try {
+    for (const e of Object.values(loadLedger(userDataDir).events)) {
+      const usd = Number(e.usd) || 0;
+      totals.total += usd;
+      totals.docs += 1;
+      totals.tokens += Number(e.tokens) || 0;
+      if (Number.isFinite(e.ts)) {
+        if (now - e.ts <= WEEK_MS) totals.week += usd;
+        if (now - e.ts <= MONTH_MS) totals.month += usd;
+      }
+      const key = String(e.ext || '?').replace(/^\./, '') || '?';
+      const row = byExt.get(key) || { ext: key, docs: 0, usd: 0 };
+      row.docs += 1;
+      row.usd += usd;
+      byExt.set(key, row);
+    }
+  } catch {
+    return empty();
+  }
+  totals.byExt = [...byExt.values()].sort((a, b) => b.usd - a.usd || b.docs - a.docs);
+  return totals;
+}
+
+module.exports = {
+  LEDGER_VERSION,
+  PDF_TOKENS_PER_PAGE,
+  ATTACHMENT_BASELINE,
+  INPUT_USD_PER_TOKEN,
+  estimateTokens,
+  estimateSaving,
+  ledgerPath,
+  loadLedger,
+  recordConversion,
+  doc2mdSavedTotals,
+};

package/src/doc2md.cjs

@@ -27,13 +27,16 @@ const os = require('node:os');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { spawnSync } = require('node:child_process');
+const ledger = require('./doc2md-ledger.cjs');
 
 // Formats where the original is of no use to the model. Images are absent
 // deliberately: markitdown returns nothing for them, and OCR misread resource
 // names in testing (`c5.xlarge` as `c.xlarge`), which is worse than no text at
 // all in a document where those names are the content. The model reads images
 // natively anyway.
-const TARGET_EXTENSIONS = ['.pptx', '.xlsx', '.xls', '.pdf', '.docx'];
+// `.fig` converts through openfig-core in Node rather than markitdown; see
+// fig2md.cjs for why it cannot go through the Python path.
+const TARGET_EXTENSIONS = ['.pptx', '.xlsx', '.xls', '.pdf', '.docx', '.fig'];
 
 // Big enough for real decks and reports, small enough that a hostile file
 // cannot make the converter the expensive part of the turn.
@@ -107,7 +110,13 @@ function isSensitivePath(filePath) {
 function cachePathFor(filePath) {
   const abs = path.resolve(filePath);
   const hash = crypto.createHash('sha256').update(abs).digest('hex').slice(0, 12);
-  const base = path.basename(abs).replace(/[^\w.\-]/g, '_');
+  // Keep letters and digits of any script, so a Korean or Japanese file name
+  // stays readable in the cache directory instead of collapsing into a row of
+  // underscores. Only characters that are awkward in a path are replaced.
+  const base = path.basename(abs)
+    .replace(/[^\p{L}\p{N}._-]/gu, '_')
+    .replace(/_{2,}/g, '_')
+    .slice(0, 80);
   return path.join(cacheDir(), `${base}.${hash}.md`);
 }
 
@@ -129,16 +138,81 @@ function readCache(filePath) {
   }
 }
 
+/** `31854740` → `30.4MB`, for the banner and the hook's one-line summary. */
+function humanBytes(n) {
+  const bytes = Number(n) || 0;
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+/**
+ * The header stamped onto every conversion.
+ *
+ * Without it a conversion is an anonymous .md in a directory nobody opened on
+ * purpose, and the reader has no way to tell that this tool produced it, from
+ * what, or when. Four lines of provenance answer all of that at the top of the
+ * file the model is about to read, and cost about 60 tokens.
+ */
+function banner(sourcePath, saving) {
+  const src = fs.statSync(sourcePath);
+  const lines = [
+    '<!--',
+    'claude-token-saver doc2md 가 변환한 파일입니다. 직접 편집하지 마십시오.',
+    `원본: ${path.resolve(sourcePath)} (${humanBytes(src.size)})`,
+    `변환: ${new Date().toISOString()} · Markdown ${humanBytes(Buffer.byteLength(saving.markdown, 'utf8'))} · 약 ${saving.tokens.toLocaleString('en-US')} 토큰`,
+  ];
+  if (saving.usd > 0) {
+    const savedTokens = Math.max(0, saving.baseline - saving.tokens);
+    // The alternative differs by format, so the sentence names it: a PDF
+    // would have been attached, a zip document would have been unpacked.
+    const alternative = path.extname(sourcePath).toLowerCase() === '.pdf'
+      ? '원본을 첨부하면'
+      : '압축을 풀어 본문 XML을 읽으면';
+    lines.push(
+      `${alternative} 약 ${saving.baseline.toLocaleString('en-US')} 토큰이 드는데, `
+      + `변환본은 ${saving.tokens.toLocaleString('en-US')} 토큰입니다. `
+      + `약 ${savedTokens.toLocaleString('en-US')} 토큰, $${saving.usd.toFixed(2)} 을 아꼈습니다(추정).`,
+    );
+  }
+  lines.push('-->', '');
+  return lines.join('\n');
+}
+
 function writeCache(filePath, markdown, extra) {
   ensureCacheDir();
   const cacheFile = cachePathFor(filePath);
   const src = fs.statSync(filePath);
-  fs.writeFileSync(cacheFile, markdown, { encoding: 'utf8', mode: 0o600 });
+  const ext = path.extname(filePath).toLowerCase();
+  const saving = Object.assign(
+    ledger.estimateSaving({
+      ext,
+      pages: (extra && extra.pages) || 0,
+      markupBytes: (extra && extra.markupBytes) || 0,
+      markdown,
+    }),
+    { markdown },
+  );
+  fs.writeFileSync(cacheFile, banner(filePath, saving) + markdown, { encoding: 'utf8', mode: 0o600 });
+  ledger.recordConversion(userDataDir(), {
+    key: path.resolve(filePath),
+    ts: Date.now(),
+    usd: saving.usd,
+    ext,
+    tokens: saving.tokens,
+    baseline: saving.baseline,
+  });
   const meta = Object.assign({
     source: path.resolve(filePath),
     size: src.size,
     mtimeMs: src.mtimeMs,
     convertedAt: new Date().toISOString(),
+    // Carried in the metadata so the hook can report what the conversion cost
+    // and saved without re-reading and re-measuring the markdown.
+    markdownBytes: Buffer.byteLength(markdown, 'utf8'),
+    tokens: saving.tokens,
+    baselineTokens: saving.baseline,
+    savedUsd: saving.usd,
   }, extra || {});
   fs.writeFileSync(metaPathFor(cacheFile), JSON.stringify(meta, null, 2), { encoding: 'utf8', mode: 0o600 });
   return { cacheFile, meta };
@@ -193,6 +267,12 @@ function managedPython() {
 
 const MARKITDOWN_SPEC = 'markitdown[pptx,pdf,xlsx,docx]';
 
+// Editing libraries, installed alongside the converter. Reading is doc2md's
+// own job; editing is the agent's, done per-request with a short script
+// against a COPY of the document. These are the libraries those scripts need,
+// pre-installed so "swap the chart on slide 23" does not stall on pip.
+const EDIT_LIBS = ['python-pptx', 'python-docx', 'openpyxl'];
+
 /**
  * Build the managed venv and install markitdown into it.
  *
@@ -217,8 +297,8 @@ function installConverter({ onProgress = () => {} } = {}) {
     }
   }
 
-  onProgress(`installing ${MARKITDOWN_SPEC}`);
-  const install = spawnSync(target, ['-m', 'pip', 'install', '--quiet', MARKITDOWN_SPEC], {
+  onProgress(`installing ${MARKITDOWN_SPEC} + ${EDIT_LIBS.join(', ')}`);
+  const install = spawnSync(target, ['-m', 'pip', 'install', '--quiet', MARKITDOWN_SPEC, ...EDIT_LIBS], {
     encoding: 'utf8',
     timeout: 900_000,
   });
@@ -246,6 +326,30 @@ function installConverter({ onProgress = () => {} } = {}) {
  * Every failure is a reason to leave the original Read alone, never to break
  * it. That is the whole contract with the hook.
  */
+/**
+ * Bridge from this synchronous pipeline to the async fig converter: run it in
+ * a child process and read one JSON object from stdout, exactly the contract
+ * the Python converter already speaks. Costs a process spawn, buys the same
+ * timeout and isolation the other formats get.
+ */
+function spawnFigConvert(fig2md, filePath) {
+  const runner = path.join(__dirname, 'fig2md-runner.cjs');
+  const run = spawnSync(process.execPath, [runner, filePath, userDataDir()], {
+    encoding: 'utf8',
+    timeout: CONVERT_TIMEOUT_MS,
+    maxBuffer: MAX_MARKDOWN_BYTES * 4,
+  });
+  if (run.error && run.error.code === 'ETIMEDOUT') return { ok: false, reason: 'timeout' };
+  if (run.status !== 0) {
+    return { ok: false, reason: 'convert-failed', detail: (run.stderr || '').slice(0, 300) };
+  }
+  try {
+    return JSON.parse(run.stdout);
+  } catch {
+    return { ok: false, reason: 'convert-failed', detail: 'fig converter produced no JSON' };
+  }
+}
+
 function convert(filePath, { converter = CONVERTER, python: pythonOverride = null } = {}) {
   if (!isTargetPath(filePath)) return { ok: false, reason: 'not-target' };
   if (isSensitivePath(filePath)) return { ok: false, reason: 'sensitive' };
@@ -263,6 +367,17 @@ function convert(filePath, { converter = CONVERTER, python: pythonOverride = nul
   const cached = readCache(filePath);
   if (cached) return { ok: true, cached: true, cacheFile: cached.cacheFile, meta: cached.meta };
 
+  // Figma files take the Node converter; everything else goes to markitdown.
+  if (path.extname(filePath).toLowerCase() === '.fig') {
+    const fig2md = require('./fig2md.cjs');
+    const result = spawnFigConvert(fig2md, filePath);
+    if (!result.ok) return result;
+    const written = writeCache(filePath, result.markdown, {
+      note: result.note, truncated: false, rows: 0, pages: 0, markupBytes: 0,
+    });
+    return { ok: true, cached: false, cacheFile: written.cacheFile, meta: written.meta };
+  }
+
   // The override exists so tests can drive a stub converter with any Python at
   // all: the normal search insists the interpreter can import markitdown,
   // which would make the whole path untestable without the real package.
@@ -299,6 +414,8 @@ function convert(filePath, { converter = CONVERTER, python: pythonOverride = nul
     note: payload.note || null,
     truncated: !!payload.truncated || clipped,
     rows: payload.rows || 0,
+    pages: payload.pages || 0,
+    markupBytes: payload.markup_bytes || 0,
     clipped,
   });
   return { ok: true, cached: false, cacheFile: written.cacheFile, meta: written.meta };
@@ -449,6 +566,24 @@ function documentPathsIn(text) {
 // conversion. The rest are named in the note so nothing disappears quietly.
 const MAX_PROMPT_CONVERSIONS = 3;
 
+/**
+ * The one line that makes a conversion visible: what came in, what went out,
+ * and what not attaching the original was worth.
+ *
+ * The sizes matter more than they look. A 30MB deck that becomes 90KB of
+ * Markdown is the whole argument for this feature, and without the figures
+ * the model has nothing concrete to tell the user it happened.
+ */
+function conversionSummary(sourcePath, meta = {}) {
+  const parts = [];
+  try {
+    parts.push(`${humanBytes(fs.statSync(sourcePath).size)} → ${humanBytes(meta.markdownBytes || 0)}`);
+  } catch { /* the size is a nicety, not the point */ }
+  if (meta.tokens) parts.push(`약 ${Number(meta.tokens).toLocaleString('en-US')} 토큰`);
+  if (meta.savedUsd > 0) parts.push(`첨부 대비 약 $${Number(meta.savedUsd).toFixed(2)} 절감(추정)`);
+  return parts.join(', ');
+}
+
 /**
  * Context to inject for a UserPromptSubmit payload, or null.
  *
@@ -471,6 +606,7 @@ function contextForPrompt(payload, opts = {}) {
     const result = convert(p, opts);
     if (result.ok) {
       lines.push(`  ${name} → ${result.cacheFile}`);
+      lines.push(`      ${conversionSummary(p, result.meta)}`);
       if (result.meta && result.meta.note) lines.push(`      ${result.meta.note}`);
       if (result.meta && result.meta.clipped) {
         lines.push('      변환 결과가 너무 커서 뒷부분을 잘랐습니다. 전체가 필요하면 원본을 직접 다루십시오.');
@@ -479,6 +615,10 @@ function contextForPrompt(payload, opts = {}) {
       lines.push(lang === 'ko'
         ? `  ${name}: 변환기가 없어 변환하지 못했습니다. 설치: ${INSTALL_HINT}`
         : `  ${name}: no converter installed. Install it with: ${INSTALL_HINT}`);
+    } else if (result.reason === 'no-figparser') {
+      lines.push(lang === 'ko'
+        ? `  ${name}: .fig 파서가 없어 변환하지 못했습니다. 설치: claude-token-saver doc2md install-converter`
+        : `  ${name}: no .fig parser installed. Install it with: claude-token-saver doc2md install-converter`);
     } else if (result.reason === 'sensitive') {
       lines.push(lang === 'ko'
         ? `  ${name}: 파일명이 민감 문서 패턴에 걸려 변환하지 않았습니다.`
@@ -500,12 +640,14 @@ function contextForPrompt(payload, opts = {}) {
       '[doc2md] 이 프롬프트에 문서 경로가 있어 Markdown 으로 변환해 두었습니다.',
       ...lines,
       '원본 대신 위 변환본을 Read 하십시오. pptx·xlsx·docx 는 Read 도구가 이진 파일이라며 거부하므로 원본을 직접 열 수 없습니다.',
+    '변환이 일어났다는 사실은 사용자에게도 보여야 하므로, 답변 첫 줄에 변환한 문서마다 다음 형식으로 한 줄씩 출력하십시오: `📄 [claude-token-saver] doc2md: <파일명> (<원본 크기> → <Markdown 크기>, 약 <토큰> 토큰)`. 절감액이 함께 안내됐다면 그 금액도 같은 줄 끝에 덧붙이십시오.',
       '경로가 주어지지 않은 문서를 열어야 할 때는 `claude-token-saver doc2md <경로>` 를 실행해 변환본 경로를 얻으십시오.',
     ].join('\n')
     : [
       '[doc2md] This prompt names document paths, which have been converted to Markdown:',
       ...lines,
       'Read the conversions above rather than the originals: Read refuses pptx/xlsx/docx as binary files, so the originals cannot be opened directly.',
+    'The user cannot see that any of this happened, so open your reply with one line per converted document: `📄 [claude-token-saver] doc2md: <name> (<source size> → <markdown size>, ~<tokens> tokens)`, adding the saving above if one was reported.',
       'For a document whose path was not given here, run `claude-token-saver doc2md <path>` to get its conversion.',
     ].join('\n');
 }
@@ -523,15 +665,66 @@ function sessionNote(lang = 'en') {
       '[doc2md] 문서(pptx·xlsx·pdf·docx)를 다룰 때의 규칙입니다.',
       '  문서를 열어야 하는데 Read 가 이진 파일이라며 거부하면, `claude-token-saver doc2md <경로>` 를 실행하고 그 결과로 나온 .md 를 Read 하십시오.',
       '  사용자가 문서를 메시지에 직접 첨부했다면, 첨부는 내용 전체가 컨텍스트에 실려 토큰을 크게 씁니다. 다음부터는 첨부 대신 파일 경로를 적어 달라고 안내하십시오. 경로로 주면 변환본만 읽습니다.',
+      '  변환은 단방향입니다. 변환본 .md 를 고쳐도 원본에는 반영되지 않습니다. 문서 수정 요청을 받으면: ① 원본을 복사하고 ② 복사본을 스크립트로 수정하십시오. pptx·docx·xlsx 는 도구 venv 파이썬에 python-pptx·python-docx·openpyxl 이 준비되어 있고(`claude-token-saver doc2md` 상태 출력에 경로가 나옵니다), .fig 는 openfig-core 로 편집·재인코드합니다. ③ 수정한 복사본을 doc2md 로 재변환해 변경이 들어갔는지 검증하십시오. 차트·이미지 같은 시각 요소는 변환본에 안 잡히므로 텍스트 검증만으로 완료를 단정하지 마십시오.',
     ].join('\n');
   }
   return [
     '[doc2md] Handling documents (pptx/xlsx/pdf/docx):',
     '  If Read refuses a document as a binary file, run `claude-token-saver doc2md <path>` and Read the .md it prints.',
     '  If the user attached a document to their message, its full contents were billed into the context. Tell them that naming the file path instead is far cheaper, since only the converted Markdown gets read.',
+    '  Conversions are one-way: editing the cached .md changes nothing in the source. When asked to modify a document: ① copy the original, ② edit the COPY with a script — the managed venv python has python-pptx/python-docx/openpyxl, and .fig edits go through openfig-core — then ③ re-convert the copy with doc2md to verify the change landed. Charts and images do not appear in conversions, so text verification alone does not prove visual edits.',
   ].join('\n');
 }
 
+/**
+ * Guard for Edit/Write. Two writes are refused, for different reasons.
+ *
+ * A write to a conversion in the cache: the conversion is one-way, so an edit
+ * there changes nothing the user cares about — and worse, the cache still
+ * matches the source's mtime, so the corrupted copy would be served on every
+ * later read while looking exactly like the document. The deny explains where
+ * the work should go instead.
+ *
+ * A write to the original document: Edit and Write emit text, and a pptx or
+ * .fig overwritten with text is destroyed, not edited. Nothing this tool
+ * ships can write those formats back.
+ */
+function decideForWrite(context) {
+  if (!context || (context.tool_name !== 'Edit' && context.tool_name !== 'Write')) return null;
+  const toolInput = context.tool_input;
+  const filePath = toolInput && typeof toolInput.file_path === 'string' ? toolInput.file_path : '';
+  if (!filePath) return null;
+  const abs = path.resolve(filePath);
+
+  if (abs.startsWith(cacheDir() + path.sep)) {
+    let source = null;
+    try {
+      source = JSON.parse(fs.readFileSync(metaPathFor(abs), 'utf8')).source;
+    } catch { /* the deny stands on its own */ }
+    return {
+      deny: true,
+      reason: '[doc2md] 이 파일은 변환 캐시입니다. 여기를 고쳐도 원본 문서에는 아무것도 반영되지 않고, '
+        + '캐시만 오염된 채 다음 읽기부터 계속 서빙됩니다.\n'
+        + (source ? `  원본: ${source}\n` : '')
+        + '  문서 수정이 목적이라면: 원본을 복사한 뒤(cp) 복사본을 스크립트로 수정하십시오. '
+        + `pptx·docx·xlsx 는 ${managedPython()} 에 python-pptx·python-docx·openpyxl 이 설치되어 있고, `
+        + '.fig 는 doc2md-fig 의 openfig-core 로 편집·재인코드할 수 있습니다. '
+        + '수정 후 복사본을 `claude-token-saver doc2md <복사본>` 으로 재변환해 의도한 변경이 들어갔는지 확인하십시오. 원본은 절대 직접 수정하지 마십시오.',
+    };
+  }
+
+  if (isTargetPath(abs)) {
+    return {
+      deny: true,
+      reason: `[doc2md] ${path.basename(abs)} 는 이진 문서입니다. Edit/Write 는 텍스트를 쓰므로 이 파일을 파괴합니다. `
+        + '수정하려면 원본을 복사한 뒤(cp) 복사본을 스크립트로 고치십시오. '
+        + `pptx·docx·xlsx 는 ${managedPython()} 의 python-pptx·python-docx·openpyxl, .fig 는 openfig-core 를 쓰고, `
+        + '수정 후 `claude-token-saver doc2md <복사본>` 재변환으로 결과를 검증하십시오.',
+    };
+  }
+  return null;
+}
+
 /** The decision rendered as the JSON Claude Code expects on stdout. */
 function formatHookOutput(decision) {
   if (!decision) return null;
@@ -565,5 +758,6 @@ module.exports = {
   writeCache,
   convert,
   decideForRead,
+  decideForWrite,
   formatHookOutput,
 };

package/src/fig2md-runner.cjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * Child-process shim between the synchronous doc2md pipeline and the async
+ * fig converter. Prints the conversion result as one JSON object on stdout,
+ * exactly like the Python converter does, so the caller treats both the same.
+ *
+ * Usage: node fig2md-runner.cjs <file.fig> <userDataDir>
+ */
+
+'use strict';
+
+const { convertFig } = require('./fig2md.cjs');
+
+const [file, userDataDir] = process.argv.slice(2);
+convertFig(file, userDataDir)
+  .then((result) => { process.stdout.write(JSON.stringify(result)); })
+  .catch((e) => {
+    process.stdout.write(JSON.stringify({
+      ok: false, reason: 'convert-failed', detail: String(e && e.message || e).slice(0, 300),
+    }));
+  });

package/src/fig2md.cjs

@@ -0,0 +1,182 @@
+/**
+ * fig2md — Markdown rendering of a Figma `.fig` export.
+ *
+ * Planning documents increasingly live in Figma rather than PowerPoint, and a
+ * `.fig` handed to the model is even more opaque than a pptx: the container
+ * is a zip, but the payload inside (`canvas.fig`) is Figma's binary kiwi
+ * format, so there is no XML to fall back on. Without a converter the file is
+ * simply unreadable.
+ *
+ * markitdown does not speak this format, so the conversion runs in Node with
+ * [openfig-core] (MIT, three small pure-JS dependencies). The parser is not
+ * bundled: this package deliberately ships with zero dependencies, so
+ * openfig-core is installed on demand into the tool's own state directory —
+ * the same arrangement as the markitdown venv, for the same reason.
+ *
+ * Verified 2026-09-06 against real files: a community Bootstrap UI kit
+ * (8.1MB, 4,155 nodes, 1,312 of them text) and a 52MB Tailwind kit, each
+ * converting in under a second, plus a round-trip fixture whose Korean text
+ * nodes came back byte-identical. Both .fig vintages parse — the current
+ * zip container and the older bare fig-kiwi stream.
+ *
+ * [openfig-core]: https://github.com/OpenFig-org/openfig-core
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const FIG_PARSER_SPEC = 'openfig-core@^0.4.1';
+
+/** Where the on-demand parser install lives, under the tool's state dir. */
+function managedFigDir(userDataDir) {
+  return path.join(userDataDir, 'doc2md-fig');
+}
+
+function loadParser(userDataDir) {
+  try {
+    // eslint-disable-next-line import/no-dynamic-require
+    return require(path.join(managedFigDir(userDataDir), 'node_modules', 'openfig-core', 'dist', 'index.cjs'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Install openfig-core into the managed directory. Mirrors the markitdown
+ * venv install: network once, probe as the acceptance test.
+ */
+function installFigParser(userDataDir, { onProgress = () => {} } = {}) {
+  const dir = managedFigDir(userDataDir);
+  fs.mkdirSync(dir, { recursive: true });
+  const pkgJson = path.join(dir, 'package.json');
+  if (!fs.existsSync(pkgJson)) {
+    fs.writeFileSync(pkgJson, JSON.stringify({ name: 'doc2md-fig', private: true }) + '\n');
+  }
+  onProgress(`installing ${FIG_PARSER_SPEC}`);
+  const r = spawnSync('npm', ['install', '--no-audit', '--no-fund', '--silent', FIG_PARSER_SPEC], {
+    cwd: dir,
+    encoding: 'utf8',
+    timeout: 300_000,
+  });
+  if (r.status !== 0) {
+    return { ok: false, reason: 'npm-failed', detail: (r.stderr || '').slice(0, 400) };
+  }
+  if (!loadParser(userDataDir)) {
+    return { ok: false, reason: 'import-failed', detail: 'installed, but openfig-core does not load' };
+  }
+  return { ok: true, dir };
+}
+
+/**
+ * Node name plus type, indented by depth: the skeleton lines of the outline.
+ */
+function heading(node, depth) {
+  const name = String(node.name || '').trim() || '(이름 없음)';
+  return `${'#'.repeat(Math.min(depth + 2, 6))} ${name}`;
+}
+
+/**
+ * Walk the parsed document and render an outline.
+ *
+ * The traversal follows `childrenMap` (guid → ordered children), which is how
+ * the parser exposes hierarchy. Containers become headings, TEXT nodes become
+ * body lines, and everything visual (vectors, rectangles, images) is counted
+ * rather than listed: in a planning document the words are the content, and
+ * two hundred `Rectangle 173` lines would drown them.
+ */
+function renderMarkdown(doc, sourceName) {
+  const guidKey = (g) => `${g.sessionID}:${g.localID}`;
+  const lines = [];
+  const skipped = Object.create(null);
+  let textNodes = 0;
+
+  const CONTAINERS = new Set(['DOCUMENT', 'CANVAS', 'FRAME', 'GROUP', 'SECTION', 'COMPONENT', 'COMPONENT_SET', 'INSTANCE', 'SLIDE', 'SYMBOL']);
+
+  function walk(node, depth) {
+    if (!node || node.phase === 'REMOVED' || node.visible === false) return;
+    const type = node.type || '?';
+    if (type === 'TEXT') {
+      textNodes += 1;
+      const text = String(node.textData?.characters || '').trim();
+      const name = String(node.name || '').trim();
+      // The layer name usually repeats the text's first line; only show it
+      // when it says something the text does not.
+      if (name && text && !text.startsWith(name) && !name.startsWith(text.slice(0, 20))) {
+        lines.push(`- **${name}**: ${text.replace(/\n/g, ' / ')}`);
+      } else if (text) {
+        lines.push(`- ${text.replace(/\n/g, ' / ')}`);
+      }
+      return;
+    }
+    if (CONTAINERS.has(type)) {
+      if (type !== 'DOCUMENT') {
+        lines.push('', heading(node, depth), '');
+      }
+      const children = doc.childrenMap?.get?.(guidKey(node.guid))
+        || doc.childrenMap?.[guidKey(node.guid)]
+        || [];
+      for (const child of children) walk(child, depth + (type === 'DOCUMENT' ? 0 : 1));
+      return;
+    }
+    skipped[type] = (skipped[type] || 0) + 1;
+  }
+
+  const root = (doc.nodes || []).find((n) => n.type === 'DOCUMENT');
+  if (root) walk(root, 0);
+
+  const title = doc.meta?.file_name || sourceName;
+  const head = [`# ${title}`];
+  const skippedText = Object.entries(skipped)
+    .sort((a, b) => b[1] - a[1])
+    .map(([t, n]) => `${t} ${n}개`)
+    .join(', ');
+  if (skippedText) {
+    head.push('', `(텍스트 외 시각 요소는 생략했습니다: ${skippedText}. 시각 확인이 필요하면 Figma에서 원본을 여십시오.)`);
+  }
+  return { markdown: [...head, ...lines, ''].join('\n'), textNodes };
+}
+
+/**
+ * Convert one `.fig` file. Same result contract as the Python converter:
+ * `{ ok, markdown, note, truncated, rows, pages, markup_bytes }` or
+ * `{ ok: false, reason, detail }`.
+ *
+ * `markup_bytes` is 0 on purpose. The office formats price their alternative
+ * as "unzip and wade through the XML", but a .fig unzips to another binary —
+ * there is no readable fallback, so there is no honest baseline to claim and
+ * these conversions count as documents handled rather than money saved.
+ */
+async function convertFig(filePath, userDataDir) {
+  const parser = loadParser(userDataDir);
+  if (!parser) return { ok: false, reason: 'no-figparser' };
+  let doc;
+  try {
+    const buf = fs.readFileSync(filePath);
+    // Two vintages of the same extension: current exports are a zip wrapping
+    // canvas.fig, older ones are the bare fig-kiwi stream (magic "fig-kiwi").
+    // Verified on a real 8.4MB community kit that only the binary path reads.
+    doc = buf[0] === 0x50 && buf[1] === 0x4b
+      ? await parser.parseFig(buf)
+      : await parser.parseFigBinary(buf);
+  } catch (e) {
+    return { ok: false, reason: 'convert-failed', detail: String(e.message || e).slice(0, 300) };
+  }
+  const { markdown, textNodes } = renderMarkdown(doc, path.basename(filePath, '.fig'));
+  if (!textNodes) {
+    // A design file with no words converts to an empty outline, which would
+    // read as "the document says nothing" — a worse claim than "unreadable".
+    return { ok: false, reason: 'no-text', detail: 'the file has no text nodes' };
+  }
+  return { ok: true, markdown, note: null, truncated: false, rows: 0, pages: 0, markup_bytes: 0 };
+}
+
+module.exports = {
+  FIG_PARSER_SPEC,
+  managedFigDir,
+  installFigParser,
+  convertFig,
+  renderMarkdown,
+};

package/src/formatters/statusline.js

@@ -261,7 +261,7 @@ export function formatNoSession({ caps = null, model = null, windowLabel = '', v
  * @param {boolean} [opts.verbose=false] - longer layout with labels
  * @param {boolean} [opts.timer=true] - show TTL countdown segment
  * @param {'text'|'icon'} [opts.mode='text'] - label style. 'icon' uses 🧠 ⏳ 💰 instead of word labels.
- * @param {string[]|null} [opts.segments] - whitelist of segments to render. Names: cap-warn, spike, version, harness, korean, model, hit, ttl, saved, delegated, ctx, period, plus per-window keys (`five_hour`, `seven_day`, …). `5h`/`7d` are kept as aliases for back-compat. Null/undefined = all.
+ * @param {string[]|null} [opts.segments] - whitelist of segments to render. Names: cap-warn, spike, version, harness, korean, model, hit, ttl, saved, delegated, doc2md, ctx, period, plus per-window keys (`five_hour`, `seven_day`, …). `5h`/`7d` are kept as aliases for back-compat. Null/undefined = all.
  * @param {boolean} [opts.singleLine=false] - force the legacy one-line layout. By default, when the delegation ledger has lifetime savings, the routing totals lead on their own first line and everything else moves to line 2 (Claude Code renders multi-line statuslines; `--single-line` is the escape hatch for terminals that only show the first line).
  */
 export function formatReport(data, { color = true, verbose = false, timer = true, mode = 'text', segments = null, singleLine = false } = {}) {
@@ -350,6 +350,32 @@ export function formatReport(data, { color = true, verbose = false, timer = true
       ? `${c(YELLOW)}🔀 ${unresolvedRuns} unresolved${c(RESET)}`
       : null);
 
+  // Document conversions — the same kind of number as "Routing saved", earned
+  // a different way: a document read as Markdown instead of attached whole.
+  // Kept as its own chip rather than folded into the routing total, because a
+  // single figure could not tell the reader which habit earned it.
+  //
+  // Conversions that saved nothing measurable still show as a count. For
+  // pptx/xlsx/docx the honest saving is zero — the client extracts much the
+  // same text — and a chip that disappeared on those would read as "doc2md
+  // did nothing" on the very formats it is the only way to open.
+  //   icon:  "📄 $0.42"   verbose: "📄 Doc2md saved $0.42 · 12 docs"
+  //   text:  "Doc2md saved $0.42"
+  const doc2md = data.doc2mdTotals;
+  const doc2mdUsd = Number(doc2md && doc2md.total) || 0;
+  const doc2mdDocs = Number(doc2md && doc2md.docs) || 0;
+  const doc2mdLabel = isIcon
+    ? (verbose ? '📄 Doc2md saved' : '📄')
+    : 'Doc2md saved';
+  let doc2mdSeg = null;
+  if (doc2mdUsd > 0) {
+    doc2mdSeg = `${c(GREEN)}${doc2mdLabel}${c(RESET)} ${formatMoney(doc2mdUsd)}`
+      + (verbose ? ` ${c(GRAY)}· ${doc2mdDocs} docs${c(RESET)}` : '');
+  } else if (doc2mdDocs > 0) {
+    const label = isIcon ? '📄' : 'Doc2md';
+    doc2mdSeg = `${c(GRAY)}${label} ${doc2mdDocs} docs${c(RESET)}`;
+  }
+
   // Routing-savings headline line (multi-line layout). The lifetime sum from
   // the delegation ledger — the number the whole tool exists to grow, so it
   // gets line 1 to itself while the diagnostics move to line 2.
@@ -388,6 +414,24 @@ export function formatReport(data, { color = true, verbose = false, timer = true
       (pairText ? `  ${c(GRAY)}|${c(RESET)}  ${pairText}` : '');
   }
 
+  // Doc2md's own headline line, same anatomy as the routing one: a green
+  // lifetime total, then a gray per-format breakdown. Only built when there
+  // is money to report — a bare document count stays an inline chip, since a
+  // whole line for "3 docs" would be all frame and no figure.
+  //   icon:  "📄 Doc2md saved $1.8 | pptx 1× $1.55 · pdf 2× $0.27"
+  let doc2mdLine = null;
+  if (!singleLine && doc2mdUsd > 0) {
+    const head = isIcon ? '📄 Doc2md saved' : 'Doc2md saved';
+    const byExt = Array.isArray(doc2md.byExt) ? doc2md.byExt : [];
+    const extText = byExt
+      .map((r) => `${c(GRAY)}${r.ext} ${r.docs}× ${formatMoney(r.usd)}${c(RESET)}`)
+      .join(` ${c(GRAY)}·${c(RESET)} `);
+    doc2mdLine =
+      `${c(GREEN)}${c(BOLD)}${head}${c(RESET)} ` +
+      `${c(GREEN)}${formatMoney(doc2mdUsd)}${c(RESET)}` +
+      (extText ? `  ${c(GRAY)}|${c(RESET)}  ${extText}` : '');
+  }
+
   // Period label honors hour-precision configs (`mode 6h` → "6h", `mode 1d` → "1d").
   // Fall back to legacy `${days}d` when callers haven't supplied a label.
   const periodLabel = options.windowLabel || `${options.days}d`;
@@ -628,6 +672,8 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   // When the totals headline owns line 1, the inline session chip would
   // repeat the same story on line 2 — drop it there.
   if (delegateSeg && want('delegated') && !totalsLine) segs.push(delegateSeg);
+  // Only when it did not already earn a headline line above.
+  if (doc2mdSeg && want('doc2md') && !doc2mdLine) segs.push(doc2mdSeg);
   if (want('hit')) segs.push(hitSeg);
   if (want('ttl')) segs.push(ttlSeg);
   for (const { key, seg } of usageSegs) {
@@ -646,8 +692,17 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   // allowed — --no-color/NO_COLOR consumers expect escape-free output.
   const eol = color ? '\x1b[K' : '';
   const rest = segs.join(' · ') + eol;
+  // Each savings source that earned real money gets a headline line, ordered
+  // biggest saver first — the top line is the one the eye lands on, so it
+  // goes to whichever habit is actually paying for the tool. The diagnostics
+  // line always closes.
+  const headlines = [];
   if (totalsLine && want('delegated')) {
-    return totalsLine + eol + '\n' + rest;
+    headlines.push({ usd: Number(totals && totals.total) || 0, line: totalsLine });
+  }
+  if (doc2mdLine && want('doc2md')) {
+    headlines.push({ usd: doc2mdUsd, line: doc2mdLine });
   }
-  return rest;
+  headlines.sort((a, b) => b.usd - a.usd);
+  return headlines.map((h) => h.line + eol + '\n').join('') + rest;
 }

package/src/installer.js

@@ -394,6 +394,27 @@ export function installDoc2mdHook() {
     settings.hooks.PreToolUse = list;
   }
 
+  // The write guard rides the same command on its own matcher. A conversion
+  // is one-way: an Edit to the cached .md changes nothing the user cares
+  // about, and a Write to the original clobbers a binary with text. Both are
+  // denied with an explanation of where the work should go instead.
+  let addedWriteGuard = false;
+  {
+    const list2 = Array.isArray(settings.hooks.PreToolUse) ? settings.hooks.PreToolUse : [];
+    const hasWriteGuard = list2.some((m) =>
+      m?.matcher === 'Edit|Write'
+      && Array.isArray(m?.hooks) && m.hooks.some((h) => typeof h?.command === 'string' && /doc2md --hook(?!-)/.test(h.command)),
+    );
+    if (!hasWriteGuard) {
+      list2.push({
+        matcher: 'Edit|Write',
+        hooks: [{ type: 'command', command: DOC2MD_HOOK_COMMAND }],
+      });
+      settings.hooks.PreToolUse = list2;
+      addedWriteGuard = true;
+    }
+  }
+
   // The Read hook alone covers only PDFs. Claude Code refuses pptx/xlsx/docx
   // as binary before any PreToolUse hook runs, so for exactly the formats this
   // feature exists for, the tool call is dead before doc2md is consulted.
@@ -412,7 +433,7 @@ export function installDoc2mdHook() {
     }
   }
 
-  if (!hasReadHook || addedPrompt) {
+  if (!hasReadHook || addedPrompt || addedWriteGuard) {
     writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
     return { path: file, action: hasReadHook ? 'updated' : 'created' };
   }