@litfamily/litgrok 1.0.30 → 1.0.31

package/.grok/rules/00-litgrok.md

@@ -203,7 +203,7 @@ An old agent name, prefixed or not, selects the renamed agent and prints that ro
 
 These rows are prompt guidance, not a router: old slash routes are not guaranteed; never create old skill directories or invent command metadata.
 
-<!-- litfamily:litgrok:start v=1.0.30 pre=0a -->
+<!-- litfamily:litgrok:start v=1.0.31 pre=0a -->
 ## LitGrok ground rules
 
 Grok Build reads this file on every turn. These lines are the working agreement. The sections above still choose the skill.

package/.grok/skills/lit-typographic-motion/references/stage.md

@@ -15,6 +15,7 @@ Allowed files: html, js, mjs, css, svg, png, jpg, webp, gif, wav, woff, woff2, t
   stage directory.
 - Rasters are textures and stills, never a frame sequence: at most 24 raster images and 8 MB in
   total. Ten or more rasters of one size (a flipbook), or any animated GIF, APNG or WebP, is exit 17.
+  The one frame sequence a page may carry is a declared keyed clip (Clips).
 - Forbidden, exit 17 naming it: `<video>`, `<audio>`, `<iframe>`, `<object>`, `<embed>`, `<frame>`,
   `new Audio()`, `AudioContext`, `OfflineAudioContext`, Worker, SharedWorker, service workers,
   WebSocket, WebTransport, RTCPeerConnection.
@@ -25,6 +26,8 @@ Allowed files: html, js, mjs, css, svg, png, jpg, webp, gif, wav, woff, woff2, t
 <script src="/lit/stage-kit.js"></script>
 ```
 
+A page with clips also loads `<script src="/lit/clips.js"></script>` (Clips).
+
 `/lit/fonts.css` declares the verified faces with `font-display: block`: `Archivo` (weights 400,
 700, 900; `font-stretch` 75 %, 100 %, 125 %), `Pretendard` (Hangul, 400 and 700), `VT323`,
 `Silkscreen` (400, 700), `Galmuri9` and `Meslo` (both need the pre-warm), and `JetBrains Mono`
@@ -88,11 +91,58 @@ LitStage.drawPath(svgPath, p);                       // stroke draw-on
 const shape = LitStage.morph(dA, dB); path.setAttribute('d', shape(p));        // single-subpath morph
 LitStage.clip(el, p, { from: 'left' });              // inset reveal; LitStage.circle(el, p, { x, y })
 const c = LitStage.mix('#0b1f33', '#7fd1ff', p);     // colour mix
+const show = LitStage.overlay({ parent, id, box });    // a declared keyed clip (Clips); show(t, { start })
 ```
 
 `morph` normalizes both paths to cubics, resamples them by arc length and picks the best rotation;
 paths with more than one subpath are not supported (split them into separate paths).
 
+## Clips
+
+Real keyed footage (a reaction clip, a spinning-cat loop shot on green screen) joins the film as a
+layer inside the page. Key the video outside the renderer into one 8-bit RGBA PNG per frame, declare
+the frames, and the page picks the frame from film time. A declared clip leaves the flipbook and
+count rule; every other raster keeps its limits. Nothing is encoded by hand: the page is captured
+frame by frame as usual, so the flash audit, the determinism replay and the text checks run on the
+final pixels.
+
+1. Copy each clip's frames into the run's stage folder as `stage/clips/<dir>/frame_0001.png`,
+   `frame_0002.png` and so on, with no gaps and no other image in the folder.
+2. Declare them in `stage/clips/clips.json`:
+
+   ```json
+   { "clips": [ { "id": "boom", "dir": "01-vine-boom", "count": 122, "fps": 30 } ] }
+   ```
+
+   `id` is the name the page uses, `dir` a folder directly under `clips/`, `count` the number of
+   frames and `fps` the clip's own rate, 1 to 30. A clip used twice is declared once.
+3. The page loads `<script src="/lit/clips.js"></script>` after the kit, registers each use once with
+   `LitStage.overlay({ parent, id, box })` and calls the returned `show(t, opts)` from `render(t)`.
+   (`LitStage.clip` is the inset reveal; it has nothing to do with clips.) `parent` is the element
+   the clip sits in; `box` is its place in pixels, the frame fitted inside it. `show` returns the
+   clip's wrapper element, or `null` while hidden; scale, fade or move that wrapper from `t` like any
+   other layer.
+
+```js
+const boom = LitStage.overlay({ parent: stageEl, id: 'boom', box: { x: 1200, y: 300, w: 520, h: 511 } });
+render(t) { boom(t, { start: 2.1 }); }
+```
+
+The frame is `floor((t - start) * fps) + 1`, counted from `from`, so a cue is plain arithmetic: a
+clip whose own sound starts at frame 85 and must land on a cue at 0.12 s has
+`start = 0.12 - 84 / 30`. Options: `start` (film seconds, default 0), `from` and `to` (the frame
+range, default the whole clip), `loop` (wrap by frame index) and `hold` (keep the last frame).
+Before `start` and past `to`, without `loop` or `hold`, the clip is hidden.
+
+The scan refuses, with exit 17 and the clip named: more than 12 clips, 360 frames in a clip or 1500
+in all, 40 MB in a clip or 128 MB in all, a frame whose long side is above 720 px (a clip is an
+overlay, not the film), an fps above 30, frames of mixed sizes, a missing or extra frame, a frame
+that is not an 8-bit RGBA PNG or has no transparent pixel in the first, middle and last frame (an
+opaque video is not keyed), an animated image, and a duplicate `id`. A folder that is not declared,
+or any frame sequence beside a declared clip, is a flipbook as before. Cover mode takes no clips.
+Keep clips clear of copy: the text checks read DOM text, so a clip laid over a line is yours to
+catch on the stills. The manifest and the gate report list each clip.
+
 ## Serving and network
 
 The page is served from the synthetic origin `http://lit.stage/` with no listening socket. Only

