@kaydash9999/banker-plugins 0.20.1 → 0.20.5

package/skills/payload-mon/SKILL.md

@@ -40,9 +40,10 @@ node "<이 스킬 디렉터리 절대경로>/scripts/payload-mon.mjs" <on|off|st
 
 - `on`: Claude Code 설정 폴더(`$CLAUDE_CONFIG_DIR`, 없으면 `~/.claude`)의 `hud/omc-hud-custom.mjs` 에서, ctx 를 넣는 줄 바로 뒤에 `// >>> payload-mon >>>` 블록 하나를 넣는다.
   블록이 불러오는 추정 모듈은 래퍼 옆 `hud/payload-mon/payload-size.mjs` 에 사본으로 둔다. 플러그인 설치 경로는 버전마다 바뀌어 업데이트 뒤에 사라지기 때문이다.
+  래퍼 파일이 다른 곳을 가리키는 링크면 사본은 그 파일 옆에 둔다. 래퍼 v4 가 그 자리에서 사본을 먼저 찾기 때문이다.
   이미 켜져 있으면 래퍼를 바꾸지 않고, 모듈 사본이 이 버전과 다를 때만 사본을 맞춘다. 예전 방식(블록 2개)으로 켜져 있었다면 새 방식으로 바꾼다.
   바꾸기 전 내용은 `omc-hud-custom.mjs.payload-mon.bak` 에 남는다.
-- `off`: 그 블록만 빼서 래퍼를 켜기 전 상태로 되돌리고, 모듈 사본과 추정치 캐시를 지운다. 래퍼 v4 에서는 모듈 사본이 없어져 `PL:` 칸도 사라진다.
+- `off`: 그 블록만 빼서 래퍼를 켜기 전 상태로 되돌리고, 모듈 사본과 추정치 캐시를 지운다. 래퍼 v4 에서는 모듈 사본이 없어져 `PL:` 칸도 사라진다. 사본 폴더가 링크면 사본을 지우지 않고 그렇다고 알린다(`PL:` 칸이 남는다).
 - `status`: 켜짐·꺼짐, 모듈 사본이 이 버전과 같은지, statusLine 이 이 래퍼를 쓰는지, 현재 세션의 추정치를 보여 준다.
 - 같은 래퍼에 자기 표시 블록을 넣는 다른 도구가 있어도 서로의 블록을 건드리지 않는다.
 
@@ -59,7 +60,9 @@ node "<이 스킬 디렉터리 절대경로>/scripts/payload-mon.mjs" <on|off|st
   플러그인 파일을 손으로 고치지 말고, banker 를 최신으로 올린 뒤(`update-banker`) 다시 시도한다. 그래도 안 되면 banker 이슈로 알린다.
 - "node --check 실패": 블록을 넣은 결과가 문법 검사를 통과하지 못했다(예: 래퍼가 ctx 를 넣는 줄을 비동기가 아닌 함수 안으로 옮김). 파일은 그대로다.
 - "래퍼에 쓸 권한이 없습니다", 또는 `status` 의 "HUD 래퍼를 읽을 수 없음": 래퍼 파일의 권한을 확인한다. 파일은 그대로다.
