elanous 0.2.9 → 0.2.11

package/skills/explainer-video/SKILL.md

@@ -91,8 +91,12 @@ The reference is used only for its structure (header, chapter cards, a diagram t
 
 ```bash
 zsh $SKILL/engine/reel.sh <folder> --title "마케터의 밤" --sub "2026.10.02 · 서울"
+zsh $SKILL/engine/reel.sh --warm-cards --title "마케터의 밤" --sub "2026.10.02 · 서울"  # 행사 전 카드 미리 굽기
+zsh $SKILL/engine/reel.sh <folder> --title "마케터의 밤" --sub "2026.10.02 · 서울" --instant  # 사진 구간만 렌더
 ```
 
+즉석판 카드 캐시: `~/.cache/elanous-explainer/cards/<sha256(JSON 배열 [title, sub, 1080, 1920, 카드판번호]) 앞 16자>/{intro,end}.mp4` (`EXPLAINER_CACHE`로 루트 변경 가능).
+
 - **Input**: a folder of phone photos (jpg · png · heic) and short clips (mp4 · mov). The default upload folder is `~/.elanous/field/<event>/`.
 - **Order**: by capture time (`mdls` creation date), then by file name.
 - **Captions**: optional `<folder>/captions.txt`, one line per item as `파일명 | 자막`. A photo without a line gets one line from a vision model (`codex exec -i`, all photos in parallel, 30 s cap each); if that fails it shows «현장 N». `FIELD_REEL_VISION=0` turns the vision step off.

package/skills/explainer-video/engine/reel.mjs

@@ -12,15 +12,18 @@ import { join, dirname, resolve, extname, basename } from "node:path";
 import { homedir } from "node:os";
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { normalizeCardTitle } from "./stitch.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const argv = process.argv.slice(2);
 const opt = (k, d) => { const i = argv.indexOf(`--${k}`); return i >= 0 ? argv[i + 1] : d; };
 const folder = resolve(argv.find((a, i) => !a.startsWith("--") && !(i > 0 && argv[i - 1].startsWith("--"))) ?? ".");
 const PART = opt("part", "full");
+if (!["full", "body", "intro", "end"].includes(PART)) throw new Error(`unknown reel part: ${PART}`);
+const CARD = PART === "intro" || PART === "end";
 const MAX = Number(opt("max", 60)), MIN = Number(opt("min", 24));
 const W = 1080, H = 1920, PHOTO = 4.2, CLIP_MAX = 5, XF = 0.5;
-const INTRO = PART === "body" ? 0 : 3.0, END = PART === "body" ? 0 : 3.4;
+const INTRO = PART === "body" || PART === "end" ? 0 : 3.0, END = PART === "body" || PART === "intro" ? 0 : 3.4;
 const out = join(folder, "reel"), hf = join(out, "hf"), media = join(hf, "assets", "media");
 mkdirSync(media, { recursive: true }); mkdirSync(join(hf, "assets", "fonts"), { recursive: true });
 const T0 = Date.now(), lap = (s) => console.log(`reel: ${s} · ${((Date.now() - T0) / 1000).toFixed(1)}s`);
@@ -37,18 +40,19 @@ const created = (p) => {
   return Number.isFinite(t) ? t : statSync(p).mtimeMs;
 };
 const probeDur = (p) => Number(run("ffprobe", ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", p]).stdout.trim()) || 0;
-const caps = Object.fromEntries((existsSync(join(folder, "captions.txt")) ? readFileSync(join(folder, "captions.txt"), "utf8") : "")
+let TITLE = opt("title", ""), SUB = opt("sub", "");
+const caps = Object.fromEntries((!CARD && existsSync(join(folder, "captions.txt")) ? readFileSync(join(folder, "captions.txt"), "utf8") : "")
   .split("\n").filter((l) => l.includes("|")).map((l) => l.split("|").map((s) => s.trim())));
-let items = readdirSync(folder).filter((f) => [...IMG, ...VID].includes(extname(f).toLowerCase()))
+let items = CARD ? [] : readdirSync(folder).filter((f) => [...IMG, ...VID].includes(extname(f).toLowerCase()))
   .map((f) => ({ f, p: join(folder, f), video: VID.includes(extname(f).toLowerCase()), t: created(join(folder, f)) }))
   .sort((a, b) => a.t - b.t || a.f.localeCompare(b.f));
-if (!items.length) throw new Error(`no photos or clips in ${folder}`);
+if (!CARD && !items.length) throw new Error(`no photos or clips in ${folder}`);
 
 // ── durations: fit into [MIN, MAX] ─────────────────────────────────────────────
 for (const it of items) it.dur = it.video ? Math.min(CLIP_MAX, Math.max(1.5, probeDur(it.p))) : PHOTO;
 const body = () => items.reduce((a, it) => a + it.dur, 0);
 while (INTRO + body() + END > MAX && items.length > 1) items.splice(Math.floor(items.length / 2), 1); // drop from the middle, keep first & last
-if (PART !== "body" && INTRO + body() + END < MIN) { const photos = items.filter((i) => !i.video); const need = MIN - (INTRO + body() + END); for (const p of photos) p.dur += need / Math.max(1, photos.length); }
+if (PART === "full" && INTRO + body() + END < MIN) { const photos = items.filter((i) => !i.video); const need = MIN - (INTRO + body() + END); for (const p of photos) p.dur += need / Math.max(1, photos.length); }
 
 // ── media prep: HEIC → jpg · big photos down to 2160 · a small copy for the vision model · clips re-encoded short & muted ──
 let t = INTRO;
@@ -92,18 +96,17 @@ const oneLine = (s, max) => {
 const CAP_PROMPT = "행사 현장 사진이다. 세로 영상 자막으로 쓸 한국어 한 줄을 출력하라 — 18자 이내 · 마침표 없이 · 보이는 장면만 · 사람 이름·외모 묘사·추측 금지 · 화면 속 글자(행사명·회사명)는 읽히면 써도 된다. 그 한 줄만.";
 const HEAD_PROMPT = "같은 행사에서 찍은 사진들이다. 영상 첫 화면 제목으로 쓸 한국어 행사 이름 한 줄을 출력하라 — 16자 이내 · 화면 속 글자에서 읽히는 행사·회사 이름을 우선 · 읽히지 않으면 장면을 짧게(예: «상장 기념식 현장») · 추측 금지. 그 한 줄만.";
 const slugTitle = (s) => !s || /^[a-z0-9]+(?:-[a-z0-9]+)*$/i.test(s);
-let TITLE = opt("title", ""), SUB = opt("sub", "");
 const photos = items.filter((it) => !it.video);
 const VT0 = Date.now();
-const jobs = VISION ? [
+const jobs = VISION && !CARD ? [
   ...photos.filter((it) => !caps[it.f]).map(async (it) => { it.vcap = oneLine(await ask(CAP_PROMPT, [join(out, `v${items.indexOf(it)}.jpg`)]), 22); }),
   ...(PART !== "body" && slugTitle(TITLE) && photos.length ? [(async () => { TITLE = oneLine(await ask(HEAD_PROMPT, photos.slice(0, 3).map((it) => join(out, `v${items.indexOf(it)}.jpg`))), 20) || TITLE; })()] : []),
 ] : [];
 await Promise.all(jobs);
 const visionMs = Date.now() - VT0;
 items.forEach((it, i) => { it.cap = caps[it.f] || it.vcap || (it.video ? "" : `현장 ${i + 1}`); });
-if (slugTitle(TITLE)) TITLE = "현장 스케치";
-if (!SUB) { const d = new Date(items[0].t + 9 * 3600e3); SUB = `${d.getUTCFullYear()}.${String(d.getUTCMonth() + 1).padStart(2, "0")}.${String(d.getUTCDate()).padStart(2, "0")}`; }
+TITLE = normalizeCardTitle(TITLE);
+if (!CARD && !SUB) { const d = new Date(items[0].t + 9 * 3600e3); SUB = `${d.getUTCFullYear()}.${String(d.getUTCMonth() + 1).padStart(2, "0")}.${String(d.getUTCDate()).padStart(2, "0")}`; }
 lap(`vision ${jobs.length ? `${items.filter((i) => i.vcap).length}/${photos.filter((p) => !caps[p.f]).length} captions` : "off"} · title «${TITLE}»`);
 
 // ── assets (same cache as build.mjs) ───────────────────────────────────────────
@@ -119,7 +122,7 @@ for (const [rel, url] of Object.entries(ASSETS)) {
 // ── music: cut to length · fade in/out · level to about -16 LUFS (the whole mix is music) ──
 const BGM = process.env.FIELD_REEL_BGM || join(CACHE, "bgm", "field.wav");
 let music = "";
-if (PART !== "body" && existsSync(BGM)) {
+if (PART === "full" && existsSync(BGM)) {
   const r = run("ffmpeg", ["-v", "error", "-y", "-i", BGM, "-t", String(TOTAL), "-af", `afade=t=in:d=0.4,afade=t=out:st=${f(TOTAL - 1.6)}:d=1.6,loudnorm=I=-16:TP=-1.5:LRA=9`, "-ar", "48000", "-ac", "2", join(media, "bgm.wav")]);
   if (r.status === 0) music = "bgm.wav"; else console.error(`reel: music skipped — ${r.stderr.slice(0, 160)}`);
 }
@@ -165,16 +168,18 @@ const clips = items.map((it, i) => {
   return vis + cap;
 }).join("\n");
 
-const intro = PART === "body" ? "" : `<section class="clip card" data-start="0" data-duration="${INTRO}" data-track-index="6">`
+const intro = PART === "body" || PART === "end" ? "" : `<section class="clip card" data-start="0" data-duration="${INTRO}" data-track-index="6">`
   + `<div class="kick ik">현장 스케치</div>${mark(200, "im")}<h1>${words(TITLE, "it")}</h1><div class="line il"></div><p class="is">${esc(SUB)}</p></section>`;
-const end = PART === "body" ? "" : `<section class="clip card" data-start="${f(t)}" data-duration="${END}" data-track-index="6">`
+const end = PART === "body" || PART === "intro" ? "" : `<section class="clip card" data-start="${f(t)}" data-duration="${END}" data-track-index="6">`
   + `${mark(230, "em")}<h1 class="et">Elanous</h1><p class="et">사진을 올리면, 영상이 됩니다</p><p class="et red">elanous.ai</p></section>`;
-if (PART !== "body") {
+if (PART === "full" || PART === "intro") {
   tw.push(`tl.fromTo(".ik", {opacity:0, letterSpacing:"0.6em"}, {opacity:1, letterSpacing:"0.28em", duration:0.8, ease:"power3.out"}, 0.1);`);
   tw.push(`tl.fromTo(".im", {rotation:-160, scale:0.6, opacity:0}, {rotation:0, scale:1, opacity:1, duration:1.0, ease:"power3.out"}, 0.0);`);
   tw.push(`tl.fromTo(".it", {opacity:0, y:50}, {opacity:1, y:0, duration:0.55, stagger:0.1, ease:"power3.out"}, 0.45);`);
   tw.push(`tl.fromTo(".il", {scaleX:0}, {scaleX:1, duration:0.6, ease:"power3.inOut"}, 0.9);`);
   tw.push(`tl.fromTo(".is", {opacity:0, y:16}, {opacity:1, y:0, duration:0.45, ease:"power3.out"}, 1.15);`);
+}
+if (PART === "full" || PART === "end") {
   tw.push(`tl.fromTo(".em", {rotation:-200, scale:0.5}, {rotation:0, scale:1, duration:1.2, ease:"power3.out"}, ${f(t)});`);
   tw.push(`tl.fromTo(".et", {opacity:0, y:20}, {opacity:1, y:0, duration:0.5, stagger:0.14, ease:"power3.out"}, ${f(t + 0.5)});`);
 }

package/skills/explainer-video/engine/reel.sh

@@ -1,9 +1,28 @@
 #!/bin/zsh
-# Field reel in one command: folder of phone photos/clips → <folder>/reel/<name>-9x16.mp4 · prints the elapsed seconds.
+# Field reel: standard full composition or instant body with cached cards.
 # The layout/contrast check is advisory: phone photos behind captions often miss 3:1, and a failed check must not stop the reel.
-# Usage: zsh reel.sh <folder> [--title "…"] [--sub "…"]   (captions: <folder>/captions.txt — `파일 | 자막`)
-E=${0:A:h}; F=${1:A}; shift
+# Usage: zsh reel.sh <folder> [--title "…"] [--sub "…"] [--instant]   (captions: <folder>/captions.txt — `파일 | 자막`)
+E=${0:A:h}
+if [[ $1 == --warm-cards ]]; then
+  shift
+  node $E/stitch.mjs --warm-cards "$@"
+  exit $?
+fi
+F=${1:A}; shift
 [[ -d $F ]] || { print -u2 "reel: no folder $F"; exit 2 }
 T0=$(date +%s)
-rm -rf $F/reel && node $E/reel.mjs $F "$@" && (cd $F/reel/hf && { npx -y hyperframes@${HYPERFRAMES_VERSION:-0.8.95} check >../render.log 2>&1 || print "reel: check reported issues (continuing — user photos vary; see above)" >>../render.log }; npx -y hyperframes@${HYPERFRAMES_VERSION:-0.8.95} render --fps 30 --workers 4 --output ../reel-9x16.mp4 >>../render.log 2>&1) || { print -u2 "reel: FAILED — see $F/reel/render.log"; exit 1 }
-print "reel: $F/reel/reel-9x16.mp4 · $(( $(date +%s) - T0 ))s"
+instant=0
+args=()
+for arg in "$@"; do
+  if [[ $arg == --instant ]]; then instant=1; else args+=("$arg"); fi
+done
+rm -rf $F/reel
+if (( instant )); then
+  node $E/reel.mjs $F "${args[@]}" --part body &&
+    (cd $F/reel/hf && { npx -y hyperframes@${HYPERFRAMES_VERSION:-0.8.95} check >../render.log 2>&1 || print "reel: check reported issues (continuing — user photos vary; see above)" >>../render.log }; npx -y hyperframes@${HYPERFRAMES_VERSION:-0.8.95} render --fps 30 --workers 4 --output ../body.mp4 >>../render.log 2>&1) &&
+    node $E/stitch.mjs --instant $F >>$F/reel/render.log 2>&1 || { print -u2 "reel: FAILED — see $F/reel/render.log"; exit 1 }
+  print "reel: $F/reel/reel-9x16.mp4 · $(( $(date +%s) - T0 ))s (instant)"
+else
+  node $E/reel.mjs $F "${args[@]}" && (cd $F/reel/hf && { npx -y hyperframes@${HYPERFRAMES_VERSION:-0.8.95} check >../render.log 2>&1 || print "reel: check reported issues (continuing — user photos vary; see above)" >>../render.log }; npx -y hyperframes@${HYPERFRAMES_VERSION:-0.8.95} render --fps 30 --workers 4 --output ../reel-9x16.mp4 >>../render.log 2>&1) || { print -u2 "reel: FAILED — see $F/reel/render.log"; exit 1 }
+  print "reel: $F/reel/reel-9x16.mp4 · $(( $(date +%s) - T0 ))s"
+fi

package/skills/explainer-video/engine/stitch.mjs

@@ -0,0 +1,145 @@
+// Pre-render field cards once; render only the photo composition on subsequent runs.
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const W = 1080, H = 1920, FPS = 30, CARD_VERSION = 1;
+const cacheRoot = () => process.env.EXPLAINER_CACHE || join(homedir(), '.cache', 'elanous-explainer');
+const valid = (path) => { try { const stat = statSync(path); return stat.isFile() && stat.size > 0; } catch { return false; } };
+function run(bin, args, cwd) {
+  const result = spawnSync(bin, args, { cwd, encoding: 'utf8', maxBuffer: 4 * 1024 * 1024 });
+  if (result.error || result.status !== 0) throw new Error(`${bin}: ${result.error?.message ?? result.stderr?.slice(-2000) ?? `exit ${result.status}`}`);
+  return result.stdout;
+}
+
+async function renderCards({ title, sub, intro, end, cacheDir }) {
+  for (const [part, output] of [['intro', intro], ['end', end]]) {
+    if (valid(output)) continue;
+    const project = join(cacheDir, `project-${part}`);
+    mkdirSync(project, { recursive: true });
+    run('node', [join(here, 'reel.mjs'), project, '--part', part, '--title', title, '--sub', sub]);
+    run('npx', ['-y', `hyperframes@${process.env.HYPERFRAMES_VERSION || '0.8.95'}`, 'render', '--fps', String(FPS), '--workers', '4', '--output', output], join(project, 'reel', 'hf'));
+  }
+}
+
+export const normalizeCardTitle = (title) => !title || /^[a-z0-9]+(?:-[a-z0-9]+)*$/i.test(title) ? '현장 스케치' : title;
+
+function ownerGone(lock) {
+  let pid;
+  try { pid = JSON.parse(readFileSync(join(lock, 'owner.json'), 'utf8')).pid; }
+  catch (error) {
+    if (error.code !== 'ENOENT' && !(error instanceof SyntaxError)) throw error;
+    // A new owner may still be writing its identity. Never reclaim that window.
+    try { return Date.now() - statSync(lock).mtimeMs > 5_000; } catch { return false; }
+  }
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return false; }
+  catch (error) { return error.code === 'ESRCH'; }
+}
+
+// A single reaper checks identity again under this claim before moving an orphan.
+function recoverLock(lock) {
+  const recovery = `${lock}.recovery`;
+  try { mkdirSync(recovery); }
+  catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    if (ownerGone(recovery)) rmSync(recovery, { recursive: true, force: true });
+    return;
+  }
+  try {
+    writeFileSync(join(recovery, 'owner.json'), JSON.stringify({ pid: process.pid }));
+    if (!ownerGone(lock)) return;
+    const abandoned = `${lock}.abandoned-${randomUUID()}`;
+    try { renameSync(lock, abandoned); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; return; }
+    rmSync(abandoned, { recursive: true, force: true });
+  } finally { rmSync(recovery, { recursive: true, force: true }); }
+}
+
+export async function ensureCards({ title, sub, cacheDir = join(cacheRoot(), 'cards'), render = renderCards }) {
+  title = normalizeCardTitle(title);
+  const key = createHash('sha256').update(JSON.stringify([title, sub, W, H, CARD_VERSION])).digest('hex').slice(0, 16);
+  const dir = join(cacheDir, key);
+  const intro = join(dir, 'intro.mp4'), end = join(dir, 'end.mp4');
+  const ready = () => valid(intro) && valid(end);
+  if (ready()) return { intro, end, cardsCache: 'hit' };
+  mkdirSync(cacheDir, { recursive: true });
+  const lock = `${dir}.lock`;
+  const deadline = Date.now() + 10 * 60_000;
+  for (;;) {
+    try {
+      mkdirSync(lock);
+      try { writeFileSync(join(lock, 'owner.json'), JSON.stringify({ pid: process.pid })); }
+      catch (error) { rmSync(lock, { recursive: true, force: true }); throw error; }
+      break;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      if (ready()) return { intro, end, cardsCache: 'hit' };
+      recoverLock(lock);
+      if (Date.now() >= deadline) throw new Error(`timed out waiting for card render: ${lock}`);
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }
+  let staging;
+  try {
+    if (ready()) return { intro, end, cardsCache: 'hit' };
+    staging = mkdtempSync(join(cacheDir, `.${key}-`));
+    await render({ title, sub, intro: join(staging, 'intro.mp4'), end: join(staging, 'end.mp4'), cacheDir: staging });
+    if (!valid(join(staging, 'intro.mp4')) || !valid(join(staging, 'end.mp4'))) throw new Error(`card renderer did not produce both cards: ${dir}`);
+    rmSync(dir, { recursive: true, force: true });
+    renameSync(staging, dir);
+    return { intro, end, cardsCache: 'miss' };
+  } finally {
+    if (staging) rmSync(staging, { recursive: true, force: true });
+    rmSync(lock, { recursive: true, force: true });
+  }
+}
+
+function duration(file) {
+  const seconds = Number(run('ffprobe', ['-v', 'error', '-show_entries', 'format=duration', '-of', 'default=noprint_wrappers=1:nokey=1', file]).trim());
+  if (!Number.isFinite(seconds) || seconds <= 0) throw new Error(`invalid duration: ${file}`);
+  return seconds;
+}
+
+export function stitch({ intro, body, end, bgm, out }) {
+  const first = duration(intro), middle = duration(body), last = duration(end);
+  if (Math.min(first, middle, last) <= 0.3) throw new Error('xfade requires clips longer than 0.3s');
+  const total = first + middle + last - 0.6;
+  const args = ['-v', 'error', '-y', '-i', intro, '-i', body, '-i', end];
+  const music = bgm && existsSync(bgm);
+  if (music) args.push('-stream_loop', '-1', '-i', bgm);
+  const filters = [
+    ...[0, 1, 2].map((i) => `[${i}:v]fps=${FPS},scale=${W}:${H},setsar=1,format=yuv420p,settb=AVTB,setpts=PTS-STARTPTS[v${i}]`),
+    `[v0][v1]xfade=transition=fade:duration=0.3:offset=${(first - 0.3).toFixed(3)}[v01]`,
+    `[v01][v2]xfade=transition=fade:duration=0.3:offset=${(first + middle - 0.6).toFixed(3)}[v]`,
+  ];
+  if (music) filters.push(`[3:a]atrim=duration=${total.toFixed(3)},asetpts=PTS-STARTPTS,afade=t=in:d=0.4,afade=t=out:st=${Math.max(0, total - 1.6).toFixed(3)}:d=1.6,loudnorm=I=-16:TP=-1.5:LRA=9[a]`);
+  else filters.push(`anullsrc=r=48000:cl=stereo,atrim=duration=${total.toFixed(3)}[a]`);
+  mkdirSync(dirname(out), { recursive: true });
+  run('ffmpeg', [...args, '-filter_complex', filters.join(';'), '-map', '[v]', '-map', '[a]', '-t', total.toFixed(3), '-r', String(FPS), '-c:v', 'libx264', '-preset', 'veryfast', '-pix_fmt', 'yuv420p', '-c:a', 'aac', '-ar', '48000', '-ac', '2', '-movflags', '+faststart', out]);
+  return out;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const args = process.argv.slice(2);
+  const value = (name) => { const i = args.indexOf(name); return i < 0 ? undefined : args[i + 1]; };
+  const folder = args[1] && resolve(args[1]);
+  if (args[0] === '--warm-cards') {
+    const title = value('--title'), sub = value('--sub');
+    if (title === undefined || sub === undefined) throw new Error('--warm-cards requires --title and --sub');
+    const cards = await ensureCards({ title, sub });
+    console.log(`reel: cards ${cards.cardsCache} · ${dirname(cards.intro)}`);
+  } else if (args[0] === '--instant' && folder) {
+    const timelineFile = join(folder, 'reel', 'timeline.json');
+    const timeline = JSON.parse(readFileSync(timelineFile, 'utf8'));
+    const cards = await ensureCards({ title: timeline.title, sub: timeline.sub });
+    const bgm = process.env.FIELD_REEL_BGM || join(cacheRoot(), 'bgm', 'field.wav');
+    stitch({ intro: cards.intro, body: join(folder, 'reel', 'body.mp4'), end: cards.end, bgm, out: join(folder, 'reel', 'reel-9x16.mp4') });
+    writeFileSync(timelineFile, JSON.stringify({ ...timeline, cardsCache: cards.cardsCache, music: existsSync(bgm) }, null, 2));
+    console.log(`reel: cards ${cards.cardsCache}`);
+  } else throw new Error('usage: stitch.mjs --warm-cards --title … --sub … | --instant <folder>');
+}

package/skills/google-workspace/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: google-workspace
+description: Use your own Google account to find, summarize and draft Gmail messages; read or create Calendar events; read Drive and Sheets.
+requires: []
+---
+
+# Google Workspace
+
+## Set up
+
+Install the `gws` CLI and run `gws auth login` with **your own Google account**. Grant the scopes required for the requested operation in your account. Do not request or expose credentials in chat.
+
+Run commands from this skill directory so the bundled wrapper resolves by relative path:
+
+```bash
+bash scripts/gws-safe.sh gmail users messages list --params '{"userId":"me","q":"is:unread","maxResults":10}'
+```
+
+Use `scripts/gws-safe.sh` for API calls, not `gws` directly. The wrapper removes proxy variables, strips the keyring banner before JSON output, and checks the API method against `gws schema` before running it. A read with an unknown method is blocked too; do not bypass the check. `gws schema <service.resource.method>` can be used to inspect the method locally.
+
+## Supported work
+
+- Gmail: find messages, read and summarize their contents, compose a draft in the reply, or save an approved draft in Gmail. Saving a draft is a write and requires the write gate below.
+- Calendar: look up events and create events after confirming their details with the user.
+- Drive and Sheets: read files and spreadsheet data. Do not edit them without an explicit request.
+
+For example, read Calendar events with `bash scripts/gws-safe.sh calendar events list --params '{"calendarId":"primary"}'`. Check the relevant API schema and required parameters before issuing other calls. Treat API errors as errors, not as empty results.
+
+## Write gate and user confirmation
+
+Before sending email, deleting anything, or performing another irreversible action, ask the user for explicit confirmation of the **specific action and its targets**. Creating Calendar events and saving Gmail drafts also writes to the account: confirm the details before doing either. The wrapper rejects POST, PUT, PATCH, DELETE and unknown methods with exit code 4 by default; it is not permission to silently enable writes.
+
+For each write, first inspect `gws schema <service.resource.method>` and prepare the exact wrapper command, including recipient or calendar, content, and parameters. Show those details to the user and wait for their explicit approval of **that command**. Only after that approval, run the same command yourself from this skill directory with the one-command prefix `ELANOUS_GWS_ALLOW_WRITE=1 bash scripts/gws-safe.sh ...`. Check the JSON response for errors and report the result; do not reuse approval for another command, silently change its arguments, leave the variable enabled for later calls, or bypass the wrapper. If the user does not approve, do not execute the write.

package/skills/google-workspace/scripts/gws-safe.sh

@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+# 🔐 **`gws` 를 «안전하게» 부르는 한 자리** — ⛔ 이 셸의 함정 둘을 여기서 «한 번만» 막는다.
+#
+#   bash scripts/google/gws-safe.sh gmail users messages list --params '{"userId":"me"}'
+#
+# ⛔⭐ **함정 ①: 프록시** — 이 셸엔 HTTPS_PROXY 가 걸려 있고 `gws` 가 그것을 통과 못 한다
+#    (문면: "tunnel error: unsuccessful"). ⇒ 프록시를 «빼고» 부른다.
+#    🚨 이 한 줄이 없으면 범위가 멀쩡해도 ***401 로 「인증 실패」처럼 보인다*** — 2026-08-26 에 그렇게 오진할 뻔했다.
+#
+# ⛔⭐ **함정 ②: 머리말** — `gws` 는 "Using keyring backend …" 를 stdout 에 «섞는다».
+#    그대로 파서에 주면 JSON 파싱이 죽고, ***그 죽음이 「API 실패」처럼 보인다***(32차에 실제로 그랬다).
+#    ⇒ 첫 `{` 또는 `[` «부터» 잘라 낸다. `grep -v` 로 한 줄만 거르는 것으로는 부족했다.
+#
+# 📌 **왜 이 파일이 «따로» 있나**: 이 지식이 `scripts/botlab/assistant-google.sh` «안»에만 있었다.
+#    Google 을 쓰는 두 번째 소비자(스킬)를 만들면서 ***복제하지 않으려고*** 뽑았다.
+#    ⛔ 새 소비자는 이 파일을 «부른다» — gws 를 직접 부르지 마라.
+set -uo pipefail
+
+if [ "$#" -eq 0 ]; then
+  echo "⛔ 인자가 «없다» — gws 에 넘길 명령을 그대로 준다." >&2
+  echo "   예: bash scripts/google/gws-safe.sh gmail users messages list --params '{\"userId\":\"me\"}'" >&2
+  exit 2
+fi
+
+# ⛔⭐⭐ **크론의 `PATH` 에는 `gws` 도 `node` 도 «없다»** — 이 저장소가 «여섯 번째» 밟은 자리다.
+#    🚨 2026-08-29 실측: 아침 07:30 회차가 `gws 를 못 찾았다` ×3 으로 죽었다. 손으로 돌리면 «된다».
+#    ⛔⛔ 그리고 ***절대 경로만으로는 부족하다*** — `gws` 의 shebang 이 `#!/usr/bin/env node` 라
+#       node 가 PATH 에 없으면 ***rc=127***이다(매뉴얼의 ④ 「있는데도 안 된다」 층).
+#       📏 반증: `env -i PATH=/usr/bin:/bin <절대경로>/gws --help` ⇒ rc=127 ·
+#              그 디렉터리를 PATH 에 넣으면 ⇒ rc=0.
+#    ⇒ 그래서 ⓐ 실물로 «찾고» ⓑ ***찾은 것의 디렉터리를 PATH 에 넣는다***(node 가 그 옆에 산다).
+resolve_gws_bin() {
+  local candidate
+  # ⛔⭐ **명시값은 «그것만» 쓴다** — 「이것을 써라」이지 「여기부터 찾아라」가 아니다.
+  #    🚨 첫 판은 명시값이 없을 때 자동 탐색으로 «흘러내려» 갔고, 그 바람에
+  #       ***「gws 가 없다」는 상황을 시험이 만들 수 없었다***(시험이 즉시 잡았다).
+  if [ -n "${ELANOUS_GWS_BIN:-}" ]; then
+    if [ -x "$ELANOUS_GWS_BIN" ]; then printf '%s\n' "$ELANOUS_GWS_BIN"; return 0; fi
+    if command -v "$ELANOUS_GWS_BIN" >/dev/null 2>&1; then command -v "$ELANOUS_GWS_BIN"; return 0; fi
+    return 0   # ⛔ 명시했는데 없으면 «없는 것»이다 — 다른 데서 찾지 않는다
+  fi
+  if command -v gws >/dev/null 2>&1; then command -v gws; return 0; fi
+  # ⛔ nvm 은 «버전 디렉터리»가 바뀐다 — 경로를 박지 않고 훑는다(사전순 마지막 = 대개 최신).
+  for candidate in "$HOME"/.nvm/versions/node/*/bin/gws /opt/homebrew/bin/gws /usr/local/bin/gws; do
+    [ -x "$candidate" ] && printf '%s\n' "$candidate"
+  done | tail -1
+}
+GWS_BIN="$(resolve_gws_bin)"
+if [ -z "$GWS_BIN" ]; then
+  echo "⛔ gws 를 «못 찾았다»(${ELANOUS_GWS_BIN:-gws}) — 「Google 이 안 된다」가 아니라 ***이 기계에 그 CLI 가 없다***." >&2
+  echo "   본 곳: \$ELANOUS_GWS_BIN · PATH · ~/.nvm/versions/node/*/bin · /opt/homebrew/bin · /usr/local/bin" >&2
+  exit 3
+fi
+# ⛔ 「찾았다」로 끝내지 않는다 — 그 옆의 node 를 쓸 수 있게 «뒤»에 붙인다.
+#    ⚠️ «뒤»인 이유: 부르는 쪽이 준 PATH(시험의 가짜들)를 밀지 않기 위해서다.
+GWS_DIR="$(cd "$(dirname "$GWS_BIN")" 2>/dev/null && pwd)" || GWS_DIR=""
+[ -n "$GWS_DIR" ] && export PATH="$PATH:$GWS_DIR"
+
+# ⛔⭐⭐⭐ **열쇠고리(Keychain)를 «쓰는» 순간 크론이 죽는다 — 그래서 저장소를 «파일»로 못 박는다.**
+#    🚨 2026-08-29(36차) 실측 · ***크론 회차의 전체 문면이 스스로 답을 말했다***:
+#       401 Authentication failed: Failed to get token:
+#           Error while setting token in cache: OS keyring failed:
+#           Platform secure storage failure: ***User interaction is not allowed.***
+#           ⇒ Set GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file to use file storage.
+#    ⇒ 🔑 인증은 «됐고», 갱신한 토큰을 ***Keychain 에 «쓰다가»*** 죽는다. 크론은 비대화형이라
+#       그 쓰기에 필요한 사용자 확인을 못 받는다. ⛔ 「로그인이 안 됐다」가 아니다.
+#
+#    ⛔⭐⭐ **그리고 이 축은 `env` 로 «재현되지 않는다»** — 36차가 실제로 속았다:
+#       `env -i PATH=/usr/bin:/bin …` 로 돌리면 ***성공한다***(같은 시각 크론은 실패).
+#       ***보안 세션은 환경변수를 따라오지 않기 때문***이다. ⇒ 「크론과 같은 PATH 로 돌려 봤다」는
+#       크론 판정이 «아니다». 판정은 ***진짜 크론 회차***로만 한다(RFC §27c ④ 가 옳았다 · 두 번).
+#
+#    ⚖️ **보안 결정**: 파일 저장소는 열쇠를 Keychain 대신 «파일»에 둔다. 이 기계는 이미 같은 계급의
+#       결정을 한 번 했다(`~/.config/gws/credentials.json` 평문 · 대표 승인 2026-08-29). 그 디렉터리는
+#       `drwx------`(0700)이다. ⛔ 명시값이 있으면 «그것을» 존중한다 — 여기서 덮어쓰지 않는다.
+export GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND="${GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND:-file}"
+
+# ⛔ 그래도 열쇠고리 오류가 나면 «이름을 대고» 말한다 — 조용히 401 로 흘리지 않는다.
+diagnose_keyring_401() {
+  {
+    echo "⛔⭐ 이 401 은 «로그인 실패»가 아니다 — 토큰을 ***저장소에 쓰다가*** 죽었다."
+    echo "     지금 백엔드: GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=${GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND:-(비어 있다)}"
+    echo "     ⇒ 이 값이 file 이 «아니면» 누가 밖에서 덮어쓴 것이다(이 파일은 file 을 기본으로 준다)."
+    echo "     ⇒ file 인데도 났다면 ~/.config/gws 의 쓰기 권한을 봐라(0700 이어야 한다)."
+    echo "   ⛔ 「사람이 다시 로그인하면 된다」로 읽지 마라 — 그 로그인은 이미 돼 있다."
+  } >&2
+}
+
+# ⛔⭐⭐ **403 을 「범위 부족」으로만 읽지 않는다 — «왜» 그 자격인지가 다른 층에 있다.**
+#    🚨 2026-08-29 실측 · 외부 문서로 확인(deepwiki googleworkspace/cli 2.2-authentication):
+#       gws 의 자격 해결 순서는 ***TOKEN/CREDENTIALS_FILE → credentials.enc → credentials.json → ADC*** 이고,
+#       토큰 캐시는 AES-256-GCM 이며 ***그 열쇠가 OS keyring(macOS Keychain)에 산다***.
+#    ⇒ 그래서 Keychain 을 «못 읽는» 세션(크론 · 에이전트 하위 프로세스)에서는
+#       ***조용히 ADC 로 폴백***하고, ADC 는 gcloud 공용 클라이언트라 Gmail 같은 민감 범위가
+#       «이미 차단»돼 있어 ***403 insufficientPermissions*** 가 난다.
+#    📏 이 기계에서 잰 것: `gws auth status` ⇒ `storage=none` · `keyring_backend=keyring` ·
+#       `token_cache_exists=true` ⊕ `security find-generic-password -s gws-cli -w` 가 ***프롬프트에 걸려 rc=124***.
+#    ⛔ 그러니 「사람이 로그인만 하면 된다」로 안내하면 «틀린 길»로 보낸다 — 그 로그인은 이미 돼 있었다.
+diagnose_403() {
+  local storage
+  storage="$("$GWS_BIN" auth status 2>/dev/null \
+    | sed -n 's/.*"storage" *: *"\([^"]*\)".*/\1/p' | head -1)"
+  [ "$storage" = "none" ] || return 0
+  {
+    echo "⛔⭐ 그런데 이 403 은 «범위만»의 문제가 아닐 수 있다 — 자격 저장소를 «못 읽고» 있다:"
+    echo "     gws auth status ⇒ storage=none (keyring 을 못 읽었다) ⇒ ***ADC 로 폴백***한 것이다."
+    echo "     ADC 는 gcloud 공용 클라이언트라 Gmail 등 민감 범위가 «이미 차단»돼 있다."
+    echo "   ⇒ 사람이 «자기 터미널»에서 한 번(크론·에이전트도 읽을 수 있게 «파일»로 내린다):"
+    echo "       gws auth export --unmasked > ~/.config/gws/credentials.json && chmod 600 ~/.config/gws/credentials.json"
+    echo "     ⛔ 그 파일은 «평문 자격»이다 — 두는 것 자체가 보안 결정이다(0600 필수)."
+  } >&2
+}
+
+# ── 🚧 쓰기 관문 ────────────────────────────────────────────────────────────
+# ⛔⭐⭐ ***되돌릴 수 없는 것을 «규율»로만 막지 않는다.***
+#    `google-workspace` 스킬의 SKILL.md 가 「명시 없으면 초안까지」라고 «부탁»하지만,
+#    그것은 프롬프트다 — ***관문이 아니다***. 메일 전송·일정 삭제는 되돌릴 길이 «없다».
+#    📌 브라우저 축이 같은 자리에서 같은 답을 냈다(`decideReversibility` · `actionHosts`).
+#
+# ⭐ **이름을 짐작하지 않는다** — Google 이 «스스로» 말한다:
+#      gws schema <service.resource.method>  ⇒  "httpMethod": "GET" | "POST" | "DELETE" | …
+#    📏 실측 2026-08-28: 이 조회는 ***지역*** 이다(죽은 프록시로도 답한다) · 165~181ms.
+#
+# ⛔ 모르면 «막는다» — 「모른다」를 「괜찮다」로 읽지 않는다(브라우저 축의 ClickKind 와 같은 규율).
+gws_write_gate() {
+  # gws <service> <resource> [sub-resource] <method> [flags] — 첫 «플래그» 앞까지가 위치 인자다.
+  local -a pos=()
+  local a
+  for a in "$@"; do
+    case "$a" in -*) break ;; *) pos+=("$a") ;; esac
+  done
+  # `schema` 자체는 조회다 — 그리고 위치 인자가 모자라면 gws 가 스스로 거절한다.
+  if [ "${#pos[@]}" -lt 2 ] || [ "${pos[0]}" = "schema" ] || [ "${pos[0]}" = "auth" ]; then return 0; fi
+
+  local path
+  path=$(IFS=.; echo "${pos[*]}")
+  local http
+  http=$(env -u HTTP_PROXY -u HTTPS_PROXY -u http_proxy -u https_proxy -u ALL_PROXY -u all_proxy \
+    "$GWS_BIN" schema "$path" 2>/dev/null \
+    | sed -n '/^[[{]/,$p' \
+    | python3 -c 'import sys,json
+try: print((json.load(sys.stdin) or {}).get("httpMethod") or "")
+except Exception: print("")' 2>/dev/null)
+
+  case "$http" in
+    GET|HEAD) return 0 ;;
+    "")
+      echo "⛔ 이 호출이 «읽기인지 쓰기인지» 못 알아냈다(schema $path 가 httpMethod 를 안 냈다)." >&2
+      echo "   ⇒ 「모른다」를 「괜찮다」로 읽지 않는다. 읽기라면 경로를 확인하고, 쓰기라면 아래를 보라." >&2
+      ;;
+    *)
+      echo "⛔ 이것은 «쓰기»다($http $path) — ***되돌릴 길이 없다***." >&2
+      ;;
+  esac
+  echo "   사람이 그 «한 번»을 명시로 열어야 한다:  ELANOUS_GWS_ALLOW_WRITE=1 <같은 명령>" >&2
+  return 1
+}
+
+if [ "${ELANOUS_GWS_ALLOW_WRITE:-}" != "1" ]; then
+  gws_write_gate "$@" || exit 4
+fi
+
+# ⛔ 산출을 «한 번» 담는다 — 403 이면 그 «이유»를 같이 내야 하기 때문이다(diagnose_403).
+#    ⚠️ 담지 않으면 파이프 뒤에서 그 판정을 할 수 없다. gws 응답은 작아 이 비용이 싸다.
+GWS_RAW="$(env -u HTTP_PROXY -u HTTPS_PROXY -u http_proxy -u https_proxy -u ALL_PROXY -u all_proxy \
+  "$GWS_BIN" "$@" 2>&1)"
+GWS_RC=$?
+printf '%s\n' "$GWS_RAW" | sed -n '/^[[{]/,$p'
+
+# ⛔⭐ 403 을 «그냥 흘려보내지 않는다» — 자격 저장소를 못 읽어 ADC 로 폴백한 것일 수 있다.
+#    📌 그 갈림이 없으면 「사람이 로그인만 하면 된다」는 «틀린 길»로 안내하게 된다.
+case "$GWS_RAW" in *'"code": 403'*|*'"code":403'*) diagnose_403 ;; esac
+
+# ⛔⭐ 401 + 열쇠고리 문면이면 «다른 병»이다 — 403(범위·ADC 폴백)과 갈라서 말한다.
+case "$GWS_RAW" in *'OS keyring failed'*|*'secure storage failure'*) diagnose_keyring_401 ;; esac
+
+exit "$GWS_RC"

package/skills/grill-me/SKILL.md

@@ -128,7 +128,7 @@ requires: []
 | 🧑‍🤝‍🧑 **팀 짜기** | 일이 여럿으로 갈릴 때 | ⭐ 목표를 심은 뒤 *"이 일을 할 팀을 짜 보라"* — 인터뷰의 «응용»이다 |
 
 ⛔ **골 문면으로 갈 때는 파서가 무는 문면을 «그때» 확인한다** —
-`내부 문서 `MANUAL-goal-authoring-method-2026-08-03`` §1a. ⛔ 여기 옮겨 적지 않는다(늙는다).
+골 저작 방법 매뉴얼 §1a. ⛔ 여기 옮겨 적지 않는다(늙는다).
 
 ---