package/.grok/skills/lit-typographic-motion/scripts/lib/clips.mjs

@@ -0,0 +1,119 @@
+// Declared keyed overlay clips on the stage path: stage/clips/clips.json names RGBA frame folders,
+// scanClips checks every declared frame against its bytes, and clipsScript writes the table the page
+// reads as window.LitClips (served at /lit/clips.js). See references/stage.md, Clips.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { CLIP_LIMITS } from './constants.mjs';
+import { decodePng } from './png.mjs';
+
+export const CLIPS_DIR = 'clips';
+export const clipFrame = (i) => `frame_${String(i).padStart(4, '0')}.png`;
+const ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$/;
+const DIR = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/;
+const MB = 1024 * 1024;
+
+/** Header facts of a PNG: size, bit depth, colour type (6 = RGBA) and whether it is an APNG. */
+function pngHeader(bytes) {
+  if (bytes.length < 33 || bytes.toString('latin1', 1, 4) !== 'PNG') return null;
+  let animated = false;
+  for (let o = 8; o + 8 <= bytes.length;) {
+    const type = bytes.toString('latin1', o + 4, o + 8);
+    if (type === 'acTL') animated = true;
+    if (type === 'IDAT' || type === 'IEND') break;
+    o += 12 + bytes.readUInt32BE(o);
+  }
+  return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20), bitDepth: bytes[24], colorType: bytes[25], animated };
+}
+
+/** The clips stage/clips/clips.json declares ([] without the file), checked for shape only. Throws Error. */
+export function declaredClips(stageDir, limits = CLIP_LIMITS) {
+  const file = join(stageDir, CLIPS_DIR, 'clips.json');
+  if (!existsSync(file)) return [];
+  let doc;
+  try { doc = JSON.parse(readFileSync(file, 'utf8')); } catch (error) { throw new Error(`${CLIPS_DIR}/clips.json is not valid JSON (${error.message})`); }
+  if (!doc || !Array.isArray(doc.clips)) throw new Error(`${CLIPS_DIR}/clips.json needs { "clips": [ { "id", "dir", "count", "fps" } ] }`);
+  if (doc.clips.length > limits.clips) throw new Error(`${doc.clips.length} clips declared (at most ${limits.clips} clips)`);
+  const ids = new Set();
+  const dirs = new Set();
+  return doc.clips.map((c, n) => {
+    const at = `${CLIPS_DIR}/clips.json clip #${n + 1}`;
+    if (!c || typeof c !== 'object') throw new Error(`${at} is not an object`);
+    if (typeof c.id !== 'string' || !ID.test(c.id)) throw new Error(`${at}: id must be a plain token of letters, digits, - and _ (got ${JSON.stringify(c.id)})`);
+    if (ids.has(c.id)) throw new Error(`${at}: duplicate id ${c.id}`);
+    ids.add(c.id);
+    if (typeof c.dir !== 'string' || !DIR.test(c.dir) || c.dir.includes('..')) throw new Error(`clip "${c.id}": dir must be a folder name directly under ${CLIPS_DIR}/ (got ${JSON.stringify(c.dir)})`);
+    if (dirs.has(c.dir)) throw new Error(`clip "${c.id}": dir ${c.dir} is already declared by another clip`);
+    dirs.add(c.dir);
+    if (!Number.isInteger(c.count) || c.count < 1) throw new Error(`clip "${c.id}": count must be a whole number of frames (got ${JSON.stringify(c.count)})`);
+    if (!Number.isInteger(c.fps) || c.fps < 1 || c.fps > limits.fps) throw new Error(`clip "${c.id}": fps must be a whole number from 1 to ${limits.fps} (got ${JSON.stringify(c.fps)})`);
+    return { id: c.id, dir: c.dir, count: c.count, fps: c.fps };
+  });
+}
+
+/**
+ * Check every declared clip against its bytes. Each clip needs exactly frame_0001.png..frame_<count>.png in clips/<dir>/, every one an
+ * 8-bit still RGBA PNG of one size within the overlay cap, a transparent pixel in the first, middle and
+ * last frame, and the per-clip and total caps. Throws Error naming the clip; returns
+ * [{ id, dir, count, fps, width, height, bytes, frames }] where `frames` are stage-relative paths.
+ */
+export function scanClips(stageDir, { limits = CLIP_LIMITS } = {}) {
+  const decls = declaredClips(stageDir, limits);
+  let totalFrames = 0;
+  let totalBytes = 0;
+  const clips = decls.map((d) => {
+    if (d.count > limits.framesPerClip) throw new Error(`clip "${d.id}": ${d.count} frames (at most ${limits.framesPerClip} per clip)`);
+    const prefix = `${CLIPS_DIR}/${d.dir}/`;
+    const folder = join(stageDir, CLIPS_DIR, d.dir);
+    const have = new Set(existsSync(folder) ? readdirSync(folder, { withFileTypes: true }).filter((e) => e.isFile() && /\.(png|jpe?g|webp|gif)$/i.test(e.name)).map((e) => e.name) : []);
+    const frames = [];
+    for (let i = 1; i <= d.count; i += 1) {
+      if (!have.has(clipFrame(i))) throw new Error(`clip "${d.id}": ${prefix}${clipFrame(i)} is missing (declared ${d.count} frames, named frame_0001.png onward)`);
+      frames.push(`${prefix}${clipFrame(i)}`);
+    }
+    const stray = [...have].find((name) => !frames.includes(`${prefix}${name}`));
+    if (stray) throw new Error(`clip "${d.id}": ${prefix}${stray} is not one of the ${d.count} declared frames; raise count or remove it`);
+    let size = null;
+    let bytes = 0;
+    const read = (rel) => readFileSync(join(stageDir, ...rel.split('/')));
+    const headers = frames.map((rel) => {
+      const buffer = read(rel);
+      bytes += buffer.length;
+      const info = pngHeader(buffer);
+      if (!info) throw new Error(`clip "${d.id}": ${rel} is not a readable PNG`);
+      if (info.animated) throw new Error(`clip "${d.id}": ${rel} is an animated image; a clip is a folder of still frames`);
+      if (info.colorType !== 6 || info.bitDepth !== 8) throw new Error(`clip "${d.id}": ${rel} must be an 8-bit RGBA PNG with an alpha channel (a keyed frame), not an opaque image`);
+      if (Math.max(info.width, info.height) > limits.side) throw new Error(`clip "${d.id}": ${rel} is ${info.width}x${info.height}; a clip is an overlay of at most ${limits.side} px on the long side`);
+      if (size && (size.width !== info.width || size.height !== info.height)) throw new Error(`clip "${d.id}": ${rel} is ${info.width}x${info.height} but frame_0001.png is ${size.width}x${size.height}; one size per clip`);
+      size = { width: info.width, height: info.height };
+      return buffer;
+    });
+    if (bytes > limits.bytesPerClip) throw new Error(`clip "${d.id}": ${(bytes / MB).toFixed(1)} MB (at most ${(limits.bytesPerClip / MB).toFixed(0)} MB per clip)`);
+    for (const at of [0, Math.floor((frames.length - 1) / 2), frames.length - 1]) {
+      let pixels;
+      try { ({ pixels } = decodePng(headers[at])); } catch (error) { throw new Error(`clip "${d.id}": ${frames[at]} cannot be decoded (${error.message}); use a non-interlaced 8-bit RGBA PNG`); }
+      let keyed = false;
+      for (let i = 3; i < pixels.length && !keyed; i += 4) keyed = pixels[i] < 255;
+      if (!keyed) throw new Error(`clip "${d.id}": ${frames[at]} has no transparent pixel; a clip is keyed, not a full-frame video`);
+    }
+    totalFrames += d.count;
+    totalBytes += bytes;
+    return { ...d, ...size, bytes, frames };
+  });
+  if (totalFrames > limits.framesTotal) throw new Error(`${totalFrames} clip frames in all (at most ${limits.framesTotal})`);
+  if (totalBytes > limits.bytesTotal) throw new Error(`${(totalBytes / MB).toFixed(1)} MB of clip frames in all (at most ${(limits.bytesTotal / MB).toFixed(0)} MB)`);
+  return clips;
+}
+
+/**
+ * The script served at /lit/clips.js: window.LitClips = { id: { src, count, fps, width, height } }, from
+ * clips.json and each first frame's header. null when the stage declares no clips, or one the scan refuses.
+ */
+export function clipsScript(stageDir) {
+  try {
+    const table = Object.fromEntries(declaredClips(stageDir).map((c) => {
+      const info = pngHeader(readFileSync(join(stageDir, CLIPS_DIR, c.dir, clipFrame(1))));
+      return [c.id, { src: `${CLIPS_DIR}/${c.dir}`, count: c.count, fps: c.fps, width: info.width, height: info.height }];
+    }));
+    return Object.keys(table).length ? `window.LitClips = ${JSON.stringify(table)};\n` : null;
+  } catch { return null; }
+}