-- "모듈 사본을 쓰지 못했습니다": 래퍼 옆 `hud/payload-mon/` 에 쓸 수 없다(권한, 같은 이름의 파일, 디스크 공간). 래퍼는 그대로다.
+- "모듈 사본을 쓰지 못했습니다": 래퍼 옆(래퍼 파일이 링크면 링크가 가리키는 파일 옆) `payload-mon/` 에 쓸 수 없다(권한, 같은 이름의 파일, 디스크 공간). 래퍼는 그대로다.
+  `사본 폴더가 링크입니다` 면 그 폴더가 다른 곳을 가리키는 링크다. 이 도구는 링크 너머에 쓰거나 지우지 않는다. 링크를 일반 폴더로 바꾼 뒤 다시 켠다.
+  `사본 폴더가 쓰는 동안 바뀌었습니다` 면 쓰는 사이 그 폴더가 다른 것(링크, 다른 폴더)으로 바뀌었거나, 바뀌었다 돌아와 사본이 폴더에 없다. 바뀐 자리의 사본은 이 도구가 쓴 그 파일이고 바이트도 같을 때만 거뒀다(원래 거기 있던 다른 래퍼의 사본은 둔다). 바뀌었다 돌아온 사이 다른 곳에 간 사본은 거두지 못한다. 폴더를 확인한 뒤 다시 켠다.
 - "표시(>>> / <<<)의 짝이 맞지 않습니다": 래퍼에 payload-mon 표시 줄이 한쪽만 남았다. `on`·`off` 모두 거부하므로, 손으로 고치지 말라는 원칙의 유일한 예외다.
   `setup-omc-hud` 로 HUD 를 재설치하거나, 래퍼에서 짝 없이 남은 `// >>> payload-mon >>>` 또는 `// <<< payload-mon <<<` 줄을 지운 뒤 다시 실행한다.
 - HUD 를 재설치한 뒤 payload 가 안 보이면 `on` 을 다시 실행한다. `setup-omc-hud` 는 설치할 때마다 이 스킬을 늘 켠다(래퍼 v4 의 `PL:` 칸이 모듈 사본을 씀).

package/skills/payload-mon/scripts/payload-mon.mjs

@@ -25,6 +25,14 @@
  * install lives under a versioned path that the next update retires, and an
  * import pointing there would go dark without a word. `on` writes the copy and
  * refreshes it when this version's module differs; `status` says when it does.
+ * When the wrapper file itself is a symlink, the copy goes beside the file it
+ * points at, where wrapper v4 looks first. A copy folder (payload-mon/) that is
+ * itself a link is neither written nor emptied through: `on` refuses it, and
+ * also refuses (taking its copy back) when the folder changes while it writes.
+ *
+ * The block takes the ctx line's line ending, so a CRLF wrapper stays CRLF, and
+ * a block whose line endings an editor rewrote still counts as on. A wrapper
+ * that starts with a BOM is taken as it is.
  *
  * `on` converges on the current block and is a no-op when it is in place. It
  * writes only into the OMC custom HUD (signature-gated); `off` removes only
