claude-token-saver 3.28.0 → 3.28.2

package/README.en.md

@@ -397,12 +397,18 @@ Three situations, three different interception points:
 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 + editing libs + the .fig parser
-claude-token-saver doc2md on                  # register the Read hook
+claude-token-saver doc2md on                  # register the hooks (the converter installs itself)
 claude-token-saver doc2md                     # check converter + hook registration
 claude-token-saver doc2md report.pptx         # convert by hand and see the result
+claude-token-saver doc2md install-converter   # only to get the install out of the way early
 ```
 
+**The converter installs itself.** Any rollout step a person has to be told about is a step some of them skip, so the converter installs in the background the moment a document first shows up, and converts as soon as it is ready. Measured: about 30s for the first document (15s install plus markitdown's first import), then 3.7s for a new document and 0.1s on a cache hit. The `.fig` parser installs in half a second on the first Figma file.
+
+It installs on first use rather than at `install` time: the venv is 47MB, and someone who never opens a document should not pay for it. Set `CTS_DOC2MD_NO_AUTOINSTALL=1` to turn the automatic install off.
+
+**Python 3.10+ is required** — markitdown's own floor, and macOS still ships 3.9 as `/usr/bin/python3`. The venv is built on an interpreter chosen by version rather than by PATH order. Built on 3.9, pip resolves markitdown to a 2019 placeholder release (0.0.1a1): the install looks like it worked and every conversion then dies at import. This was found by walking into it. When nothing on the machine is new enough, the message points at `brew install python` instead of at an install command that cannot succeed.
+
 The converter goes into a venv this tool owns (`<state dir>/doc2md-venv`): no system interpreter is touched, and uninstalling the CLI takes it along. An existing markitdown on `uv tool` or `PATH` is preferred over building a new one.
 
 Conversion is [markitdown](https://github.com/microsoft/markitdown). Slide numbers, heading levels, tables, speaker notes and per-sheet headings all survive, and non-Latin text comes through intact.
@@ -455,6 +461,23 @@ Conversion is one-way — editing the cached `.md` changes nothing in the source
 
 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.
 
+### Locked documents, and Windows
+
+**A password-protected document is a state, not an error.** Office encrypts by wrapping the package in an OLE compound file rather than a zip, so opening one as a zip used to report "not a zip file" — which reads as a broken download and sends the user after the wrong problem. It is now identified before conversion:
+
+```
+✗ encrypted: password-protected Office file (OLE-wrapped)
+✗ encrypted: password-protected PDF
+```
+
+The model is told to ask for an unlocked copy. This tool never asks for or stores a password, and never blocks the original `Read`, so work continues either way. A PDF that merely restricts printing still opens and still converts — checked against a false positive — and a legacy `.xls`, which is an OLE file by design, is not mistaken for an encrypted one.
+
+**Windows is supported.** For teams with Windows machines:
+
+- The Python search uses the `py -3` launcher. `python3` is rarely on PATH there, and a bare `python` may be the Store alias stub that opens a web page instead of running anything. Venv interpreters are looked for at `Scripts\python.exe`.
+- The `.fig` parser installs through `npm.cmd` via the shell, and the package spec dropped its caret (`openfig-core@0.4.x`): in cmd.exe `^` is the escape character and never reaches npm.
+- The background install and every child process set `windowsHide`, so no console window appears in the middle of someone's prompt.
+
 `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)

package/README.md

@@ -389,12 +389,18 @@ doc2md 는 그 파일을 한 번 변환해 두고 원본 대신 변환본을 읽
 두 번째 줄의 제약은 실측으로 확인한 것입니다. `.pdf` 를 Read 하면 훅이 실행되고, 같은 세션에서 `.pptx` 를 Read 하면 훅 로그에 아무 기록도 남지 않습니다.
 
 ```bash
-claude-token-saver doc2md install-converter   # markitdown·편집 라이브러리·.fig 파서 설치
-claude-token-saver doc2md on                  # Read 훅 등록
+claude-token-saver doc2md on                  # 훅 등록 (변환기는 첫 문서에서 자동 설치)
 claude-token-saver doc2md                     # 변환기·훅 등록 상태 확인
 claude-token-saver doc2md 보고서.pptx          # 직접 변환해 결과 확인
+claude-token-saver doc2md install-converter   # 설치를 미리 끝내 두고 싶을 때만
 ```
 
