@kaydash9999/banker-plugins 0.16.1 → 0.16.2

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude Code skills + commands — QA, audit, docs, architecture, dependency setup, and wiki; the banker plugin marketplace.",
-    "version": "0.16.1"
+    "version": "0.16.2"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "banker",
-  "version": "0.16.1",
+  "version": "0.16.2",
   "description": "Claude Code plugin: QA/audit/docs/architecture skills + commands, a /banker:setup installer for OS dependencies (playwright, etc.), and wiki compaction.",
   "author": {
     "name": "smallOpenSource",

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.16.2] - 2026-10-11
+
+### Security
+- **3d-intro 가 프로젝트 폴더에 든 파일로 실행할 프로그램을 정하지 않는다.** 0.16.1 까지는 남이 만든 저장소에서 3d-intro-build 를 돌리면, 그 저장소가 커밋해 둔 파일이 실행될 수 있었다.\
+  프로젝트 키 파일(`.env.3d-intro.local`)의 `FFMPEG_PATH` 를 ffmpeg 로 실행했다. 이제 그 값은 읽지 않고 이름만 알린다. 독립 검증(`verify-intro.mjs`)은 프로젝트의 `node_modules/playwright` 를 먼저 불러왔다. 이제 `--playwright-from-project` 를 줄 때만 읽는다. Windows 에서는 `npm root -g` 를 프로젝트 폴더에서 돌려 그 폴더의 `npm.cmd` 가 먼저 실행될 수 있었다. 이제 홈 폴더에서 돌린다.
+- ffmpeg 는 셸의 `FFMPEG_PATH`, 홈 설정 파일 `~/.config/banker/3d-intro/settings.env`, 예전 판이 홈 키 파일에 남긴 값, `PATH` 의 절대 경로 항목, `ffmpeg-static` 순으로 찾는다. 경로는 절대 경로만 받고, `PATH` 의 `.` 같은 상대 항목은 건너뛴다. 설정 파일에는 키를 두지 않는다.
+- 키 파일에 줄바꿈이 든 값이나 변수 이름이 아닌 키를 쓰지 않는다. 0.16.1 까지는 콘솔 샘플의 여러 줄 값이 홈 키 파일에 `FFMPEG_PATH` 나 두 번째 endpoint 줄을 심을 수 있었다.
+- `3d-intro-setup` 의 `ffmpeg-static` 폴백은 프로젝트가 아니라 홈의 전용 폴더(`~/.config/banker/3d-intro/tools`)에 설치한다. 프로젝트의 `.npmrc` 와 스크립트가 끼어들지 않는다. 새로 만드는 설정 폴더는 0700 이다.
+
+### Notes
+- 예전 판이 프로젝트 키 파일에만 ffmpeg 경로를 남겼고 `PATH` 에 ffmpeg 가 없다면, 3d-intro-build 가 "ffmpeg not found" 로 멈춘다. 셸에서 `export FFMPEG_PATH=<절대 경로>` 한 뒤 `3d-intro-setup` §2 를 한 번 다시 돌리면 홈 설정 파일에 남는다.
+- 프로젝트에만 playwright 를 설치했다면 독립 검증에 `--playwright-from-project` 를 준다.
+
 ## [0.16.1] - 2026-10-11
 
 ### Security

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaydash9999/banker-plugins",
-  "version": "0.16.1",
+  "version": "0.16.2",
   "description": "banker — Claude Code + Codex CLI plugin (QA, audit, docs, architecture, wiki skills). Install via Claude Code marketplace, or `npm i -g @kaydash9999/banker-plugins` then `banker setup`.",
   "bin": {
     "banker": "bin/banker.js"

package/skills/3d-intro-build/SKILL.md

@@ -50,11 +50,12 @@ description: "스크롤 위치에 맞춰 3D 플라이스루 영상이 움직이
 ```js
 import { resolveCreds, resolveFfmpeg } from './references/azure-adapter.mjs';
 const creds = resolveCreds({ projectDir });     // _source === null 이면 미설정
-// setup 이 ffmpeg 경로를 creds 에 FFMPEG_PATH 로 영속했으면 이 프로세스 env 에 적용(다른 세션/no-PATH 대비)
-if (creds.FFMPEG_PATH && !process.env.FFMPEG_PATH) process.env.FFMPEG_PATH = creds.FFMPEG_PATH;
+// ffmpeg 경로는 resolveFfmpeg 가 셸의 FFMPEG_PATH 와 홈의 설정 파일, 키 파일에서만 찾는다. 프로젝트 키 파일의 값은 쓰지 않는다.
+if (creds._ignored) console.log('프로젝트 키 파일에서 쓰지 않는 값:', Object.keys(creds._ignored).join(', '));   // 값은 출력하지 않는다
 ```
 
 - `creds._source` 가 `null` 이면 크리덴셜이 없다. `3d-intro-setup` 으로 보낸다.
+- `creds._ignored` 가 있으면 프로젝트 키 파일의 `FFMPEG_PATH` 를 쓰지 않은 것이다. 저장소와 함께 온 파일이 실행할 프로그램을 정하지 못하게 막은 것이다. 값은 출력하지 않으니 사람이 파일을 열어 확인하고, 그 경로가 필요하면 `3d-intro-setup` §2 로 홈 설정 파일에 남긴다.
   Claude Code: `/banker:setup` 에서 3d-intro-setup / Codex: `banker-3d-intro-setup`.
 - `resolveFfmpeg()` 가 throw 하면 ffmpeg 가 없다. 같은 `3d-intro-setup` 으로 보낸다.
 - 둘 다 통과해야 다음 단계로 간다.
@@ -64,7 +65,7 @@ if (creds.FFMPEG_PATH && !process.env.FFMPEG_PATH) process.env.FFMPEG_PATH = cre
   `malformed` 는 endpoint 가 https URL 이 아니거나(http 는 이 기기의 localhost 만 허용) 모델이 한 id 가 아닌 항목이다(`reason` 이 `endpoint` 또는 `model`). 영상 단계는 이 항목을 건너뛰고, 모두 `malformed` 면 영상 단계에서 멈춘다. 그러니 유료 스틸을 만들기 전에 사용자에게 알리고 `3d-intro-setup` 으로 고친다.
   Azure 호출도 같다. 키는 https 로만 보내고, `http://` endpoint 는 보내기 전에 막는다(Sora 영상 단계는 `invalid_request`, 이미지 생성 같은 그 밖의 호출은 `HTTP 0 (EINSECURE)` 오류).
   WAN 항목(`WAN_<n>_ENDPOINT`, `WAN_<n>_API_KEY`)이 하나도 없으면 영상은 처음부터 Sora 로 만든다. 이때 정지와 비행 모드(Step 4B)는 쓸 수 없다.
-- 독립 검증(Step 6)에는 Node 용 playwright 패키지와 Chromium 이 필요하다. `npx playwright install chromium`(`setup-playwright`)은 브라우저만 받으므로, 패키지도 `npm i -g playwright` 나 프로젝트의 `npm i -D playwright` 로 설치해 둔다.
+- 독립 검증(Step 6)에는 Node 용 playwright 패키지와 Chromium 이 필요하다. `npx playwright install chromium`(`setup-playwright`)은 브라우저만 받으므로, 패키지도 `npm i -g playwright` 로 설치해 둔다. 사용자가 자기 프로젝트에 `npm i -D playwright` 로 설치했다고 확인해 준 때만 Step 6 에 `--playwright-from-project` 를 준다. 프로젝트에 `node_modules/playwright` 가 있다는 이유만으로는 주지 않는다. 이 옵션이 없으면 프로젝트의 `node_modules` 는 읽지 않는다(저장소가 함께 가져온 코드가 실행되지 않게).
 
 ---
 

package/skills/3d-intro-build/references/azure-adapter.mjs

@@ -82,7 +82,7 @@ export function parseConsoleSample(text) {
   const out = { endpoint: null, deployment: null, apiKey: null, apiVersion: null };
 
   // endpoint: an explicit kwarg (python/JS SDK) wins; else the origin of the first URL (curl).
-  let m = s.match(/(?:azure_endpoint|azure_openai_endpoint|base_url|endpoint)\s*[=:]\s*["']([^"']+)["']/i);
+  let m = s.match(/(?:azure_endpoint|azure_openai_endpoint|base_url|endpoint)\s*[=:]\s*["']([^"'\r\n]+)["']/i);
   if (m) out.endpoint = originOf(m[1]);
   else { m = s.match(/https?:\/\/[^\s"'`)]+/); if (m) out.endpoint = originOf(m[0]); }
 
@@ -94,7 +94,7 @@ export function parseConsoleSample(text) {
   m = s.match(/\/deployments\/([^/?"'\s]+)/i);
   if (m) out.deployment = decodeURIComponent(m[1]);
   else {
-    m = s.match(/(?:azure_deployment|deployment_name|deployment|model)\s*[=:]\s*["']([^"']+)["']/i);
+    m = s.match(/(?:azure_deployment|deployment_name|deployment|model)\s*[=:]\s*["']([^"'\r\n]+)["']/i);
     if (m) out.deployment = m[1];
   }
 
@@ -134,38 +134,80 @@ function envValue(raw) {
   return raw.trimEnd().replace(/\s+#.*$/, '').trim().replace(/^["']|["']$/g, '');
 }
 
+/** The home key file, `~/.config/banker/3d-intro/env`: the keys when no project key file is used. */
+export function homeCredsPath() {
+  return path.join(os.homedir(), '.config', 'banker', '3d-intro', 'env');
+}
+
+/**
+ * This machine's settings file, `~/.config/banker/3d-intro/settings.env` (FFMPEG_PATH). It holds no
+ * key, so it can exist without making the home key file look set up.
+ */
+export function homeSettingsPath() {
+  return path.join(os.homedir(), '.config', 'banker', '3d-intro', 'settings.env');
+}
+
+/** The settings file as a KEY=VALUE map; {} when it is missing or cannot be read. */
+export function readSettings() {
+  return readEnvQuietly(homeSettingsPath);
+}
+
+// A KEY=VALUE file named by fileOf(); {} when there is none or it cannot be read (no home folder, no
+// permission, a folder in its place).
+function readEnvQuietly(fileOf) {
+  try { return parseEnvFile(fs.readFileSync(fileOf(), 'utf8')); } catch { return {}; }
+}
+
+// Settings that name a program to run. Only the shell or this machine's own files set them (the
+// settings file, or the home key file from an earlier setup): a project's .env.3d-intro.local can come
+// with a repository, and must not choose what runs on this machine.
+const MACHINE_ONLY = ['FFMPEG_PATH'];
+
 /**
  * Load creds from `.env.3d-intro.local` in projectDir, else `~/.config/banker/3d-intro/env`.
- * Returns the parsed KEY=VALUE map plus `_source` (the file used, or null if none found).
+ * Returns the parsed KEY=VALUE map plus `_source` (the file used, or null if none found). From a
+ * project file, FFMPEG_PATH is left out and returned under `_ignored` so the caller can say why.
  */
 export function resolveCreds({ projectDir } = {}) {
+  const home = homeCredsPath();
   const candidates = [];
   if (projectDir) candidates.push(path.join(projectDir, '.env.3d-intro.local'));
-  candidates.push(path.join(os.homedir(), '.config', 'banker', '3d-intro', 'env'));
-  for (const p of candidates) {
-    if (fs.existsSync(p)) return { ...parseEnvFile(fs.readFileSync(p, 'utf8')), _source: p };
-  }
-  return { _source: null };
+  candidates.push(home);
+  const p = candidates.find((c) => fs.existsSync(c));
+  if (!p) return { _source: null };
+  const creds = { ...parseEnvFile(fs.readFileSync(p, 'utf8')), _source: p };
+  return p === home ? creds : withoutMachineOnly(creds);
+}
+
+function withoutMachineOnly(creds) {
+  const ignored = Object.fromEntries(MACHINE_ONLY.filter((k) => creds[k] != null).map((k) => [k, creds[k]]));
+  for (const k of MACHINE_ONLY) delete creds[k];
+  return Object.keys(ignored).length ? { ...creds, _ignored: ignored } : creds;
 }
 
 /**
  * Persist creds to a KEY=VALUE env file, chmod 0600 where supported. Keys starting with `_`
- * and null/undefined values are skipped. Returns the written path.
+ * and null/undefined values are skipped. Returns the written path. A name that is not a variable
+ * name, or a value with a line break, throws before anything is written: either would add lines of
+ * its own (a FFMPEG_PATH, a second endpoint) to the file.
  */
 export function persistCreds(creds, { target } = {}) {
   if (!target) throw new Error('persistCreds: target path required');
-  const lines = [];
-  for (const [k, v] of Object.entries(creds || {})) {
-    if (k.startsWith('_') || v == null) continue;
-    lines.push(`${k}=${envLiteral(String(v))}`);
-  }
+  const lines = Object.entries(creds || {}).filter(([k, v]) => !k.startsWith('_') && v != null).map(([k, v]) => envLine(k, String(v)));
   const body = lines.length ? `${lines.join('\n')}\n` : '';
-  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
   fs.writeFileSync(target, body, { mode: 0o600 });
   try { fs.chmodSync(target, 0o600); } catch { /* chmod unsupported (e.g. Windows) — best effort */ }
   return target;
 }
 
+// One KEY=VALUE line for persistCreds, refusing a name or value that would make lines of its own.
+function envLine(k, v) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(k)) throw new Error(`persistCreds: ${JSON.stringify(k)} is not a variable name; nothing was written`);
+  if (/[\r\n]/.test(v)) throw new Error(`persistCreds: ${k} contains a line break; nothing was written`);
+  return `${k}=${envLiteral(v)}`;
+}
+
 // Quote a value that parseEnvFile would otherwise cut at " #", trim, or strip of its quotes.
 function envLiteral(v) {
   if (!/\s#|^["'\s]|["'\s]$/.test(v)) return v;
@@ -497,30 +539,43 @@ export async function createVideoTwoImage({
 
 /**
  * Locate an ffmpeg binary without ever invoking a shell:
- *   1) $FFMPEG_PATH (if it exists)
- *   2) scan $PATH entries (split on path.delimiter) for ffmpeg / ffmpeg.exe
+ *   1) $FFMPEG_PATH from the shell, else FFMPEG_PATH in the settings file, else one an earlier setup
+ *      left in the home key file; absolute paths only
+ *   2) the absolute $PATH entries (split on path.delimiter), for ffmpeg / ffmpeg.exe
  *   3) the optional ffmpeg-static package (dynamic import — may be absent)
+ * A project's .env.3d-intro.local never names the program, and "." or another relative PATH entry is
+ * skipped: either would let the files of a project, a cloned repository say, choose what runs.
  * Throws an actionable error if none is found.
  */
 export async function resolveFfmpeg() {
-  const fromEnv = process.env.FFMPEG_PATH;
-  if (fromEnv && fs.existsSync(fromEnv)) return fromEnv;
+  const found = namedFfmpeg() || ffmpegOnPath() || await staticFfmpeg();
+  if (!found) throw new Error('ffmpeg not found; run motion-graphic-setup or 3d-intro-setup');
+  return found;
+}
 
+// The ffmpeg this machine names. Absolute only: a relative value would be looked up in the current
+// folder, the project. The files are read only when the shell names nothing usable.
+function namedFfmpeg() {
+  const usable = (p) => !!p && path.isAbsolute(p) && fs.existsSync(p);
+  if (usable(process.env.FFMPEG_PATH)) return process.env.FFMPEG_PATH;
+  return [readSettings(), readEnvQuietly(homeCredsPath)].map((s) => s.FFMPEG_PATH).find(usable) || null;
+}
+
+function ffmpegOnPath() {
   const names = process.platform === 'win32' ? ['ffmpeg.exe', 'ffmpeg'] : ['ffmpeg'];
-  for (const dir of (process.env.PATH || '').split(path.delimiter).filter(Boolean)) {
-    for (const name of names) {
-      const candidate = path.join(dir, name);
-      if (fs.existsSync(candidate)) return candidate;
-    }
+  for (const dir of (process.env.PATH || '').split(path.delimiter).filter((d) => path.isAbsolute(d))) {
+    const hit = names.map((name) => path.join(dir, name)).find((c) => fs.existsSync(c));
+    if (hit) return hit;
   }
+  return null;
+}
 
+async function staticFfmpeg() {
   try {
     const mod = await import('ffmpeg-static');
     const p = mod?.default || mod;
-    if (typeof p === 'string' && fs.existsSync(p)) return p;
-  } catch { /* ffmpeg-static not installed — fall through to the error */ }
-
-  throw new Error('ffmpeg not found; run motion-graphic-setup or 3d-intro-setup');
+    return typeof p === 'string' && fs.existsSync(p) ? p : null;
+  } catch { return null; /* ffmpeg-static not installed */ }
 }
 
 // Run ffmpeg with an ARGUMENT ARRAY (never a shell string). Returns {code, stdout, stderr, args}.

package/skills/3d-intro-build/references/verify-intro.mjs

@@ -15,17 +15,19 @@
  *
  * Usage:
  *   node verify-intro.mjs <url> [--out report.json] [--header <selector>] [--min-contrast 4.5]
- *        [--viewports 1280x800,390x844t] [--no-input] [--no-contrast]
+ *        [--viewports 1280x800,390x844t] [--no-input] [--no-contrast] [--playwright-from-project]
  *     --viewports  a trailing t marks a touch screen, r reduced motion (default: the six below)
  *     --header     the site's fixed header (default: the engine's .sw-topbar)
+ *     --playwright-from-project  also look in the current folder's node_modules, first (your own project only)
  *   Exit 0 when nothing failed, 1 otherwise; the report (JSON) goes to --out or stdout.
  *
  * Needs Playwright with Chromium (setup-playwright skill: npx playwright install chromium), found
- * from this folder or from the global npm root.
+ * beside this script or in the global npm root, and in the project only when asked.
  */
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import { createRequire } from 'node:module';
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
@@ -128,21 +130,31 @@ function resolveFrom(base) {
   try { return createRequire(path.join(base, 'noop.js')).resolve('playwright'); } catch { return null; }
 }
 
+// npm's global root. npm runs from the home folder: run from the project, cmd.exe on Windows would
+// take an npm.cmd from that folder first, and a relative PATH entry would do the same anywhere.
+function globalRoot() {
+  const win = process.platform === 'win32';
+  const r = spawnSync(win ? 'npm.cmd' : 'npm', ['root', '-g'], { encoding: 'utf8', shell: win, cwd: os.homedir() });
+  return String(r.stdout || '').trim();
+}
+
 /**
- * The playwright package: beside this script, in the project (the current folder), or in the global
- * npm root. `npx playwright install chromium` alone fetches the browser, not this package.
+ * The playwright package: beside this script, else in the global npm root. The project's own
+ * node_modules (the current folder) is read only with `fromProject` (--playwright-from-project), and
+ * then first: a repository can ship a node_modules of its own, and loading it runs its code.
+ * `npx playwright install chromium` alone fetches the browser, not this package.
  */
-export async function loadPlaywright() {
+export async function loadPlaywright({ fromProject = false } = {}) {
   try { return await import('playwright'); } catch { /* not beside this script */ }
-  const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-  const globalRoot = String(spawnSync(npm, ['root', '-g'], { encoding: 'utf8', shell: process.platform === 'win32' }).stdout || '').trim();
-  const entry = resolveFrom(process.cwd()) || (globalRoot && resolveFrom(globalRoot));
+  const fromHere = fromProject ? resolveFrom(process.cwd()) : null;
+  const root = fromHere ? null : globalRoot();
+  const entry = fromHere || (root && resolveFrom(root));
   if (entry) {
     const mod = await import(pathToFileURL(entry).href);
     return mod.chromium ? mod : mod.default;
   }
   throw new Error('verify-intro: the playwright package was not found. Install it and its browser: '
-    + '`npm i -g playwright && npx playwright install chromium` (or `npm i -D playwright` in the project).');
+    + '`npm i -g playwright && npx playwright install chromium`, or for your own project `npm i -D playwright` and --playwright-from-project.');
 }
 
 const navInfo = (page) => page.evaluate(() => {
@@ -419,8 +431,8 @@ async function measureViewport(browser, url, vp, o) {
 }
 
 /** Measures `url` at every viewport. Resolves to { url, viewports: [...], failures }. */
-export async function verifyIntro(url, { viewports = VIEWPORTS, header = '.sw-topbar', minContrast = 4.5, input = true, contrast = true } = {}) {
-  const { chromium } = await loadPlaywright();
+export async function verifyIntro(url, { viewports = VIEWPORTS, header = '.sw-topbar', minContrast = 4.5, input = true, contrast = true, playwrightFromProject = false } = {}) {
+  const { chromium } = await loadPlaywright({ fromProject: playwrightFromProject });
   const browser = await chromium.launch();
   try {
     const results = [];
@@ -439,11 +451,11 @@ export function parseViewport(v) {
 }
 
 const FLAGS = { '--out': 'out', '--header': 'header', '--min-contrast': 'minContrast', '--viewports': 'viewports' };
-const SWITCHES = { '--no-input': ['input', false], '--no-contrast': ['contrast', false] };
+const SWITCHES = { '--no-input': ['input', false], '--no-contrast': ['contrast', false], '--playwright-from-project': ['playwrightFromProject', true] };
 
-/** The command line: a URL, --flag value or --flag=value, and the two switches. */
+/** The command line: a URL, --flag value or --flag=value, and the switches. */
 export function parseArgs(argv) {
-  const o = { url: null, out: null, header: '.sw-topbar', minContrast: 4.5, viewports: VIEWPORTS, input: true, contrast: true };
+  const o = { url: null, out: null, header: '.sw-topbar', minContrast: 4.5, viewports: VIEWPORTS, input: true, contrast: true, playwrightFromProject: false };
   for (let i = 0; i < argv.length; i++) {
     const [flag, inline] = argv[i].includes('=') ? [argv[i].slice(0, argv[i].indexOf('=')), argv[i].slice(argv[i].indexOf('=') + 1)] : [argv[i], null];
     if (SWITCHES[flag]) o[SWITCHES[flag][0]] = SWITCHES[flag][1];
@@ -461,7 +473,7 @@ if (invokedDirectly) {
   let o;
   try { o = parseArgs(process.argv.slice(2)); } catch (e) { console.error(e.message); process.exit(2); }
   if (!o.url) {
-    console.error('usage: node verify-intro.mjs <url> [--out report.json] [--header <selector>] [--min-contrast 4.5] [--viewports 1280x800,390x844t] [--no-input] [--no-contrast]');
+    console.error('usage: node verify-intro.mjs <url> [--out report.json] [--header <selector>] [--min-contrast 4.5] [--viewports 1280x800,390x844t] [--no-input] [--no-contrast] [--playwright-from-project]');
     process.exit(2);
   }
   verifyIntro(o.url, o).then((r) => {

package/skills/3d-intro-build/references/verify.md

@@ -4,7 +4,7 @@
 
 ## 1. 측정 (verify-intro.mjs)
 
-Node 용 playwright 패키지와 Chromium 이 필요하다(`npm i -g playwright && npx playwright install chromium`, 또는 프로젝트에 `npm i -D playwright`).
+Node 용 playwright 패키지와 Chromium 이 필요하다(`npm i -g playwright && npx playwright install chromium`). 사람이 자기 프로젝트에 `npm i -D playwright` 로 설치했다고 확인한 때만 `--playwright-from-project` 를 준다(폴더에 있다는 이유만으로는 주지 않는다). 이 옵션이 없으면 프로젝트의 `node_modules` 는 읽지 않는다.
 
 ```bash
 node references/verify-intro.mjs http://localhost:<port>/ --out verify.json

package/skills/3d-intro-setup/SKILL.md

@@ -43,28 +43,33 @@ OS별 상세 설치 절차(Ubuntu NodeSource·RHEL8/Rocky8 dnf 모듈·Windows w
 
 ## 2. ffmpeg 확보
 어댑터의 프레임 추출·컬러 매치·크로스페이드·이어붙이기(`extractLastFrame`·`colorMatch`·`crossfade`·`concatClips`, forward-chaining 이음새 처리)가 `ffmpeg` 바이너리를 요구한다.
-설치 절차는 `motion-graphic-setup` §2 와 완전히 동일하므로 반복하지 않고 요약만 남긴다(전체 함정·오프라인 폴백은 그 스킬 참조):
+설치 절차는 `motion-graphic-setup` §2 와 같으므로 반복하지 않고 요약만 남긴다(전체 함정은 그 스킬 참조. 마지막 폴백의 설치 위치만 다르다):
 - macOS: `brew install ffmpeg`
 - Ubuntu/Debian: `sudo apt-get install -y ffmpeg`
 - RHEL8/Rocky8: BaseOS/AppStream 미포함(라이선스) → RPM Fusion 후 `dnf install -y ffmpeg`
 - Windows: `winget install --id Gyan.FFmpeg -e`
-- 전부 막히면(권한/오프라인) project-local 폴백: `npm install --no-save ffmpeg-static`
+- 전부 막히면(권한/오프라인) 홈 폴더의 전용 폴더에 `ffmpeg-static` 을 받는다. 프로젝트 안에서 npm 을 돌리면 그 프로젝트의 `.npmrc` 와 스크립트가 끼어든다:
+  `(cd ~ && npm install --prefix ~/.config/banker/3d-intro/tools ffmpeg-static)` 후 `export FFMPEG_PATH="$(cd ~ && node -p "require(require('path').resolve('.config/banker/3d-intro/tools/node_modules/ffmpeg-static'))")"`
 
-**★ banker 플러그인 자체(스킬 파일·npm 패키지 배포물)에는 ffmpeg 바이너리를 절대 번들하지 않는다** — 위 설치는 전부 사용자 프로젝트/시스템에만 적용된다(motion-graphic-setup과 동일 원칙).
+**★ banker 플러그인 자체(스킬 파일·npm 패키지 배포물)에는 ffmpeg 바이너리를 절대 번들하지 않는다** — 위 설치는 전부 사용자 시스템(홈 폴더 포함)에만 적용된다(motion-graphic-setup과 동일 원칙).
 
-검증은 `ffmpeg -version` 대신 **어댑터가 실제 쓰는 해석 로직**(`resolveFfmpeg`: `$FFMPEG_PATH` → `PATH` 스캔 → `ffmpeg-static` 순)으로 한다 — 이게 통과해야 3d-intro-build 가 실제로 ffmpeg 를 찾는다.
-`FFMPEG_PATH`(export)는 셸 세션 한정이라, 해석된 경로를 **크레덴셜 env 파일에 `FFMPEG_PATH=` 로 영속**해 둔다 — 그래야 다른 세션/프로세스에서 도는 3d-intro-build 도 (`resolveCreds` 로 읽어) ffmpeg 를 찾는다. 시스템 `ffmpeg` 가 `PATH` 에 있으면 이 영속은 불필요하다(그래도 무해).
+검증은 `ffmpeg -version` 대신 **어댑터가 실제 쓰는 해석 로직**(`resolveFfmpeg`: 셸의 `$FFMPEG_PATH` → 홈 설정 파일 `~/.config/banker/3d-intro/settings.env` 의 `FFMPEG_PATH` → 예전 판이 홈 키 파일 `env` 에 남긴 `FFMPEG_PATH` → `PATH` 의 절대 경로 항목 → `ffmpeg-static` 순. 경로는 모두 절대 경로만)으로 한다 — 이게 통과해야 3d-intro-build 가 실제로 ffmpeg 를 찾는다.
+셸의 `FFMPEG_PATH`(export, 절대 경로만 받는다)로만 찾았으면 셸 세션 한정이라, 그 경로를 **홈 설정 파일 `settings.env` 에 `FFMPEG_PATH=` 로 영속**해 다른 세션의 3d-intro-build 도 찾게 한다. 시스템 `ffmpeg` 가 `PATH` 에 있으면 영속은 필요 없다. 이 파일에는 키를 두지 않아, 키 파일을 어디에 만들지 정하는 §3 에 영향을 주지 않는다.
+실행할 프로그램의 경로는 프로젝트 키 파일(`.env.3d-intro.local`)에 두지 않고, 거기 적힌 값은 읽지 않는다. 그 파일은 저장소와 함께 올 수 있어, 남이 만든 저장소가 이 기기에서 실행할 프로그램을 정하게 되기 때문이다.
 ```bash
 node -e "
 (async () => {
-  const { resolveFfmpeg, resolveCreds, persistCreds } = await import('$ADAPTER');
+  const { resolveFfmpeg, resolveCreds, persistCreds, readSettings, homeSettingsPath } = await import('$ADAPTER');
+  const proj = resolveCreds({ projectDir: process.cwd() });
+  if (proj._ignored) console.log('프로젝트 키 파일에서 쓰지 않는 값:', Object.keys(proj._ignored).join(', '));   // 값은 출력하지 않는다
   const ff = await resolveFfmpeg().catch((e) => { console.log('ffmpeg 미확보:', e.message); process.exit(1); });
   console.log('ffmpeg 확보:', ff);
-  const c = resolveCreds({ projectDir: process.cwd() });
-  if (c._source && c.FFMPEG_PATH !== ff) { c.FFMPEG_PATH = ff; persistCreds(c, { target: c._source }); console.log('FFMPEG_PATH 영속 ->', c._source); }
+  const s = readSettings();   // 홈 설정 파일(키는 두지 않음)
+  if (ff === process.env.FFMPEG_PATH && s.FFMPEG_PATH !== ff) { persistCreds({ ...s, FFMPEG_PATH: ff }, { target: homeSettingsPath() }); console.log('FFMPEG_PATH 영속 ->', homeSettingsPath()); }
 })();
 "
 ```
+`프로젝트 키 파일에서 쓰지 않는 값` 이 보이면 예전 판이 그 파일에 남긴 ffmpeg 경로다. 값은 출력하지 않으니 사람이 파일을 열어 그 경로가 맞는지 확인하고, 맞으면 셸에서 `export FFMPEG_PATH=<그 경로>` 한 뒤 이 명령을 다시 돌려 홈 설정 파일에 남긴다.
 
 ## 3. 크레덴셜 입력
 **★시크릿(API key)은 사용자만 입력 — 채팅 로그·커밋·리포트에 원문 노출 금지, 항상 `redact()` 결과만 표기한다.**

package/skills/3d-intro-setup/references/azure-adapter.mjs

@@ -82,7 +82,7 @@ export function parseConsoleSample(text) {
   const out = { endpoint: null, deployment: null, apiKey: null, apiVersion: null };
 
   // endpoint: an explicit kwarg (python/JS SDK) wins; else the origin of the first URL (curl).
-  let m = s.match(/(?:azure_endpoint|azure_openai_endpoint|base_url|endpoint)\s*[=:]\s*["']([^"']+)["']/i);
+  let m = s.match(/(?:azure_endpoint|azure_openai_endpoint|base_url|endpoint)\s*[=:]\s*["']([^"'\r\n]+)["']/i);
   if (m) out.endpoint = originOf(m[1]);
   else { m = s.match(/https?:\/\/[^\s"'`)]+/); if (m) out.endpoint = originOf(m[0]); }
 
@@ -94,7 +94,7 @@ export function parseConsoleSample(text) {
   m = s.match(/\/deployments\/([^/?"'\s]+)/i);
   if (m) out.deployment = decodeURIComponent(m[1]);
   else {
-    m = s.match(/(?:azure_deployment|deployment_name|deployment|model)\s*[=:]\s*["']([^"']+)["']/i);
+    m = s.match(/(?:azure_deployment|deployment_name|deployment|model)\s*[=:]\s*["']([^"'\r\n]+)["']/i);
     if (m) out.deployment = m[1];
   }
 
@@ -134,38 +134,80 @@ function envValue(raw) {
   return raw.trimEnd().replace(/\s+#.*$/, '').trim().replace(/^["']|["']$/g, '');
 }
 
+/** The home key file, `~/.config/banker/3d-intro/env`: the keys when no project key file is used. */
+export function homeCredsPath() {
+  return path.join(os.homedir(), '.config', 'banker', '3d-intro', 'env');
+}
+
+/**
+ * This machine's settings file, `~/.config/banker/3d-intro/settings.env` (FFMPEG_PATH). It holds no
+ * key, so it can exist without making the home key file look set up.
+ */
+export function homeSettingsPath() {
+  return path.join(os.homedir(), '.config', 'banker', '3d-intro', 'settings.env');
+}
+
+/** The settings file as a KEY=VALUE map; {} when it is missing or cannot be read. */
+export function readSettings() {
+  return readEnvQuietly(homeSettingsPath);
+}
+
+// A KEY=VALUE file named by fileOf(); {} when there is none or it cannot be read (no home folder, no
+// permission, a folder in its place).
+function readEnvQuietly(fileOf) {
+  try { return parseEnvFile(fs.readFileSync(fileOf(), 'utf8')); } catch { return {}; }
+}
+
+// Settings that name a program to run. Only the shell or this machine's own files set them (the
+// settings file, or the home key file from an earlier setup): a project's .env.3d-intro.local can come
+// with a repository, and must not choose what runs on this machine.
+const MACHINE_ONLY = ['FFMPEG_PATH'];
+
 /**
  * Load creds from `.env.3d-intro.local` in projectDir, else `~/.config/banker/3d-intro/env`.
- * Returns the parsed KEY=VALUE map plus `_source` (the file used, or null if none found).
+ * Returns the parsed KEY=VALUE map plus `_source` (the file used, or null if none found). From a
+ * project file, FFMPEG_PATH is left out and returned under `_ignored` so the caller can say why.
  */
 export function resolveCreds({ projectDir } = {}) {
+  const home = homeCredsPath();
   const candidates = [];
   if (projectDir) candidates.push(path.join(projectDir, '.env.3d-intro.local'));
-  candidates.push(path.join(os.homedir(), '.config', 'banker', '3d-intro', 'env'));
-  for (const p of candidates) {
-    if (fs.existsSync(p)) return { ...parseEnvFile(fs.readFileSync(p, 'utf8')), _source: p };
-  }
-  return { _source: null };
+  candidates.push(home);
+  const p = candidates.find((c) => fs.existsSync(c));
+  if (!p) return { _source: null };
+  const creds = { ...parseEnvFile(fs.readFileSync(p, 'utf8')), _source: p };
+  return p === home ? creds : withoutMachineOnly(creds);
+}
+
+function withoutMachineOnly(creds) {
+  const ignored = Object.fromEntries(MACHINE_ONLY.filter((k) => creds[k] != null).map((k) => [k, creds[k]]));
+  for (const k of MACHINE_ONLY) delete creds[k];
+  return Object.keys(ignored).length ? { ...creds, _ignored: ignored } : creds;
 }
 
 /**
  * Persist creds to a KEY=VALUE env file, chmod 0600 where supported. Keys starting with `_`
- * and null/undefined values are skipped. Returns the written path.
+ * and null/undefined values are skipped. Returns the written path. A name that is not a variable
+ * name, or a value with a line break, throws before anything is written: either would add lines of
+ * its own (a FFMPEG_PATH, a second endpoint) to the file.
  */
 export function persistCreds(creds, { target } = {}) {
   if (!target) throw new Error('persistCreds: target path required');
-  const lines = [];
-  for (const [k, v] of Object.entries(creds || {})) {
-    if (k.startsWith('_') || v == null) continue;
-    lines.push(`${k}=${envLiteral(String(v))}`);
-  }
+  const lines = Object.entries(creds || {}).filter(([k, v]) => !k.startsWith('_') && v != null).map(([k, v]) => envLine(k, String(v)));
   const body = lines.length ? `${lines.join('\n')}\n` : '';
-  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
   fs.writeFileSync(target, body, { mode: 0o600 });
   try { fs.chmodSync(target, 0o600); } catch { /* chmod unsupported (e.g. Windows) — best effort */ }
   return target;
 }
 
+// One KEY=VALUE line for persistCreds, refusing a name or value that would make lines of its own.
+function envLine(k, v) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(k)) throw new Error(`persistCreds: ${JSON.stringify(k)} is not a variable name; nothing was written`);
+  if (/[\r\n]/.test(v)) throw new Error(`persistCreds: ${k} contains a line break; nothing was written`);
+  return `${k}=${envLiteral(v)}`;
+}
+
 // Quote a value that parseEnvFile would otherwise cut at " #", trim, or strip of its quotes.
 function envLiteral(v) {
   if (!/\s#|^["'\s]|["'\s]$/.test(v)) return v;
@@ -497,30 +539,43 @@ export async function createVideoTwoImage({
 
 /**
  * Locate an ffmpeg binary without ever invoking a shell:
- *   1) $FFMPEG_PATH (if it exists)
- *   2) scan $PATH entries (split on path.delimiter) for ffmpeg / ffmpeg.exe
+ *   1) $FFMPEG_PATH from the shell, else FFMPEG_PATH in the settings file, else one an earlier setup
+ *      left in the home key file; absolute paths only
+ *   2) the absolute $PATH entries (split on path.delimiter), for ffmpeg / ffmpeg.exe
  *   3) the optional ffmpeg-static package (dynamic import — may be absent)
+ * A project's .env.3d-intro.local never names the program, and "." or another relative PATH entry is
+ * skipped: either would let the files of a project, a cloned repository say, choose what runs.
  * Throws an actionable error if none is found.
  */
 export async function resolveFfmpeg() {
-  const fromEnv = process.env.FFMPEG_PATH;
-  if (fromEnv && fs.existsSync(fromEnv)) return fromEnv;
+  const found = namedFfmpeg() || ffmpegOnPath() || await staticFfmpeg();
+  if (!found) throw new Error('ffmpeg not found; run motion-graphic-setup or 3d-intro-setup');
+  return found;
+}
 
+// The ffmpeg this machine names. Absolute only: a relative value would be looked up in the current
+// folder, the project. The files are read only when the shell names nothing usable.
+function namedFfmpeg() {
+  const usable = (p) => !!p && path.isAbsolute(p) && fs.existsSync(p);
+  if (usable(process.env.FFMPEG_PATH)) return process.env.FFMPEG_PATH;
+  return [readSettings(), readEnvQuietly(homeCredsPath)].map((s) => s.FFMPEG_PATH).find(usable) || null;
+}
+
+function ffmpegOnPath() {
   const names = process.platform === 'win32' ? ['ffmpeg.exe', 'ffmpeg'] : ['ffmpeg'];
-  for (const dir of (process.env.PATH || '').split(path.delimiter).filter(Boolean)) {
-    for (const name of names) {
-      const candidate = path.join(dir, name);
-      if (fs.existsSync(candidate)) return candidate;
-    }
+  for (const dir of (process.env.PATH || '').split(path.delimiter).filter((d) => path.isAbsolute(d))) {
+    const hit = names.map((name) => path.join(dir, name)).find((c) => fs.existsSync(c));
+    if (hit) return hit;
   }
+  return null;
+}
 
+async function staticFfmpeg() {
   try {
     const mod = await import('ffmpeg-static');
     const p = mod?.default || mod;
-    if (typeof p === 'string' && fs.existsSync(p)) return p;
-  } catch { /* ffmpeg-static not installed — fall through to the error */ }
-
-  throw new Error('ffmpeg not found; run motion-graphic-setup or 3d-intro-setup');
+    return typeof p === 'string' && fs.existsSync(p) ? p : null;
+  } catch { return null; /* ffmpeg-static not installed */ }
 }
 
 // Run ffmpeg with an ARGUMENT ARRAY (never a shell string). Returns {code, stdout, stderr, args}.