package/.grok/skills/lit-typographic-motion/scripts/lib/constants.mjs

@@ -195,6 +195,19 @@ export const STAGE = Object.freeze({
   determinismMax: 16,
 });
 
+// Keyed overlay clips (references/stage.md, Clips): frame folders declared in stage/clips/clips.json
+// are held to these caps instead of the raster limits above. A clip is a sticker on the film, never
+// the film: 8-bit RGBA PNG frames with real transparency, at most `side` px on the long side.
+export const CLIP_LIMITS = Object.freeze({
+  clips: 12,
+  framesPerClip: 360,
+  framesTotal: 1500,
+  bytesPerClip: 40 * 1024 * 1024,
+  bytesTotal: 128 * 1024 * 1024,
+  side: 720,
+  fps: 30,
+});
+
 // Cover mode (references/cover.md): the README cover loop and the gate that reads its DECODED file.
 // Calibrated on 2026-10-20 against eight earlier painted covers, four slide-like negatives and
 // three pilot loops; a number moves only with a new calibration table. FLOOR fails a cover (every

package/.grok/skills/lit-typographic-motion/scripts/lib/cover.mjs

@@ -137,7 +137,7 @@ function prepare({ out, env }) {
   const treatment = loadCoverTreatment(out);
   const dir = join(out, COVER_DIR);
   if (!existsSync(join(dir, 'index.html'))) throw new BlockedError(EXIT.STAGE_CONTRACT, `STAGE_CONTRACT_ERROR: ${join(dir, 'index.html')} is missing; write the cover page first (start from a recipe in recipes/)`);
-  const scan = scanStage(dir);
+  const scan = scanStage(dir, { clips: false });
   const rename = (line) => line.replaceAll('stage/', `${COVER_DIR}/`);
   if (scan.network.length) throw new BlockedError(EXIT.STAGE_NETWORK, `STAGE_NETWORK_REQUEST: ${rename(scan.network[0])}; a cover loads only its own files and the /lit/ routes`);
   if (scan.contract.length) throw new BlockedError(EXIT.STAGE_CONTRACT, `STAGE_CONTRACT_ERROR: ${rename(scan.contract[0])}`);

package/.grok/skills/lit-typographic-motion/scripts/lib/stage-gate.mjs

@@ -124,6 +124,7 @@ export function stageReportText({ manifest, gate, withheld, perf, outDir, treatm
   lines.push(`path: stage · format ${manifest.format} (${manifest.resolution.join('x')}) · ${manifest.durationSec.toFixed(2)} s of ${treatment.durationSec} s target @ ${manifest.fps} fps`);
   lines.push(`sound: ${manifest.sound?.label ?? 'n/a'}${manifest.sound?.timbre ? ` (${manifest.sound.timbre}, ${manifest.sound.key}, ${manifest.sound.tempo} BPM, ${manifest.sound.lufs?.toFixed?.(1)} LUFS)` : ''}`);
   lines.push(`renderer: ${manifest.renderer}`);
+  if (manifest.clips?.length) lines.push(`clips: ${manifest.clips.map((c) => `${c.id} ${c.frames} frames at ${c.fps} fps`).join(', ')} (keyed overlays, chosen from film time)`);
   lines.push('');
   lines.push(`QA gate: ${gate.status}`);
   for (const r of gate.results) lines.push(`  ${`${r.id}:`.padEnd(30)}${r.status}  (${r.detail})`);

package/.grok/skills/lit-typographic-motion/scripts/lib/stage-session.mjs

@@ -7,6 +7,7 @@ import { extname, join, sep } from 'node:path';
 import { STAGE } from './constants.mjs';
 import { launchStage } from './chrome.mjs';
 import { SKILL_ROOT } from './fonts.mjs';
+import { clipsScript } from './clips.mjs';
 
 export const CONTENT_TYPES = Object.freeze({
   '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.mjs': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8',
@@ -78,6 +79,7 @@ export async function openStage({ executable, outDir, stageDir, width, height, f
   const network = [];
   const refused = [];
   const served = new Set();
+  const clipsJs = clipsScript(stageDir);
   const kit = existsSync(KIT_PATH) ? readFileSync(KIT_PATH) : Buffer.from('/* stage kit missing */');
   const respond = (requestId, status, body, type) => browser.send('Fetch.fulfillRequest', {
     requestId, responseCode: status,
@@ -95,6 +97,7 @@ export async function openStage({ executable, outDir, stageDir, width, height, f
       return;
     }
     if (url.pathname === '/lit/stage-kit.js') { served.add('/lit/stage-kit.js'); await respond(requestId, 200, kit, CONTENT_TYPES['.js']); return; }
+    if (clipsJs && url.pathname === '/lit/clips.js') { served.add('/lit/clips.js'); await respond(requestId, 200, clipsJs, CONTENT_TYPES['.js']); return; }
     if (url.pathname.startsWith('/lit/three/')) {
       const resolved = resolveThree(url.pathname);
       if (resolved.refused) { refused.push(resolved.refused); await respond(requestId, 403, 'refused'); return; }

package/.grok/skills/lit-typographic-motion/scripts/lib/stage.mjs

@@ -6,6 +6,7 @@ import { createHash } from 'node:crypto';
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { extname, join, relative } from 'node:path';
 import { BlockedError, DIRECTOR, EXIT, STAGE } from './constants.mjs';
+import { scanClips } from './clips.mjs';
 import { resolveChrome, stageArgs } from './chrome.mjs';
 import { fontPath, fontState, PINS, resolveFontKey } from './fonts.mjs';
 import { FlashDetector } from './flash.mjs';
@@ -67,17 +68,24 @@ export function rasterInfo(bytes, ext) {
 }
 
 // Static scan before any launch: forbidden elements (17), absolute or protocol-relative URLs and
-// preconnect/prefetch links (19), raster limits, flipbooks and animated rasters (17).
-export function scanStage(stageDir) {
+// preconnect/prefetch links (19), raster limits, flipbooks and animated rasters (17). Frames of a clip
+// declared in clips/clips.json are checked by scanClips instead; `clips: false` (cover mode) ignores the
+// declaration, so a declared folder is held to the raster limits like any other.
+export function scanStage(stageDir, { clips: allowClips = true } = {}) {
   const contract = [];
   const network = [];
   const warnings = [];
-  if (!existsSync(join(stageDir, 'index.html'))) return { contract: ['stage/index.html is missing'], network, warnings, files: [], rasters: [] };
+  if (!existsSync(join(stageDir, 'index.html'))) return { contract: ['stage/index.html is missing'], network, warnings, files: [], rasters: [], clips: [] };
   const files = walk(stageDir);
   // A Blender plate and its preview stills are frames the runner wrote and plate.json lists by name
   // and size; they are not page rasters. Anything not listed is held to the raster limits.
   const plates = [readPlate(stageDir, 'plate'), readPlate(stageDir, 'plate-preview')].filter(Boolean);
   const listed = new Set(plates.flatMap((p) => p.frames.map((f) => `${p.dir}/${String(f.name)}`)));
+  let clips = [];
+  if (allowClips) {
+    try { clips = scanClips(stageDir); } catch (error) { contract.push(error.message); }
+    for (const clip of clips) for (const rel of clip.frames) listed.add(rel);
+  }
   const rasters = [];
   for (const file of files) {
     if (file.symlink) continue;
@@ -112,7 +120,7 @@ export function scanStage(stageDir) {
   const bySize = new Map();
   for (const r of rasters) { const key = `${r.width}x${r.height}`; bySize.set(key, (bySize.get(key) ?? 0) + 1); }
   for (const [size, count] of bySize) if (count >= STAGE.flipbookCount) contract.push(`${count} rasters of one size (${size}) form a flipbook; rasters are textures and stills, never a frame sequence`);
-  return { contract, network, warnings, files: files.map((f) => f.rel), rasters };
+  return { contract, network, warnings, files: files.map((f) => f.rel), rasters, clips };
 }
 
 // ---- fonts -----------------------------------------------------------------------------------
@@ -424,6 +432,7 @@ export async function renderStage({ out, treatment, round = 1, stillsOnly = fals
       schemaVersion: 1, path: 'stage', format: treatment.format, resolution: [width, height], fps, durationSec: totalFrames / fps, targetDurationSec: treatment.durationSec,
       frames: totalFrames, seed, rung: masterRung, renderer: `${masterRenderer} on the ${masterRung} rung (stage path)`, softwareRenderer: masterRung === 'software' || isSoftwareRenderer(masterRenderer), chromeFlags: masterArgs.filter((arg) => !arg.startsWith('--user-data-dir') && !arg.startsWith('--window-size') && arg !== 'about:blank'), previewEncoder: preview.encoder,
       sound: sound.summary, round, warnings,
+      clips: scan.clips.map((c) => ({ id: c.id, frames: c.count, fps: c.fps, width: c.width, height: c.height, bytes: c.bytes })),
     };
     const stills = writeStills(out, { plan, frames: kept, width, height, path: 'stage', round, mode: 'full', poster: { bytes: posterBytes, frame: posterFrame }, treatmentSha256 });
     // The final render ships its storyboard too: the done-check wants the board viewed on the final set.

package/.grok/skills/lit-typographic-motion/scripts/stage/stage-kit.js

@@ -280,6 +280,49 @@
     };
   }
 
+  // A declared keyed clip (stage/clips/clips.json, served as window.LitClips by /lit/clips.js): one
+  // wrapper at `box` over the film, holding the clip's frame for t. The frame is a pure function of film
+  // time, floor((t - start) * fps) + 1 within from..to, so no <video> and no real clock is involved.
+  // Before `start` and after `to` the wrapper is hidden (null) unless `hold` keeps the last frame or
+  // `loop` wraps by frame index. The wrapper is what a page scales or fades; the <img> inside is
+  // replaced on a frame change, so the renderer waits for its decode before the capture.
+  function overlay(opts) {
+    var all = root.LitClips, parent = opts && opts.parent, id = opts && opts.id, box = opts && opts.box;
+    if (!all) throw new Error('LitStage.overlay: load <script src="/lit/clips.js"></script> before the page script; the stage declares no clips (clips/clips.json)');
+    var c = all[id];
+    if (!c) throw new Error('LitStage.overlay: no clip "' + id + '" in clips/clips.json (declared: ' + Object.keys(all).join(', ') + ')');
+    if (!parent || !box || !(box.w > 0) || !(box.h > 0)) throw new TypeError('LitStage.overlay: pass { parent, id, box: { x, y, w, h } }');
+    var doc = parent.ownerDocument || root.document;
+    var wrap = doc.createElement('div');
+    wrap.setAttribute('data-lit-clip', id);
+    var ws = wrap.style;
+    ws.position = 'absolute'; ws.left = box.x + 'px'; ws.top = box.y + 'px'; ws.width = box.w + 'px'; ws.height = box.h + 'px';
+    ws.display = 'none'; ws.pointerEvents = 'none';
+    parent.append(wrap);
+    var shown = 0, img = null;
+    return function (t, o) {
+      o = o || {};
+      var start = o.start == null ? 0 : o.start, from = o.from == null ? 1 : o.from, to = o.to == null ? c.count : o.to;
+      if (!(from >= 1 && to <= c.count && from <= to)) throw new RangeError('LitStage.overlay: from..to must lie within 1..' + c.count + ' (got ' + from + '..' + to + ')');
+      var n = to - from + 1, k = Math.floor((t - start) * c.fps + 1e-6);
+      var i = k < 0 ? 0 : k < n ? from + k : o.loop ? from + (k % n) : o.hold ? to : 0;
+      wrap.style.display = i ? 'block' : 'none';
+      if (!i) return null;
+      if (i !== shown) {
+        var next = doc.createElement('img');
+        next.src = c.src + '/frame_' + String(i).padStart(4, '0') + '.png';
+        next.alt = '';
+        var ns = next.style;
+        ns.display = 'block'; ns.width = '100%'; ns.height = '100%'; ns.objectFit = 'contain';
+        if (img) img.replaceWith(next);
+        else wrap.append(next);
+        img = next;
+        shown = i;
+      }
+      return wrap;
+    };
+  }
+
   function rgb(hex) {
     var h = String(hex).replace('#', '');
     if (h.length === 3) h = h.split('').map(function (c) { return c + c; }).join('');
@@ -472,6 +515,7 @@
     clip: clip,
     circle: circle,
     plate: plate,
+    overlay: overlay,
     mix: mix,
     rgb: rgb,
     hex: hex,

package/.grok-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "litgrok",
-  "version": "1.0.30",
+  "version": "1.0.31",
   "description": "Grok Build skills, project rules, and bounded lifecycle hooks for evidence-first lit work.",
   "author": {
     "name": "LitGrok contributors"

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 1.0.31 — 2026-11-01
+
+- The motion skill's stage path can carry keyed overlay clips: real footage keyed on green screen outside the renderer into one RGBA PNG per frame, declared in `stage/clips/clips.json` (`id`, `dir`, `count`, `fps`). The page registers a clip once with `LitStage.overlay` and shows it from film time, so a cue is plain arithmetic and the flash audit, the determinism replay and the text checks still run on the final pixels. The scan holds clips to 12 per film, 360 frames each and 1500 in all, 40 MB each and 128 MB in all, 720 px on the long side and 30 fps, and refuses opaque or mixed-size frames with exit 17; an undeclared frame folder is still a flipbook, and cover mode takes no clips.
+
 ## 1.0.30 — 2026-10-31
 
 - `lit-adhd` counts other work before it tells this session what to do. A paused frame here is not resumed, and this session's own run is not continued with `go`, while another session or a herdr agent is still working. A start-work approval is still offered. The session's own card does not show `lit continue` while that work runs.

package/README.md

@@ -1,18 +1,18 @@
-<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/assets/cover-motion-still.webp" /><source media="(prefers-reduced-motion: no-preference)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/assets/cover-motion.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: seven armored robots power on one by one, the LitGrok robot wakes with glowing eyes and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
+<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/assets/cover-motion-still.webp" /><source media="(prefers-reduced-motion: no-preference)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/assets/cover-motion.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: seven armored robots power on one by one, the LitGrok robot wakes with glowing eyes and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
 
 <h1 align="center">LitGrok</h1>
 <p align="center"><strong>Keep the work lit.</strong></p>
 
 LitGrok gives xAI's Grok Build the habit of planning before it edits, checking what it built, and leaving a handoff, so tomorrow's session starts where today's stopped. One npm command adds its skills, project rule and hooks to your project.
 
-**[Full README on GitHub](https://github.com/wjgoarxiv/litgrok#readme)** · [Guide](https://github.com/wjgoarxiv/litgrok/blob/main/docs/guide.md) · [All skills](https://github.com/wjgoarxiv/litgrok/blob/main/docs/skills.md) · [한국어](https://github.com/wjgoarxiv/litgrok/blob/main/README_ko-KR.md) · [Install](#install-in-30-seconds) · [Reference](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/reference.md)
+**[Full README on GitHub](https://github.com/wjgoarxiv/litgrok#readme)** · [Guide](https://github.com/wjgoarxiv/litgrok/blob/main/docs/guide.md) · [All skills](https://github.com/wjgoarxiv/litgrok/blob/main/docs/skills.md) · [한국어](https://github.com/wjgoarxiv/litgrok/blob/main/README_ko-KR.md) · [Install](#install-in-30-seconds) · [Reference](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/reference.md)
 
 <p align="center">
-<a href="#install-in-30-seconds"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/assets/readme/badge-version.svg" alt="1.0.30" /></a>
-<a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/assets/readme/badge-license.svg" alt="MIT license" /></a>
+<a href="#install-in-30-seconds"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/assets/readme/badge-version.svg" alt="1.0.31" /></a>
+<a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/assets/readme/badge-license.svg" alt="MIT license" /></a>
 </p>
 
-<p align="center"><a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/reference.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/assets/readme/lucide-book-open.svg" width="16" alt="" /> Docs</a> &nbsp; <a href="#install-in-30-seconds">Install</a> &nbsp; <a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/assets/cover-motion.webp"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/assets/readme/lucide-play.svg" width="16" alt="" /> Cover motion</a> &nbsp; <a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/assets/readme/lucide-shield-check.svg" width="16" alt="" /> MIT</a></p>
+<p align="center"><a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/reference.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/assets/readme/lucide-book-open.svg" width="16" alt="" /> Docs</a> &nbsp; <a href="#install-in-30-seconds">Install</a> &nbsp; <a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/assets/cover-motion.webp"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/assets/readme/lucide-play.svg" width="16" alt="" /> Cover motion</a> &nbsp; <a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/assets/readme/lucide-shield-check.svg" width="16" alt="" /> MIT</a></p>
 
 Long Grok Build sessions get compacted, a new session starts without what the last one knew, and "done" often just means the model said so. LitGrok gives each session a routine to follow: a written plan before the first edit, checks against that plan, and a handoff file the next session can read. It ships 42 skills, 11 agents, one project rule, and twelve hook registrations. Grok Build still runs the session and chooses the model. It suits work that runs longer than one sitting, such as a feature spread over a few days or a report someone else will read.
 
@@ -24,7 +24,7 @@ You need Node.js and Grok Build. In an interactive terminal, from the project yo
 npm exec --yes --package @litfamily/litgrok@latest -- litgrok install
 ```
 
-The files land in `<project>/.grok/`. Add `--user` to install under `~/.grok/` instead, or use `--package @litfamily/litgrok@1.0.30` to pin this release. Add `--dry-run` to see every destination before anything is written.
+The files land in `<project>/.grok/`. Add `--user` to install under `~/.grok/` instead, or use `--package @litfamily/litgrok@1.0.31` to pin this release. Add `--dry-run` to see every destination before anything is written.
 
 Trying a local package instead? Put its real absolute path in a variable, then run these two lines separately:
 
@@ -73,7 +73,7 @@ Beyond code, `lit-pptx` makes slide decks and `lit-docx` makes reports and Word
 
 ## What changes after install
 
-The installer copies the skills, agents, project rule, and hooks into `.grok/`. The twelve hook registrations in [`hooks/hooks.json`](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/hooks/hooks.json) run only in a trusted Git root, and they log the order of events in `.grok/litgrok/session-ledger/`. Everything runs inside your Grok session, and nothing runs in the background; when the session ends, the work waits for the next one.
+The installer copies the skills, agents, project rule, and hooks into `.grok/`. The twelve hook registrations in [`hooks/hooks.json`](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/hooks/hooks.json) run only in a trusted Git root, and they log the order of events in `.grok/litgrok/session-ledger/`. Everything runs inside your Grok session, and nothing runs in the background; when the session ends, the work waits for the next one.
 
 If you'd like a status row showing the active LitGrok skill, the model and how much context is used, add it with `install --user --status-line`. It writes `[ui.status_line]` into `~/.grok/config.toml` and backs up an existing file first. Once a prompt starts a workflow skill, the row also shows the workflow stage, the tool running now and the last test result. Add `--notify` for Grok's terminal notification when a turn finishes.
 
@@ -112,6 +112,6 @@ If the status row is missing, add it with `install --user --status-line`. Grok r
 
 If LitGrok saves you some re-explaining, a [star on GitHub](https://github.com/wjgoarxiv/litgrok) helps other Grok Build users find it.
 
-[Reference](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/reference.md) · [Changelog](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/CHANGELOG.md) · [Privacy](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/privacy.md) · [MIT license](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/LICENSE) · [Trademark policy](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/TRADEMARK.md)
+[Reference](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/reference.md) · [Changelog](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/CHANGELOG.md) · [Privacy](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/privacy.md) · [MIT license](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/LICENSE) · [Trademark policy](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/TRADEMARK.md)
 
 The cover is brand motion made with the LitFamily motion skill: animated artwork, with no Grok session recorded in it.

package/README_ko-KR.md

@@ -1,18 +1,18 @@
-<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/assets/cover-motion-still.webp" /><source media="(prefers-reduced-motion: no-preference)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/assets/cover-motion.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/assets/cover-motion.webp" width="100%" alt="LitFamily 모션 커버: 일곱 로봇 패널이 차례로 켜지고, LitGrok 로봇의 눈과 테두리가 빛난 뒤 LITFAMILY와 KEEP THE WORK LIT. 문구가 밝아지는 영상" /></picture></p>
+<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/assets/cover-motion-still.webp" /><source media="(prefers-reduced-motion: no-preference)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/assets/cover-motion.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/assets/cover-motion.webp" width="100%" alt="LitFamily 모션 커버: 일곱 로봇 패널이 차례로 켜지고, LitGrok 로봇의 눈과 테두리가 빛난 뒤 LITFAMILY와 KEEP THE WORK LIT. 문구가 밝아지는 영상" /></picture></p>
 
 <h1 align="center">LitGrok</h1>
 <p align="center"><strong>Keep the work lit.</strong></p>
 
 LitGrok은 xAI Grok Build가 코드를 고치기 전에 계획부터 세우고, 만든 결과를 확인하고, 인수인계 문서를 남기게 합니다. 그러면 내일 세션이 오늘 멈춘 자리에서 이어집니다. npm 명령 한 줄이면 스킬과 프로젝트 규칙, 훅이 프로젝트에 들어갑니다.
 
-**[GitHub에서 README 전체 보기](https://github.com/wjgoarxiv/litgrok/blob/main/README_ko-KR.md)** · [안내서](https://github.com/wjgoarxiv/litgrok/blob/main/docs/guide_ko-KR.md) · [전체 스킬](https://github.com/wjgoarxiv/litgrok/blob/main/docs/skills_ko-KR.md) · [English](https://github.com/wjgoarxiv/litgrok#readme) · [설치](#30초-설치) · [상세 안내](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/reference_ko-KR.md)
+**[GitHub에서 README 전체 보기](https://github.com/wjgoarxiv/litgrok/blob/main/README_ko-KR.md)** · [안내서](https://github.com/wjgoarxiv/litgrok/blob/main/docs/guide_ko-KR.md) · [전체 스킬](https://github.com/wjgoarxiv/litgrok/blob/main/docs/skills_ko-KR.md) · [English](https://github.com/wjgoarxiv/litgrok#readme) · [설치](#30초-설치) · [상세 안내](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/reference_ko-KR.md)
 
 <p align="center">
-<a href="#30초-설치"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/assets/readme/badge-version.svg" alt="1.0.30" /></a>
-<a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/assets/readme/badge-license.svg" alt="MIT 라이선스" /></a>
+<a href="#30초-설치"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/assets/readme/badge-version.svg" alt="1.0.31" /></a>
+<a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/assets/readme/badge-license.svg" alt="MIT 라이선스" /></a>
 </p>
 
-<p align="center"><a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/reference_ko-KR.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/assets/readme/lucide-book-open.svg" width="16" alt="" /> 상세 안내</a> &nbsp; <a href="#30초-설치">설치</a> &nbsp; <a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/assets/cover-motion.webp"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/assets/readme/lucide-play.svg" width="16" alt="" /> 커버 모션</a> &nbsp; <a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/assets/readme/lucide-shield-check.svg" width="16" alt="" /> MIT</a></p>
+<p align="center"><a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/reference_ko-KR.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/assets/readme/lucide-book-open.svg" width="16" alt="" /> 상세 안내</a> &nbsp; <a href="#30초-설치">설치</a> &nbsp; <a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/assets/cover-motion.webp"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/assets/readme/lucide-play.svg" width="16" alt="" /> 커버 모션</a> &nbsp; <a href="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/assets/readme/lucide-shield-check.svg" width="16" alt="" /> MIT</a></p>
 
 Grok Build 세션이 길어지면 대화가 압축되고, 새 세션은 앞 세션이 알던 내용을 모른 채 시작하며, "다 됐다"는 말도 모델이 그렇게 말했다는 뜻일 때가 많습니다. LitGrok은 세션마다 따라갈 순서를 줍니다. 첫 수정 전에 계획을 글로 남기고, 그 계획에 비추어 확인하고, 다음 세션이 읽을 인수인계 문서를 남깁니다. 스킬 42개, 에이전트 11개, 프로젝트 규칙 하나, 훅 등록 열두 개가 들어 있고, 세션 실행과 모델 선택은 계속 Grok Build가 맡습니다. 며칠에 걸쳐 만드는 기능이나 다른 사람이 읽을 보고서처럼, 한 번 앉은 자리에서 끝나지 않는 일에 잘 맞습니다.
 
@@ -24,7 +24,7 @@ Node.js와 Grok Build가 있으면 됩니다. 써 보고 싶은 프로젝트에
 npm exec --yes --package @litfamily/litgrok@latest -- litgrok install
 ```
 
-파일은 `<project>/.grok/`에 들어갑니다. `~/.grok/`에 설치하려면 `--user`를, 이 릴리스로 고정하려면 `--package @litfamily/litgrok@1.0.30`을 쓰세요. `--dry-run`을 붙이면 파일을 쓰기 전에 들어갈 경로를 모두 보여 줍니다.
+파일은 `<project>/.grok/`에 들어갑니다. `~/.grok/`에 설치하려면 `--user`를, 이 릴리스로 고정하려면 `--package @litfamily/litgrok@1.0.31`을 쓰세요. `--dry-run`을 붙이면 파일을 쓰기 전에 들어갈 경로를 모두 보여 줍니다.
 
 로컬 패키지로 써 보려면 실제 절대 경로를 변수에 넣고 두 줄을 따로 실행하세요.
 
@@ -73,7 +73,7 @@ npm exec --yes --package "$LITGROK_PACK" -- litgrok install
 
 ## 설치하면 달라지는 것
 
-설치 프로그램이 스킬, 에이전트, 프로젝트 규칙, 훅을 `.grok/`에 복사합니다. [`hooks/hooks.json`](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/hooks/hooks.json)에 있는 훅 등록 열두 개는 신뢰한 Git 루트에서만 동작하고, `.grok/litgrok/session-ledger/`에 이벤트 순서를 남깁니다. 모든 작업은 Grok 세션 안에서 돌고 백그라운드 작업은 없습니다. 세션이 끝나면 다음 세션이 이어받을 때까지 그 자리에 멈춰 있습니다.
+설치 프로그램이 스킬, 에이전트, 프로젝트 규칙, 훅을 `.grok/`에 복사합니다. [`hooks/hooks.json`](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/hooks/hooks.json)에 있는 훅 등록 열두 개는 신뢰한 Git 루트에서만 동작하고, `.grok/litgrok/session-ledger/`에 이벤트 순서를 남깁니다. 모든 작업은 Grok 세션 안에서 돌고 백그라운드 작업은 없습니다. 세션이 끝나면 다음 세션이 이어받을 때까지 그 자리에 멈춰 있습니다.
 
 지금 어떤 LitGrok 스킬이 동작 중인지, 어떤 모델을 쓰는지, 컨텍스트를 얼마나 썼는지 보고 싶으면 `install --user --status-line`으로 상태 행을 켜세요. `~/.grok/config.toml`에 `[ui.status_line]`을 넣고, 파일이 이미 있으면 먼저 백업합니다. 프롬프트가 작업 흐름 스킬을 시작하면 지금 단계, 돌고 있는 도구, 마지막 테스트 결과도 함께 보입니다. 턴이 끝날 때 Grok의 터미널 알림을 받으려면 `--notify`를 붙이세요.
 
@@ -112,6 +112,6 @@ npm exec --yes --package @litfamily/litgrok@latest -- litgrok uninstall --user
 
 LitGrok 덕분에 같은 설명을 덜 반복하게 됐다면, [GitHub 스타](https://github.com/wjgoarxiv/litgrok) 하나가 다른 Grok Build 사용자에게 이 프로젝트를 알리는 데 도움이 됩니다.
 
-[상세 안내](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/reference_ko-KR.md) · [변경 이력](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/CHANGELOG.md) · [개인정보](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/docs/privacy.md) · [MIT 라이선스](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/LICENSE) · [상표 정책](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.30/TRADEMARK.md)
+[상세 안내](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/reference_ko-KR.md) · [변경 이력](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/CHANGELOG.md) · [개인정보](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/docs/privacy.md) · [MIT 라이선스](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/LICENSE) · [상표 정책](https://cdn.jsdelivr.net/npm/@litfamily/litgrok@1.0.31/TRADEMARK.md)
 
 커버의 모션은 LitFamily 모션 스킬로 만든 브랜드 연출입니다. 그려서 움직인 그림이라 실제 Grok 세션을 녹화한 장면은 들어 있지 않습니다.

package/docs/assets/readme/badge-version.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="local: 1.0.30"><title>local: 1.0.30</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="290" transform="scale(.1)">local</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.30</text></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="local: 1.0.31"><title>local: 1.0.31</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="290" transform="scale(.1)">local</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.31</text></g></svg>

package/docs/reference.md

@@ -80,7 +80,7 @@ npm exec --yes --package @litfamily/litgrok@latest -- litgrok install
 Pin a version when you need a reproducible install:
 
 ```bash
-npm exec --yes --package @litfamily/litgrok@1.0.30 -- litgrok install
+npm exec --yes --package @litfamily/litgrok@1.0.31 -- litgrok install
 ```
 
 Preview without writing files:

package/docs/reference_ko-KR.md

@@ -81,7 +81,7 @@ npm exec --yes --package @litfamily/litgrok@latest -- litgrok install
 재현 가능한 설치는 버전을 고정합니다.
 
 ```bash
-npm exec --yes --package @litfamily/litgrok@1.0.30 -- litgrok install
+npm exec --yes --package @litfamily/litgrok@1.0.31 -- litgrok install
 ```
 
 파일을 쓰지 않고 미리보기:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litfamily/litgrok",
-  "version": "1.0.30",
+  "version": "1.0.31",
   "description": "Installer for LitGrok: skills, a project rule and hooks that help xAI Grok Build sessions plan, build, check and hand off their work.",
   "keywords": [
     "grok",

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "litgrok",
-  "version": "1.0.30",
+  "version": "1.0.31",
   "description": "Grok Build skills, project rules, and bounded lifecycle hooks for evidence-first lit work.",
   "author": {
     "name": "LitGrok contributors"