@@ -39,6 +47,7 @@ import {
   accessSync,
   constants,
   existsSync,
+  lstatSync,
   mkdirSync,
   mkdtempSync,
   readdirSync,
@@ -56,7 +65,10 @@ import { CACHE_DIR, clearCache, estimatePayloadBytes, REQUEST_LIMIT_BYTES, SHOW_
 
 const OPEN = "// >>> payload-mon >>>";
 const CLOSE = "// <<< payload-mon <<<";
-const BLOCKS = /^[ \t]*\/\/ >>> payload-mon >>>[\s\S]*?\/\/ <<< payload-mon <<<[ \t]*\r?\n/gm;
+export const BLOCKS = /^[ \t]*\/\/ >>> payload-mon >>>[\s\S]*?\/\/ <<< payload-mon <<<[ \t]*\r?\n/gm;
+// The closing line. No block reaches past the last one, so the pattern runs only on the text before it:
+// otherwise every stray opening line scans to the end again (a 2MB file of them took 28s).
+export const CLOSE_LINE = /\/\/ <<< payload-mon <<<[ \t]*\r?\n/g;
 // The block goes right after the line that adds ctx.
 const CTX_LINE = /^ {2}if \(f\.ctx\) colored\.push\(colorCtx\(f\.ctx\)\);\r?\n/m;
 // The statusline JSON the block reads, in either layout.
@@ -86,13 +98,29 @@ const DEFAULTS = {
   sessionId: process.env.CLAUDE_CODE_SESSION_ID,
 };
 
-// Where the block's module lives: beside the wrapper, outside any versioned path.
-const moduleCopy = (hudFile) => join(dirname(hudFile), "payload-mon", "payload-size.mjs");
+// The file a wrapper that is itself a symlink (dotfiles) points at; any other path as it is. A wrapper
+// reached through a linked folder keeps the path as configured.
+function linkTarget(hudFile) {
+  try {
+    return lstatSync(hudFile).isSymbolicLink() ? realpathSync(hudFile) : hudFile;
+  } catch {
+    return hudFile;
+  }
+}
+// Where the block's module lives: beside the wrapper, outside any versioned path. For a wrapper file
+// that is a link, beside the file it points at: wrapper v4 resolves its own path through the link and
+// looks there for its PL segment.
+const moduleCopy = (hudFile) => join(dirname(linkTarget(hudFile)), "payload-mon", "payload-size.mjs");
+// Where 0.20.1 put the copy for such a link; `off` clears it too.
+const besideLink = (hudFile) => join(dirname(hudFile), "payload-mon", "payload-size.mjs");
 const moduleUrl = (hudFile) => pathToFileURL(moduleCopy(hudFile)).href;
 
+// The ctx line's line ending, which the block takes so that a CRLF wrapper stays CRLF.
+const eolOf = (src) => (CTX_LINE.exec(src)?.[0].endsWith("\r\n") ? "\r\n" : "\n");
+
 // Right after ctx, colored like the 5h/wk rates: % on the ctx scale, MB in cyan.
 // Its names are block-scoped, so none can clash with the wrapper's own.
-const placeBlock = (url) =>
+const placeBlock = (url, eol = "\n") =>
   [
     "  " + OPEN,
     "  // payload-mon: estimated API request payload against the 32MB request limit, shown",
@@ -110,12 +138,19 @@ const placeBlock = (url) =>
     "  }",
     "  " + CLOSE,
     "",
-  ].join("\n");
+  ].join(eol);
 
-const insertBlock = (base, url) => base.replace(CTX_LINE, (line) => line + placeBlock(url));
+const insertBlock = (base, url) => base.replace(CTX_LINE, (line) => line + placeBlock(url, eolOf(line)));
 
 const count = (text, needle) => text.split(needle).length - 1;
 
+// The text without its blocks, the pattern run only up to the last closing line (see CLOSE_LINE).
+function withoutBlocks(src) {
+  let end = -1;
+  for (const m of src.matchAll(CLOSE_LINE)) end = m.index + m[0].length;
+  return end < 0 ? src : src.slice(0, end).replace(BLOCKS, "") + src.slice(end);
+}
+
 // The wrapper's text, null when there is no such file. Any other read failure
 // (permissions, say) is not "missing" and propagates.
 const readText = (file) => {
@@ -137,18 +172,21 @@ const readBytes = (file) => {
 
 const refusal = (why, hudFile) => ({ ok: false, message: `${why}. 래퍼를 그대로 두었습니다: ${hudFile}` });
 
-// The block exactly as `on` writes it for this URL, once, right after the ctx line.
-function inPlace(src, url) {
-  if (count(src, OPEN) !== 1 || count(src, CLOSE) !== 1) return false;
+// The line ending ("\n" or "\r\n") of the block that sits, exactly as `on` writes it for this URL,
+// once, right after the ctx line; "" when it does not. Either ending counts as in place, so a block
+// whose line endings an editor rewrote is still on.
+function blockEol(src, url) {
+  if (count(src, OPEN) !== 1 || count(src, CLOSE) !== 1) return "";
   const ctx = CTX_LINE.exec(src);
-  return ctx !== null && src.startsWith(placeBlock(url), ctx.index + ctx[0].length);
+  if (ctx === null) return "";
+  return ["\n", "\r\n"].find((eol) => src.startsWith(placeBlock(url, eol), ctx.index + ctx[0].length)) ?? "";
 }
 
 // Why the block cannot go into this wrapper, or "" when it can. Markers that do
 // not pair up would let the block pattern swallow the code between them.
 function misfit(src) {
   if (count(src, OPEN) !== count(src, CLOSE)) return "payload-mon 표시(>>> / <<<)의 짝이 맞지 않습니다";
-  const base = src.replace(BLOCKS, "");
+  const base = withoutBlocks(src);
   if (!base.includes("omc-hud.mjs") || !base.includes("const colorRate")) return "OMC 커스텀 HUD 래퍼가 아닙니다";
   if (!INPUT_DECL.test(base)) return "삽입 위치를 찾지 못했습니다(statusline 입력을 담는 input 변수가 없음)";
   if (!CTX_LINE.test(base)) return "삽입 위치를 찾지 못했습니다(ctx를 넣는 줄이 없음)";
@@ -163,6 +201,16 @@ function copyState(o) {
   return source !== null && copy.equals(source) ? "current" : "stale";
 }
 
+// Whether the folder holding `file` is a link. The copy folder is this tool's, and a link there
+// would take the copy, or its removal, to wherever it points.
+function linkedFolder(file) {
+  try {
+    return lstatSync(dirname(file)).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
 // Replaces file through a fresh temp file ("wx") and a rename: a link planted at
 // either name is replaced rather than written through, and a write that fails
 // leaves the old file as it was.
@@ -171,24 +219,62 @@ function writeFresh(file, data, mode) {
   rmSync(tmp, { force: true });
   try {
     writeFileSync(tmp, data, { flag: "wx", mode });
+    const id = fileId(tmp);
     renameSync(tmp, file);
+    return id;
   } catch (e) {
     rmSync(tmp, { force: true });
     throw e;
   }
 }
 
+// A file's identity, exact: NTFS file IDs pass 2^53, where a Number loses the low bits.
+const fileId = (p) => {
+  const s = lstatSync(p, { bigint: true });
+  return `${s.dev}:${s.ino}`;
+};
+// The copy folder's identity, to tell afterwards whether it is still the folder that was written into.
+const folderStamp = (dir) => {
+  const s = lstatSync(dir, { bigint: true });
+  return `${s.dev}:${s.ino}:${s.isSymbolicLink()}`;
+};
+// After the write: the copy folder must still be the one stamped before, holding these bytes. Another program
+// may have swapped it (for a link, say), so the copy went wherever it led, or put it back after the write, so
+// the copy is not in it. Then the write is refused, and the copy is taken back from where the folder now leads
+// when the file there is the one written (`written`, from writeFresh) and still ours byte for byte: a copy that
+// was there before, or one another program wrote over, stays.
+// Node has no openat, so a copy that went elsewhere through a swap that was put back stays where it went, and
+// a swap after this check goes unseen.
+function checkFolder(copy, stamp, data, written) {
+  const dir = dirname(copy);
+  if (folderStamp(dir) === stamp && readBytes(copy)?.equals(data)) return;
+  try {
+    const landed = join(realpathSync(dir), basename(copy));
+    if (fileId(landed) === written && readFileSync(landed).equals(data)) rmSync(landed, { force: true });
+  } catch {
+    /* nothing there to take back */
+  }
+  throw new Error(`사본 폴더가 쓰는 동안 바뀌었습니다: ${dir}`);
+}
+
 // Brings the copy up to this version's module; true when it had to write. The
 // statusline imports it on every refresh, so no other account may change it
 // (reading it is harmless). When the write fails, a folder made here is taken
 // away again: mkdirSync names a folder only when it created it, and rmdir
 // leaves one that something else has meanwhile put a file in.
 function syncModule(o) {
-  if (copyState(o) === "current") return false;
   const copy = moduleCopy(o.hudFile);
+  if (linkedFolder(copy)) throw new Error(`사본 폴더가 링크입니다: ${dirname(copy)}`);
+  if (copyState(o) === "current") return false;
+  // Read first: a module that cannot be read leaves no folder behind.
+  const data = readFileSync(o.moduleSource);
   const made = mkdirSync(dirname(copy), { recursive: true, mode: 0o755 }) !== undefined;
   try {
-    writeFresh(copy, readFileSync(o.moduleSource), 0o644);
+    const stamp = folderStamp(dirname(copy));
+    // From the same lstat: a folder that became a link since the check above is refused before the write.
+    if (stamp.endsWith(":true")) throw new Error(`사본 폴더가 링크입니다: ${dirname(copy)}`);
+    const written = writeFresh(copy, data, 0o644);
+    checkFolder(copy, stamp, data, written);
   } catch (e) {
     if (made) {
       try {
@@ -202,12 +288,14 @@ function syncModule(o) {
   return true;
 }
 
-// The first lines of node's complaint about `text` as an ES module, "" if it parses.
+// The first lines of node's complaint about `text` as an ES module, "" if it parses. A leading BOM
+// is left out: node runs a wrapper that starts with one, but `node --check` rejects a BOM before a
+// shebang (Node 20, 24).
 function syntaxError(text) {
   const dir = mkdtempSync(join(tmpdir(), "payload-mon-"));
   try {
     const file = join(dir, "check.mjs");
-    writeFileSync(file, text);
+    writeFileSync(file, text.replace(/^\uFEFF/, ""));
     const r = spawnSync(process.execPath, ["--check", file], { encoding: "utf8" });
     return r.status === 0 ? "" : String(r.stderr || r.error).trim().split("\n").slice(0, 3).join(" | ");
   } finally {
@@ -257,7 +345,7 @@ const showsPL = (src) => src !== null && PL_SEGMENT.test(src);
 // Where the size shows, named only while it does: the block in place and a
 // module copy to import. "" otherwise, so status never promises a segment.
 function displayWhere(o, src) {
-  if (src === null || !inPlace(src, moduleUrl(o.hudFile)) || copyState(o) === "missing") return "";
+  if (src === null || blockEol(src, moduleUrl(o.hudFile)) === "" || copyState(o) === "missing") return "";
   return showsPL(src) ? "PL 칸에 늘 표시" : `${SHOW_FROM_BYTES / MB}MB부터 표시`;
 }
 
@@ -265,7 +353,8 @@ export function turnOn(opts = {}) {
   const o = { ...DEFAULTS, ...opts };
   const src = readText(o.hudFile);
   if (src === null) return { ok: false, message: `HUD 래퍼가 없습니다: ${o.hudFile}` };
-  if (inPlace(src, moduleUrl(o.hudFile))) {
+  // In place with the wrapper's own line ending; a block whose ending differs is written again.
+  if (blockEol(src, moduleUrl(o.hudFile)) === eolOf(src)) {
     try {
       const refreshed = syncModule(o);
       return { ok: true, message: (refreshed ? "모듈 사본을 이 버전으로 맞췄습니다." : "이미 켜져 있습니다 (변경 없음).") + notShownNote(o) };
@@ -278,43 +367,52 @@ export function turnOn(opts = {}) {
   const done = showsPL(src)
     ? "켰습니다. 다음 statusline 갱신부터 PL 칸에 요청 크기가 늘 표시됩니다."
     : "켰습니다. 다음 statusline 갱신부터 8MB 이상이면 ctx 옆에 payload가 표시됩니다.";
-  const after = insertBlock(src.replace(BLOCKS, ""), moduleUrl(o.hudFile));
+  const after = insertBlock(withoutBlocks(src), moduleUrl(o.hudFile));
   return commit(o.hudFile, src, after, done + notShownNote(o), () => syncModule(o));
 }
 
 function removeBlocks(o, src) {
   if (src === null) return { ok: true, message: `HUD 래퍼가 없어 끌 것이 없습니다: ${o.hudFile}` };
   if (count(src, OPEN) !== count(src, CLOSE)) return refusal("payload-mon 표시(>>> / <<<)의 짝이 맞지 않습니다", o.hudFile);
-  const out = src.replace(BLOCKS, "");
+  const out = withoutBlocks(src);
   if (out === src) return { ok: true, message: "이미 꺼져 있습니다 (래퍼 변경 없음)." };
   return commit(o.hudFile, src, out, "껐습니다. 다음 statusline 갱신부터 payload가 표시되지 않습니다.");
 }
 
 // What off leaves behind otherwise: the cache (when this account controls its
 // folder), and the module copy with its folder (only when nothing else is in
-// it). Neither failing undoes off.
+// it), also the one 0.20.1 left beside a linked wrapper, but nothing through a copy folder that is a link.
+// None failing undoes off.
+// Returns the copy folders it left alone because they are links.
 function removeLeftovers(o) {
-  const copy = moduleCopy(o.hudFile);
-  for (const remove of [() => clearCache(o.cacheDir), () => rmSync(copy, { force: true })]) {
+  const all = [...new Set([moduleCopy(o.hudFile), besideLink(o.hudFile)])];
+  const copies = all.filter((copy) => !linkedFolder(copy));
+  for (const remove of [() => clearCache(o.cacheDir), ...copies.map((copy) => () => rmSync(copy, { force: true }))]) {
     try {
       remove();
     } catch {
       /* stale numbers or an unused copy; off stands */
     }
   }
-  try {
-    rmdirSync(dirname(copy));
-  } catch {
-    /* absent, or holds something that is not ours */
+  for (const copy of copies) {
+    try {
+      rmdirSync(dirname(copy));
+    } catch {
+      /* absent, or holds something that is not ours */
+    }
   }
+  return all.filter((copy) => !copies.includes(copy)).map((copy) => dirname(copy));
 }
 
 export function turnOff(opts = {}) {
   const o = { ...DEFAULTS, ...opts };
   const res = removeBlocks(o, readText(o.hudFile));
-  if (res.ok) removeLeftovers(o);
-  return res;
+  if (!res.ok) return res;
+  // A copy kept in a linked folder still feeds wrapper v4's PL segment, so off says so.
+  const kept = removeLeftovers(o);
+  return kept.length ? { ...res, message: `${res.message} ${KEPT_NOTE}: ${kept.join(", ")}` } : res;
 }
+const KEPT_NOTE = "사본 폴더가 링크라 모듈 사본은 지우지 않았습니다(래퍼 v4 의 PL 칸이 계속 보일 수 있음)";
 
 // The estimate for the session that runs this, "" if unknown, ending with where
 // it shows when `where` names it:
@@ -346,8 +444,17 @@ function stateOf(src, o) {
   if (count(src, OPEN) + count(src, CLOSE) === 0) return "꺼짐";
   // on and off both refuse this, so pointing at on would be a dead end.
   if (count(src, OPEN) !== count(src, CLOSE)) return "표시(>>> / <<<)의 짝이 맞지 않습니다 (on·off 모두 거부: HUD 재설치 또는 남은 표시 줄 정리)";
-  if (!inPlace(src, moduleUrl(o.hudFile))) return "켜짐이 불완전하거나 오래됨 (on 으로 복구)";
-  return "켜짐" + COPY_NOTE[copyState(o)];
+  if (blockEol(src, moduleUrl(o.hudFile)) === "") return "켜짐이 불완전하거나 오래됨 (on 으로 복구)";
+  return "켜짐" + copyNote(o);
+}
+
+// What status adds about the module copy. In a copy folder that is a link, on refuses to write it, so
+// pointing at on would be a dead end.
+function copyNote(o) {
+  const state = copyState(o);
+  const copy = moduleCopy(o.hudFile);
+  if (state !== "current" && linkedFolder(copy)) return `, 단 사본 폴더가 링크라 모듈 사본을 쓰지 않음 (링크를 일반 폴더로 바꾼 뒤 on): ${dirname(copy)}`;
+  return COPY_NOTE[state];
 }
 
 // What status says about the wrapper. A wrapper it cannot read is reported, not

package/skills/payload-mon/scripts/payload-size.mjs

@@ -211,7 +211,10 @@ export function clearCache(dir = CACHE_DIR) {
 export function estimatePayloadBytes(transcriptPath, cacheDir = CACHE_DIR) {
   const fd = openSync(transcriptPath, "r");
   try {
-    const { size, ino } = fstatSync(fd);
+    // The file number as a string: NTFS file IDs pass 2^53, where a Number loses the low bits, and JSON has no BigInt.
+    const st = fstatSync(fd, { bigint: true });
+    const size = Number(st.size);
+    const ino = String(st.ino);
     const file = cacheFile(cacheDir, transcriptPath);
     const c = loadCache(file);
     // Resume only a cache of these rules, for this file, which has not shrunk since.

package/skills/pdf-vision-extract/SKILL.md

@@ -35,7 +35,7 @@ Target: **long edge = 2400 px** (just under cap, leaves headroom).
 
 ```bash
 ls -lh <pdf-path>
-python3 -c "import fitz; d=fitz.open('<pdf-path>'); print('pages=', d.page_count)"
+(cd ~ && python3 -c "import fitz; d=fitz.open('<absolute-pdf-path>'); print('pages=', d.page_count)")   # from home: -c, -m and a stdin script import from the current folder first
 ```
 
 ### 2. Choose output directory
@@ -49,7 +49,7 @@ Convention: place PNGs **next to** existing design assets, in a subfolder named
 PyMuPDF is the most reliable single-dependency path (no Poppler, no ImageMagick).
 
 ```bash
-python3 - <<'PY'
+(cd ~ && python3 - <<'PY'
 import fitz, os
 SRC = "<absolute-pdf-path>"
 OUT = "<absolute-output-dir>"
@@ -63,9 +63,12 @@ for i, page in enumerate(doc, start=1):
     pix.save(f"{OUT}/page-{i:03d}.png")
     print(f"[{i}/{doc.page_count}] page-{i:03d}.png {pix.width}x{pix.height}")
 PY
+)
 ```
 
-Install if missing: `python3 -m pip install --user pymupdf`
+Install if missing: `(cd ~ && python3 -m pip install --user pymupdf)`
+
+Offline (no network): do not install; look for the fallback tools of section 4 (`pdftoppm`, ImageMagick) instead and say "오프라인이라 설치하지 않음(필요한 것: pymupdf)". pip retries 5 times with a 15 s timeout by default before it fails.
 
 ### 4. Fallback toolchain
 
@@ -83,7 +86,7 @@ If Python/PyMuPDF unavailable:
 
 ```bash
 ls <OUT> | wc -l                # page count matches PDF
-python3 -c "from PIL import Image; im=Image.open('<OUT>/page-001.png'); print(im.size)"
+(cd ~ && python3 -c "from PIL import Image; im=Image.open('<absolute-output-dir>/page-001.png'); print(im.size)")
 ```
 
 Expect long edge ≈ 2400 px.
@@ -110,10 +113,12 @@ For multiple pages in one turn, batch multiple `Read` calls in parallel.
 For a hybrid pipeline (visual + searchable text), also extract markdown:
 
 ```bash
-python3 -m pip install --user pymupdf4llm
-python3 -c "import pymupdf4llm; print(pymupdf4llm.to_markdown('<pdf>'))" > <OUT>/text.md
+(cd ~ && python3 -m pip install --user pymupdf4llm)
+(cd ~ && python3 -c "import pymupdf4llm; print(pymupdf4llm.to_markdown('<absolute-pdf-path>'))") > <OUT>/text.md
 ```
 
+The install needs the network too; offline, leave the markdown companion out and say so.
+
 Then `grep` the `.md` for labels and cross-reference with the PNGs.
 
 ## Example invocation history