+**변환기는 알아서 깔립니다.** 팀에 배포할 때 각자 설치 명령을 실행하게 만들면 그 단계에서 빠지는 사람이 생깁니다. 그래서 문서가 처음 등장하는 시점에 변환기가 백그라운드로 설치되고, 설치가 끝나는 대로 곧바로 변환합니다. 실측으로 첫 문서는 약 30초(설치 15초 + markitdown 최초 임포트), 이후로는 새 문서 3.7초, 캐시 적중 0.1초입니다. `.fig` 파서는 첫 Figma 파일에서 0.5초 만에 깔립니다.
+
+설치는 `install` 단계가 아니라 첫 사용 시점에 합니다. venv 가 47MB 라서, 문서를 다루지 않는 사람은 낼 이유가 없는 비용입니다. 자동 설치를 끄려면 `CTS_DOC2MD_NO_AUTOINSTALL=1` 을 설정하십시오.
+
+**파이썬 3.10 이상이 필요합니다.** markitdown 의 요구 사항이고, macOS 기본 `/usr/bin/python3` 는 3.9 입니다. 이 도구는 PATH 순서를 따르지 않고 3.10 이상인 인터프리터를 골라 venv 를 만듭니다. 3.9 로 만들면 pip 가 markitdown 을 2019 년 자리표시자 릴리스(0.0.1a1)로 해석해서, 설치는 성공한 것처럼 보이지만 모든 변환이 임포트 단계에서 죽습니다. 실제로 이 함정을 밟고 잡았습니다. 3.10 이상이 아예 없으면 설치 명령을 안내하는 대신 `brew install python` 을 안내합니다.
+
 변환기는 도구 전용 venv(`<상태 디렉터리>/doc2md-venv`)에 설치합니다. 시스템 파이썬을 건드리지 않고, CLI를 지우면 함께 사라집니다. 이미 `uv tool` 이나 다른 경로에 markitdown 이 있으면 그쪽을 먼저 씁니다.
 
 변환은 [markitdown](https://github.com/microsoft/markitdown)이 담당하며, 슬라이드 번호와 제목 계층, 표, 발표자 노트, 시트 구분이 모두 남습니다. 한글도 깨지지 않습니다.
@@ -451,6 +457,23 @@ PDF 는 첨부하면 모델이 내용을 그대로 읽습니다. 대신 페이
 
 네 형식 모두 실제로 몇 바퀴 돌려 검증했습니다(2026-09-06): docx 텍스트 치환 10건과 3회 연속 재저장, pptx 막대→꺾은선 차트 교체와 데이터 행 추가, xlsx 값 정정·행 추가, fig 텍스트 수정·재인코드·재파싱. 전 케이스에서 원본은 바이트 그대로였고, 수정본 재변환에 변경 내용이 반영됐습니다. 한 가지 주의: pptx 에서 차트 도형을 제거하면 옛 차트 XML 파트가 고아로 남습니다. PowerPoint 는 무시하지만, 깔끔히 하려면 파트와 rels 도 지우십시오. 차트·이미지 같은 시각 요소는 변환본에 잡히지 않으므로, 시각 편집의 최종 확인은 해당 프로그램에서 해야 합니다.
 
+### 암호가 걸린 문서와 Windows
+
+**암호 문서는 오류가 아니라 상태로 다룹니다.** 사내에서 받는 문서 중 일부는 암호가 걸려 있습니다. 이전에는 암호 걸린 docx 를 "손상된 zip"이라고 알려서 사용자가 원인을 엉뚱한 곳에서 찾게 만들었습니다. 암호가 걸린 Office 문서는 zip 이 아니라 OLE 복합 문서로 저장되기 때문입니다. 지금은 변환 전에 판별해서 이렇게 알립니다.
+
+```
+✗ encrypted: password-protected Office file (OLE-wrapped)
+✗ encrypted: password-protected PDF
+```
+
+모델에게는 암호를 푼 사본을 사용자에게 요청하라고 안내합니다. 이 도구는 암호를 묻지도 저장하지도 않습니다. 어느 경우에도 원본 `Read` 를 막지 않으므로 작업이 중단되지 않습니다. 열람은 자유롭고 인쇄만 제한된 PDF 는 암호 문서가 아니므로 그대로 변환합니다(오탐 확인 완료). 구형 `.xls` 도 원래 OLE 형식이라 암호로 오인하지 않습니다.
+
+**Windows 를 지원합니다.** 사내에 Windows 사용자가 있어 다음을 맞췄습니다.
+
+- 파이썬 탐색이 `py -3` 런처를 씁니다. Windows 에서는 `python3` 가 PATH 에 없는 경우가 많고, 맨 `python` 은 실행 대신 마이크로소프트 스토어를 여는 별칭 스텁일 수 있습니다. venv 기반 인터프리터도 `Scripts\python.exe` 경로로 찾습니다.
+- `.fig` 파서 설치가 `npm.cmd` 를 셸로 호출합니다. 그리고 패키지 지정자에서 캐럿을 뺐습니다(`openfig-core@0.4.x`). cmd.exe 에서 `^` 는 이스케이프 문자라 npm 에 닿기 전에 먹힙니다.
+- 백그라운드 자동 설치와 모든 하위 프로세스에 `windowsHide` 를 걸어, 프롬프트 도중에 콘솔 창이 튀어나오지 않게 했습니다.
+
 `claude-token-saver doc2md --clean` 으로 변환 캐시를 비우고, `doc2md off` 로 훅을 제거합니다. 훅 해제는 자기 항목만 골라 지우므로 `PreToolUse` 에 등록해 둔 다른 훅은 그대로 남습니다.
 
 ## 🌐 Bedrock·Vertex 경유 환경

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "3.28.0",
+  "version": "3.28.2",
   "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

@@ -43,6 +43,55 @@ def fail(reason, detail=""):
     sys.exit(0)
 
 
+# A password-protected OOXML file is not a zip at all: Office wraps the whole
+# package in an OLE compound file whose streams hold the ciphertext. Opening it
+# as a zip therefore reports "not a zip file", which reads as a broken download
+# and sends the user looking for the wrong problem.
+OLE_MAGIC = b"\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1"
+
+
+def encryption_problem(path, ext):
+    """('encrypted', detail) when the file is password-protected, else None."""
+    try:
+        with open(path, "rb") as fh:
+            head = fh.read(8)
+    except OSError:
+        return None
+
+    # Legacy .xls is an OLE file by design, so the magic alone proves nothing
+    # there. For the modern formats it can only mean encryption.
+    if ext in ZIP_EXTS and head == OLE_MAGIC:
+        return ("encrypted", "password-protected Office file (OLE-wrapped)")
+
+    # Some producers keep the zip container and put the ciphertext inside it.
+    if ext in ZIP_EXTS:
+        try:
+            import zipfile
+            with zipfile.ZipFile(path) as z:
+                names = z.namelist()
+            if any(n.startswith("EncryptedPackage") for n in names):
+                return ("encrypted", "password-protected Office file")
+        except Exception:
+            return None
+
+    if ext == ".pdf":
+        try:
+            from pdfminer.pdfparser import PDFParser
+            from pdfminer.pdfdocument import PDFDocument
+            with open(path, "rb") as fh:
+                doc = PDFDocument(PDFParser(fh))
+            # An empty owner password is the ordinary "printing restricted"
+            # case, which extracts fine. Only a document that refuses to open
+            # counts as encrypted here.
+            if doc.encryption is not None and not doc.is_extractable:
+                return ("encrypted", "password-protected PDF")
+        except Exception as e:
+            if "password" in str(type(e).__name__).lower() or "password" in str(e).lower():
+                return ("encrypted", "password-protected PDF")
+            return None
+    return None
+
+
 def check_zip(path):
     """Classify an archive before opening it as a document.
 
@@ -189,6 +238,13 @@ def main():
         fail("missing", path)
 
     ext = os.path.splitext(path)[1].lower()
+
+    # Checked before anything else opens the file: an encrypted document is a
+    # normal thing to receive, not a failure to report as corruption.
+    locked = encryption_problem(path, ext)
+    if locked:
+        fail(locked[0], locked[1])
+
     if ext in ZIP_EXTS:
         problem = check_zip(path)
         if problem:
@@ -224,6 +280,11 @@ def main():
         result = MarkItDown().convert(path)
         text = (result.text_content or "").strip()
     except Exception as e:
+        # markitdown surfaces the password failure from whichever backend hit
+        # it, so the type name is the reliable part.
+        blob = (type(e).__name__ + " " + str(e)).lower()
+        if "password" in blob or "encrypted" in blob:
+            fail("encrypted", "the file is password-protected")
         fail("convert-failed", e)
 
     if not text:

package/src/doc2md.cjs

@@ -26,7 +26,7 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const crypto = require('node:crypto');
-const { spawnSync } = require('node:child_process');
+const { spawn, 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
@@ -226,28 +226,62 @@ function writeCache(filePath, markdown, extra) {
  * memoized for the life of this process, and the caller memoizes across
  * processes through the notice file.
  */
+// The readiness test for an interpreter. Importing the *class* matters: a pip
+// install creates the package directory long before it finishes writing into
+// it, so a bare `import markitdown` reports success mid-install and the
+// conversion then fails with "cannot import name 'MarkItDown'". Measured
+// during the first-use auto-install, where the window is about a second wide.
+const PROBE = 'from markitdown import MarkItDown';
+
+const IS_WINDOWS = process.platform === 'win32';
+
+/**
+ * Interpreters to try, as `{ bin, args }` so the Windows launcher can carry
+ * its version flag. `py -3` is how a Windows box usually reaches Python at
+ * all: `python3` is rarely on PATH there, and a bare `python` may be the App
+ * Execution Alias stub that opens the Microsoft Store instead of running
+ * anything.
+ */
+function interpreterCandidates() {
+  const out = [];
+  if (process.env.CTS_DOC2MD_PYTHON) out.push({ bin: process.env.CTS_DOC2MD_PYTHON, args: [] });
+  // The tool's own venv, created by `doc2md install-converter`. First because
+  // it is the only one this tool controls: telling people to `pip install`
+  // into the system interpreter is how a token-saving CLI ends up owning a
+  // break in someone else's project.
+  out.push({ bin: managedPython(), args: [] });
+  if (IS_WINDOWS) {
+    out.push(
+      { bin: path.join(os.homedir(), '.local', 'share', 'uv', 'tools', 'markitdown', 'Scripts', 'python.exe'), args: [] },
+      { bin: 'py', args: ['-3'] },
+      { bin: 'python', args: [] },
+    );
+  } else {
+    out.push(
+      { bin: path.join(os.homedir(), '.local', 'share', 'uv', 'tools', 'markitdown', 'bin', 'python'), args: [] },
+      { bin: path.join(os.homedir(), '.local', 'bin', 'markitdown-python'), args: [] },
+      { bin: 'python3', args: [] },
+      { bin: 'python', args: [] },
+    );
+  }
+  return out;
+}
+
 let interpreterCache;
 function findInterpreter() {
   if (interpreterCache !== undefined) return interpreterCache;
-  const candidates = [];
-  if (process.env.CTS_DOC2MD_PYTHON) candidates.push(process.env.CTS_DOC2MD_PYTHON);
-  candidates.push(
-    // The tool's own venv, created by `doc2md install-converter`. First
-    // because it is the only one this tool controls: telling people to
-    // `pip install` into the system interpreter is how a token-saving CLI
-    // ends up owning a break in someone else's project.
-    managedPython(),
-    path.join(os.homedir(), '.local', 'share', 'uv', 'tools', 'markitdown', 'bin', 'python'),
-    path.join(os.homedir(), '.local', 'bin', 'markitdown-python'),
-    'python3',
-    'python',
-  );
-  for (const bin of candidates) {
+  for (const { bin, args } of interpreterCandidates()) {
     try {
-      const probe = spawnSync(bin, ['-c', 'import markitdown'], { timeout: 20_000, stdio: 'ignore' });
+      const probe = spawnSync(bin, [...args, '-c', PROBE], {
+        timeout: 20_000,
+        stdio: 'ignore',
+        windowsHide: true,
+      });
       if (probe.status === 0) {
-        interpreterCache = bin;
-        return bin;
+        // Only a bare interpreter is cached as a string; the launcher form
+        // keeps its flag, since dropping it would run the wrong Python.
+        interpreterCache = args.length ? { bin, args } : bin;
+        return interpreterCache;
       }
     } catch { /* candidate unusable, try the next */ }
   }
@@ -255,6 +289,11 @@ function findInterpreter() {
   return null;
 }
 
+/** Split a `findInterpreter()` result into the pair spawnSync wants. */
+function interpreterParts(found) {
+  return typeof found === 'string' ? { bin: found, args: [] } : found;
+}
+
 const CONVERTER = path.join(__dirname, '..', 'presets', 'doc2md', 'convert.py');
 
 /** Path to the interpreter inside the venv this tool manages. */
@@ -281,19 +320,72 @@ const EDIT_LIBS = ['python-pptx', 'python-docx', 'openpyxl'];
  * for, it goes somewhere this tool owns, so uninstalling the CLI takes the
  * whole thing with it and no system interpreter is touched.
  */
+/**
+ * A Python new enough to run markitdown (3.10+), or null.
+ *
+ * Explicit version names are tried before the bare `python3` so a modern
+ * Homebrew interpreter wins over the system one regardless of PATH order.
+ */
+function findVenvBase() {
+  const candidates = IS_WINDOWS
+    ? [
+      // The launcher first, asked for each version in turn: it knows about
+      // installs that never touched PATH, which is the normal case on
+      // Windows.
+      { bin: 'py', args: ['-3.14'] }, { bin: 'py', args: ['-3.13'] },
+      { bin: 'py', args: ['-3.12'] }, { bin: 'py', args: ['-3.11'] },
+      { bin: 'py', args: ['-3.10'] }, { bin: 'py', args: ['-3'] },
+      { bin: 'python', args: [] },
+    ]
+    : [
+      { bin: 'python3.14', args: [] }, { bin: 'python3.13', args: [] },
+      { bin: 'python3.12', args: [] }, { bin: 'python3.11', args: [] },
+      { bin: 'python3.10', args: [] },
+      { bin: 'python3', args: [] }, { bin: 'python', args: [] },
+    ];
+  for (const { bin, args } of candidates) {
+    const r = spawnSync(bin, [...args, '-c', 'import sys; print("%d.%d" % sys.version_info[:2])'], {
+      encoding: 'utf8',
+      timeout: 20_000,
+      windowsHide: true,
+    });
+    if (r.status !== 0) continue;
+    const [major, minor] = String(r.stdout).trim().split('.').map(Number);
+    if (major > 3 || (major === 3 && minor >= 10)) {
+      return { bin, args, version: `python ${major}.${minor}` };
+    }
+  }
+  return null;
+}
+
 function installConverter({ onProgress = () => {} } = {}) {
   const venv = path.join(userDataDir(), 'doc2md-venv');
   const target = managedPython();
 
   if (!fs.existsSync(target)) {
-    onProgress(`creating ${venv}`);
-    let created = false;
-    for (const base of ['python3', 'python']) {
-      const r = spawnSync(base, ['-m', 'venv', venv], { encoding: 'utf8', timeout: 180_000 });
-      if (r.status === 0) { created = true; break; }
+    // The base interpreter is chosen by version, not by whichever `python3`
+    // comes first on PATH. markitdown needs 3.10+, and macOS still ships 3.9
+    // as /usr/bin/python3: building the venv on that one installs a
+    // seven-year-old placeholder release (0.0.1a1) that has no MarkItDown
+    // class in it, and every conversion then fails at import time. Measured
+    // on this machine, where /usr/bin/python3 precedes Homebrew's 3.14.
+    const base = findVenvBase();
+    if (!base) {
+      return {
+        ok: false,
+        reason: 'no-python',
+        detail: 'markitdown needs Python 3.10 or newer; none was found on PATH '
+          + '(macOS /usr/bin/python3 is 3.9 — install a newer one, e.g. `brew install python`)',
+      };
     }
-    if (!created) {
-      return { ok: false, reason: 'no-python', detail: 'no python3 with the venv module on PATH' };
+    onProgress(`creating ${venv} (${base.version})`);
+    const r = spawnSync(base.bin, [...(base.args || []), '-m', 'venv', venv], {
+      encoding: 'utf8',
+      timeout: 180_000,
+      windowsHide: true,
+    });
+    if (r.status !== 0) {
+      return { ok: false, reason: 'no-python', detail: (r.stderr || 'venv creation failed').slice(0, 300) };
     }
   }
 
@@ -301,6 +393,7 @@ function installConverter({ onProgress = () => {} } = {}) {
   const install = spawnSync(target, ['-m', 'pip', 'install', '--quiet', MARKITDOWN_SPEC, ...EDIT_LIBS], {
     encoding: 'utf8',
     timeout: 900_000,
+    windowsHide: true,
   });
   if (install.status !== 0) {
     return { ok: false, reason: 'pip-failed', detail: (install.stderr || '').slice(0, 400) };
@@ -308,7 +401,7 @@ function installConverter({ onProgress = () => {} } = {}) {
 
   // The probe is the actual acceptance test: pip can exit 0 and still leave an
   // interpreter that cannot import what was asked for.
-  const probe = spawnSync(target, ['-c', 'import markitdown'], { timeout: 60_000, stdio: 'ignore' });
+  const probe = spawnSync(target, ['-c', PROBE], { timeout: 60_000, stdio: 'ignore', windowsHide: true });
   if (probe.status !== 0) {
     return { ok: false, reason: 'import-failed', detail: 'installed, but markitdown does not import' };
   }
@@ -320,8 +413,8 @@ function installConverter({ onProgress = () => {} } = {}) {
 /**
  * Convert one file. Returns `{ ok: true, cacheFile, meta }`, or
  * `{ ok: false, reason, detail }` where reason is one of:
- *   no-markitdown | too-large | sensitive | unsafe-archive | no-text |
- *   convert-failed | timeout
+ *   no-markitdown | python-too-old | no-figparser | encrypted | too-large |
+ *   sensitive | unsafe-archive | no-text | convert-failed | timeout
  *
  * Every failure is a reason to leave the original Read alone, never to break
  * it. That is the whole contract with the hook.
@@ -370,7 +463,14 @@ function convert(filePath, { converter = CONVERTER, python: pythonOverride = nul
   // 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);
+    let result = spawnFigConvert(fig2md, filePath);
+    // The .fig parser is an npm install of a few hundred KB, fast enough to
+    // wait for inline the first time a Figma file turns up.
+    if (!result.ok && result.reason === 'no-figparser'
+        && process.env.CTS_DOC2MD_NO_AUTOINSTALL !== '1') {
+      fig2md.installFigParser(userDataDir());
+      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,
@@ -381,13 +481,29 @@ function convert(filePath, { converter = CONVERTER, python: pythonOverride = nul
   // 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.
-  const python = pythonOverride || findInterpreter();
+  let python = pythonOverride || findInterpreter();
+  if (!python && !pythonOverride) {
+    // Telling someone to run the install command is wrong when the install
+    // cannot succeed on this machine. A too-old interpreter is a different
+    // problem with a different fix, so it gets its own reason rather than
+    // hiding behind "no converter".
+    if (!findVenvBase()) {
+      return {
+        ok: false,
+        reason: 'python-too-old',
+        detail: 'markitdown needs Python 3.10 or newer; none was found on PATH',
+      };
+    }
+    if (ensureConverterInstalled()) python = findInterpreter();
+  }
   if (!python) return { ok: false, reason: 'no-markitdown' };
 
-  const run = spawnSync(python, [converter, filePath], {
+  const py = interpreterParts(python);
+  const run = spawnSync(py.bin, [...py.args, converter, filePath], {
     encoding: 'utf8',
     timeout: CONVERT_TIMEOUT_MS,
     maxBuffer: MAX_MARKDOWN_BYTES * 4,
+    windowsHide: true,
   });
   if (run.error && run.error.code === 'ETIMEDOUT') return { ok: false, reason: 'timeout' };
   if (run.status !== 0) {
@@ -421,6 +537,75 @@ function convert(filePath, { converter = CONVERTER, python: pythonOverride = nul
   return { ok: true, cached: false, cacheFile: written.cacheFile, meta: written.meta };
 }
 
+/**
+ * First-use install, so nobody has to be told to run a setup command.
+ *
+ * A team rollout dies on any step a person has to be told about, so the
+ * converter installs itself the first time a document actually shows up. It
+ * is still lazy rather than part of `install`: the venv is 47MB, and someone
+ * who never opens a document should never pay for it.
+ *
+ * The install runs detached and the caller waits only briefly. A cold install
+ * measured 6 seconds on a fast connection, but a corporate network can be far
+ * slower, and a hook that blocks a prompt for a minute is worse than a
+ * document that converts on the next turn. So: start it, wait up to
+ * `waitMs`, and if it is still going, say so and let this turn proceed
+ * without the conversion.
+ *
+ * Returns true when a converter is ready to use right now.
+ */
+function ensureConverterInstalled({ waitMs = 15_000 } = {}) {
+  if (process.env.CTS_DOC2MD_NO_AUTOINSTALL === '1') return false;
+  if (findInterpreter()) return true;
+
+  const lock = path.join(userDataDir(), 'doc2md-install.lock');
+  let running = false;
+  try {
+    const started = JSON.parse(fs.readFileSync(lock, 'utf8')).startedAt;
+    // A lock older than the pip timeout is a crashed run, not a live one.
+    running = Number.isFinite(started) && Date.now() - started < 900_000;
+  } catch { /* no lock, or an unreadable one: treat as not running */ }
+
+  if (!running) {
+    try {
+      fs.mkdirSync(userDataDir(), { recursive: true });
+      fs.writeFileSync(lock, JSON.stringify({ startedAt: Date.now() }));
+      const cli = path.join(__dirname, '..', 'bin', 'cli.js');
+      // Detached, so a session that ends mid-install does not take the
+      // install with it — the next session finds it finished.
+      const child = spawn(process.execPath, [cli, 'doc2md', 'install-converter'], {
+        detached: true,
+        stdio: 'ignore',
+        // Without this Windows pops a console window for the install, in the
+        // middle of someone's prompt.
+        windowsHide: true,
+      });
+      child.unref();
+    } catch {
+      try { fs.rmSync(lock, { force: true }); } catch { /* best effort */ }
+      return false;
+    }
+  }
+
+  // Poll cheaply: the interpreter file appearing is the first sign, and the
+  // import probe is the acceptance test. interpreterCache has to be cleared
+  // or the memoized null from the top of this function would stick.
+  const deadline = Date.now() + waitMs;
+  while (Date.now() < deadline) {
+    if (fs.existsSync(managedPython())) {
+      interpreterCache = undefined;
+      if (findInterpreter()) {
+        try { fs.rmSync(lock, { force: true }); } catch { /* best effort */ }
+        return true;
+      }
+    }
+    // A synchronous sleep, because every caller here is synchronous. 400ms
+    // keeps the poll count low over a 15s wait.
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 400);
+  }
+  return false;
+}
+
 /** Where the "markitdown is not installed" notice records that it was shown. */
 function noticePath() {
   return path.join(userDataDir(), 'doc2md-notice.json');
@@ -490,9 +675,26 @@ function decideForRead(context, opts = {}) {
     markNoticeShown();
     return {
       deny: false,
-      reason: `[doc2md] ${name} 를 변환하려 했으나 markitdown 이 설치되어 있지 않습니다.\n`
-        + `  설치: ${INSTALL_HINT}\n`
-        + '  설치 전까지는 원본을 그대로 읽습니다. 이 안내는 한 번만 표시됩니다.',
+      reason: `[doc2md] ${name} 를 변환할 변환기를 지금 설치하고 있습니다(첫 실행에만 걸립니다).\n`
+        + '  설치가 끝나면 다음 요청부터 자동으로 변환합니다. 이번 turn 은 원본을 그대로 읽습니다.\n'
+        + `  진행 상황: ${INSTALL_HINT} 를 직접 실행하면 설치 로그를 볼 수 있습니다.`,
+    };
+  }
+  if (result.reason === 'encrypted') {
+    return {
+      deny: false,
+      reason: `[doc2md] ${name} 는 암호가 걸린 문서라 변환하지 못했습니다. `
+        + '사용자에게 암호를 푼 사본을 요청하십시오. 이 도구는 암호를 묻거나 저장하지 않습니다.',
+    };
+  }
+  if (result.reason === 'python-too-old') {
+    if (noticeAlreadyShown()) return null;
+    markNoticeShown();
+    return {
+      deny: false,
+      reason: `[doc2md] ${name} 를 변환하지 못했습니다. 변환기(markitdown)는 Python 3.10 이상이 필요한데 PATH 에서 찾지 못했습니다.\n`
+        + '  macOS 기본 /usr/bin/python3 는 3.9 입니다. `brew install python` 으로 새 버전을 설치한 뒤 다시 시도하십시오.\n'
+        + '  그때까지는 원본을 그대로 읽습니다. 이 안내는 한 번만 표시됩니다.',
     };
   }
   if (result.reason === 'no-text') {
@@ -613,8 +815,16 @@ function contextForPrompt(payload, opts = {}) {
       }
     } else if (result.reason === 'no-markitdown') {
       lines.push(lang === 'ko'
-        ? `  ${name}: 변환기가 없어 변환하지 못했습니다. 설치: ${INSTALL_HINT}`
-        : `  ${name}: no converter installed. Install it with: ${INSTALL_HINT}`);
+        ? `  ${name}: 변환기를 설치하는 중입니다(첫 실행에만 걸립니다). 설치가 끝나면 다음 요청부터 자동 변환됩니다.`
+        : `  ${name}: the converter is installing now (first run only). It will convert automatically from the next request.`);
+    } else if (result.reason === 'encrypted') {
+      lines.push(lang === 'ko'
+        ? `  ${name}: 암호가 걸린 문서입니다. 암호를 푼 사본을 달라고 사용자에게 요청하십시오.`
+        : `  ${name}: the document is password-protected. Ask the user for an unlocked copy.`);
+    } else if (result.reason === 'python-too-old') {
+      lines.push(lang === 'ko'
+        ? `  ${name}: 변환기가 Python 3.10 이상을 요구하는데 PATH 에 없습니다(macOS 기본은 3.9). \`brew install python\` 후 다시 시도하도록 사용자에게 안내하십시오.`
+        : `  ${name}: the converter needs Python 3.10+, and none is on PATH (macOS ships 3.9). Tell the user to install a newer Python, e.g. \`brew install python\`.`);
     } else if (result.reason === 'no-figparser') {
       lines.push(lang === 'ko'
         ? `  ${name}: .fig 파서가 없어 변환하지 못했습니다. 설치: claude-token-saver doc2md install-converter`
@@ -744,6 +954,10 @@ module.exports = {
   MARKITDOWN_SPEC,
   managedPython,
   installConverter,
+  ensureConverterInstalled,
+  findVenvBase,
+  interpreterCandidates,
+  interpreterParts,
   clearNotice,
   cacheDir,
   cachePathFor,

package/src/fig2md.cjs

@@ -28,7 +28,10 @@ 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';
+// `0.4.x` rather than `^0.4.1` on purpose: the Windows install goes through
+// cmd.exe, where `^` is the escape character and would be eaten before npm
+// ever saw it. The range is the same one caret means for a 0.x package.
+const FIG_PARSER_SPEC = 'openfig-core@0.4.x';
 
 /** Where the on-demand parser install lives, under the tool's state dir. */
 function managedFigDir(userDataDir) {
@@ -56,10 +59,16 @@ function installFigParser(userDataDir, { onProgress = () => {} } = {}) {
     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], {
+  // npm on Windows is npm.cmd, which spawnSync cannot execute directly — it
+  // needs the shell. Elsewhere the shell is avoided, since the package spec
+  // would then go through shell quoting for no benefit.
+  const isWindows = process.platform === 'win32';
+  const r = spawnSync(isWindows ? 'npm.cmd' : 'npm', ['install', '--no-audit', '--no-fund', '--silent', FIG_PARSER_SPEC], {
     cwd: dir,
     encoding: 'utf8',
     timeout: 300_000,
+    windowsHide: true,
+    shell: isWindows,
   });
   if (r.status !== 0) {
     return { ok: false, reason: 'npm-failed', detail: (r.stderr || '').slice(0, 400) };