@litfamily/litopencode 1.0.35 → 1.0.37

package/skills/lit-typographic-motion/engine/stage/render.mjs

@@ -450,6 +450,7 @@ export async function renderStage(out, { round = 1, stillsOnly = false } = {}) {
       preview: preview ? { width: preview.width, height: preview.height, fps: preview.fps, bytes: preview.bytes } : null,
       posterFrame, posterSize: [poster.width, poster.height], stillFrame, determinismFrames: samples,
       timing: { ...master.timing, totalSec: Number(((performance.now() - began) / 1000).toFixed(1)) },
+      ...(context.scan.clips.length ? { clips: context.scan.clips.map((clip) => ({ id: clip.id, frames: clip.count, fps: clip.fps, width: clip.width, height: clip.height, bytes: clip.bytes })) } : {}),
       ...(context.plate ? { plate: { blender: context.plate.blender, engine: context.plate.engine, device: context.plate.device, samples: context.plate.samples, fps: context.plate.fps, frames: context.plate.frames.length } } : {}),
       sound, qa: { file: ".run/qa.json", samples: qaResult.samples.length, trackFrames: qaResult.trackFrames, allowedFaces: qaResult.allowedFaces },
       treatmentSha256: sha256(readFileSync(path.join(out, "treatment.json"))), stageSha256: stageSha(context.stageDir),

package/skills/lit-typographic-motion/engine/stage/scan.mjs

@@ -5,6 +5,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import path from "node:path";
+import { decodePng } from "../png.mjs";
 
 export const STAGE_CONTRACT = 17;
 export const STAGE_NETWORK = 19;
@@ -32,6 +33,11 @@ export function readPlate(stageDir, sub = "plate") {
 }
 
 export const rasterLimits = Object.freeze({ files: 24, bytes: 8 * 1024 * 1024, sameSizeFlipbook: 10 });
+// Keyed overlay clips: frame folders that stage/clips/clips.json declares are held to these caps instead of
+// rasterLimits. 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, at most `fps` frames a second.
+export const clipLimits = Object.freeze({ clips: 12, framesPerClip: 360, framesTotal: 1500, bytesPerClip: 40 * 1024 * 1024, bytesTotal: 128 * 1024 * 1024, side: 720, fps: 30 });
+export const clipsDir = "clips";
 // XML namespace identifiers are names, not requests.
 const namespaceUris = /https?:\/\/www\.w3\.org\/(?:2000\/svg|1999\/xlink|1999\/xhtml|XML\/1998\/namespace|2000\/xmlns\/?|1998\/Math\/MathML)/gu;
 
@@ -76,7 +82,7 @@ export function rasterInfo(bytes, ext) {
       if (type === "IDAT" || type === "IEND") break;
       offset += 12 + length;
     }
-    return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20), animated };
+    return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20), animated, bitDepth: bytes[24], colorType: bytes[25] };
   }
   if (ext === ".gif") {
     const width = bytes.readUInt16LE(6), height = bytes.readUInt16LE(8);
@@ -123,10 +129,108 @@ export function rasterInfo(bytes, ext) {
   return null;
 }
 
-// Throws a StageError for the first violation; returns the raster list for pre-decoding.
-export function scanStage(stageDir) {
+// ---- declared clips: stage/clips/clips.json and the frame folders it names ----
+const clipFrame = (n) => `frame_${String(n).padStart(4, "0")}.png`;
+const clipId = /^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$/u;
+const clipFolder = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/u;
+
+// The clips stage/clips/clips.json declares ([] without the file), checked for shape only. Throws exit 17.
+export function declaredClips(stageDir, limits = clipLimits) {
+  const file = path.join(stageDir, clipsDir, "clips.json");
+  if (!existsSync(file)) return [];
+  let doc;
+  try { doc = JSON.parse(readFileSync(file, "utf8")); } catch (error) { throw contract(`${clipsDir}/clips.json is not valid JSON (${error.message})`); }
+  if (!doc || !Array.isArray(doc.clips)) throw contract(`${clipsDir}/clips.json needs { "clips": [ { "id", "dir", "count", "fps" } ] }`);
+  if (doc.clips.length > limits.clips) throw contract(`${doc.clips.length} clips declared (at most ${limits.clips} clips)`);
+  const ids = new Set();
+  const dirs = new Set();
+  return doc.clips.map((entry, n) => {
+    const at = `${clipsDir}/clips.json clip #${n + 1}`;
+    if (!entry || typeof entry !== "object") throw contract(`${at} is not an object`);
+    if (typeof entry.id !== "string" || !clipId.test(entry.id)) throw contract(`${at}: id must be a plain token of letters, digits, - and _ (got ${JSON.stringify(entry.id)})`);
+    if (ids.has(entry.id)) throw contract(`${at}: duplicate id ${entry.id}`);
+    ids.add(entry.id);
+    if (typeof entry.dir !== "string" || !clipFolder.test(entry.dir) || entry.dir.includes("..")) throw contract(`clip "${entry.id}": dir must be a folder name directly under ${clipsDir}/ (got ${JSON.stringify(entry.dir)})`);
+    if (dirs.has(entry.dir)) throw contract(`clip "${entry.id}": dir ${entry.dir} is already declared by another clip`);
+    dirs.add(entry.dir);
+    if (!Number.isInteger(entry.count) || entry.count < 1) throw contract(`clip "${entry.id}": count must be a whole number of frames (got ${JSON.stringify(entry.count)})`);
+    if (!Number.isInteger(entry.fps) || entry.fps < 1 || entry.fps > limits.fps) throw contract(`clip "${entry.id}": fps must be a whole number from 1 to ${limits.fps} (got ${JSON.stringify(entry.fps)})`);
+    return { id: entry.id, dir: entry.dir, count: entry.count, fps: entry.fps };
+  });
+}
+
+// Checks every declared clip against its bytes: exactly frame_0001.png..frame_<count>.png in clips/<dir>/,
+// each an 8-bit still RGBA PNG of one size within the overlay cap, real transparency in the first, middle
+// and last frame, and the per-clip and total caps. Returns [{ id, dir, count, fps, width, height, bytes,
+// frames }], `frames` being stage-relative paths.
+export function scanClips(stageDir, { limits = clipLimits, files = listStage(stageDir) } = {}) {
+  let totalFrames = 0;
+  let totalBytes = 0;
+  const clips = declaredClips(stageDir, limits).map((declared) => {
+    const prefix = `${clipsDir}/${declared.dir}/`;
+    if (declared.count > limits.framesPerClip) throw contract(`clip "${declared.id}": ${declared.count} frames (at most ${limits.framesPerClip} per clip)`);
+    const have = new Set(files.filter((rel) => rel.startsWith(prefix) && rasterExtensions.has(path.extname(rel).toLowerCase())).map((rel) => rel.slice(prefix.length)));
+    const frames = [];
+    for (let n = 1; n <= declared.count; n++) {
+      if (!have.has(clipFrame(n))) throw contract(`clip "${declared.id}": ${prefix}${clipFrame(n)} is missing (declared ${declared.count} frames, named frame_0001.png onward)`);
+      frames.push(`${prefix}${clipFrame(n)}`);
+    }
+    if (have.size !== declared.count) {
+      const stray = [...have].find((name) => !frames.includes(`${prefix}${name}`));
+      throw contract(`clip "${declared.id}": ${prefix}${stray} is not one of the ${declared.count} declared frames; raise count or remove it`);
+    }
+    let size = null;
+    let bytes = 0;
+    for (const rel of frames) {
+      const data = readFileSync(path.join(stageDir, rel));
+      bytes += data.length;
+      const info = path.extname(rel).toLowerCase() === ".png" && data.length > 33 ? rasterInfo(data, ".png") : null;
+      if (!info) throw contract(`clip "${declared.id}": ${rel} is not a readable PNG`);
+      if (info.animated) throw contract(`clip "${declared.id}": ${rel} is an animated image; a clip is a folder of still frames`);
+      if (info.colorType !== 6 || info.bitDepth !== 8) throw contract(`clip "${declared.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 contract(`clip "${declared.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 contract(`clip "${declared.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 };
+    }
+    if (bytes > limits.bytesPerClip) throw contract(`clip "${declared.id}": ${(bytes / 1048576).toFixed(1)} MB (at most ${(limits.bytesPerClip / 1048576).toFixed(0)} MB per clip)`);
+    for (const rel of [frames[0], frames[Math.floor((frames.length - 1) / 2)], frames.at(-1)]) {
+      let pixels;
+      try { ({ pixels } = decodePng(readFileSync(path.join(stageDir, rel)))); } catch (error) { throw contract(`clip "${declared.id}": ${rel} cannot be decoded (${error.message}); use a non-interlaced 8-bit RGBA PNG`); }
+      let transparent = false;
+      for (let i = 3; i < pixels.length && !transparent; i += 4) transparent = pixels[i] < 255;
+      if (!transparent) throw contract(`clip "${declared.id}": ${rel} has no transparent pixel; a clip is keyed, not a full-frame video`);
+    }
+    totalFrames += declared.count;
+    totalBytes += bytes;
+    return { ...declared, ...size, bytes, frames };
+  });
+  if (totalFrames > limits.framesTotal) throw contract(`${totalFrames} clip frames in all (at most ${limits.framesTotal})`);
+  if (totalBytes > limits.bytesTotal) throw contract(`${(totalBytes / 1048576).toFixed(1)} MB of clip frames in all (at most ${(limits.bytesTotal / 1048576).toFixed(0)} MB)`);
+  return clips;
+}
+
+// window.LitClips for LitStage.clip: id -> { src, count, fps, width, height }, written from clips.json and
+// the first frame's header. null when the stage declares no clips (or one the scan would refuse).
+export function clipsScript(stageDir) {
+  let table;
+  try {
+    table = Object.fromEntries(declaredClips(stageDir).map((clip) => {
+      const first = path.join(stageDir, clipsDir, clip.dir, clipFrame(1));
+      const info = rasterInfo(readFileSync(first), ".png");
+      return [clip.id, { src: `${clipsDir}/${clip.dir}`, count: clip.count, fps: clip.fps, width: info.width, height: info.height }];
+    }));
+  } catch { return null; }
+  return Object.keys(table).length ? `window.LitClips = ${JSON.stringify(table)};\n` : null;
+}
+
+// Throws a StageError for the first violation; returns the raster list for pre-decoding and the declared
+// clips, whose frames are not page rasters. `clips: false` (a cover page) ignores clips.json, so a clip
+// folder there is held to the raster limits.
+export function scanStage(stageDir, { clips: allowClips = true } = {}) {
   const files = listStage(stageDir);
   if (!files.includes("index.html")) throw contract("stage/index.html is missing");
+  const clips = allowClips ? scanClips(stageDir, { files }) : [];
+  const clipped = new Set(clips.flatMap((clip) => clip.frames));
   const rasters = [];
   let rasterBytes = 0;
   const plates = ["plate", "plate-preview"].map((sub) => readPlate(stageDir, sub)).filter(Boolean);
@@ -134,7 +238,7 @@ export function scanStage(stageDir) {
   for (const rel of files) {
     const ext = path.extname(rel).toLowerCase();
     const full = path.join(stageDir, rel);
-    if (rel === "scene.py" || plated.has(rel)) continue;
+    if (rel === "scene.py" || plated.has(rel) || clipped.has(rel)) continue;
     if (!Object.hasOwn(contentTypes, ext)) throw contract(`${rel}: ${ext || "extensionless"} files are not served on the stage`);
     if (rasterExtensions.has(ext)) {
       const bytes = readFileSync(full);
@@ -170,7 +274,7 @@ export function scanStage(stageDir) {
   const bySize = new Map();
   for (const raster of rasters) bySize.set(`${raster.width}x${raster.height}`, [...(bySize.get(`${raster.width}x${raster.height}`) ?? []), raster.rel]);
   for (const [size, list] of bySize) if (list.length >= rasterLimits.sameSizeFlipbook) throw contract(`${list.length} rasters share the size ${size} (a flipbook); rasters are textures and stills, never a frame sequence`);
-  return { files, rasters };
+  return { files, rasters, clips };
 }
 
 // One hash over every stage file's name and bytes: a render records it, the done check compares it.

package/skills/lit-typographic-motion/engine/stage/stage-kit.js

@@ -227,7 +227,7 @@
   }
 
   // ---- masks and clips ----
-  const clip = {
+  const clipMasks = {
     // A circle growing from (cx, cy) in percent of the element's box.
     circle(el, p, { cx = 50, cy = 50, max = 150 } = {}) { el.style.clipPath = `circle(${clamp(p) * max}% at ${cx}% ${cy}%)`; },
     // A straight wipe from one side: "left", "right", "top" or "bottom".
@@ -370,6 +370,44 @@
     };
   }
 
+  // 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 <img> inside is replaced on a frame change; the renderer waits for its decode.
+  // The same name carries the clip-path helpers (clip.circle, clip.wipe, clip.iris), so both keep working.
+  function keyedClip({ parent, id, box } = {}) {
+    const all = window.LitClips;
+    if (!all) throw new Error("LitStage.clip: load <script src=\"/lit/clips.js\"></script> after the kit; the stage declares no clips (clips/clips.json)");
+    const c = all[id];
+    if (!c) throw new Error(`LitStage.clip: no clip "${id}" in clips/clips.json (declared: ${Object.keys(all).join(", ")})`);
+    if (!parent || !box || !(box.w > 0) || !(box.h > 0)) throw new Error("LitStage.clip: needs { parent, id, box: { x, y, w, h } }");
+    const wrap = document.createElement("div");
+    wrap.setAttribute("data-lit-clip", id);
+    Object.assign(wrap.style, { position: "absolute", left: `${box.x}px`, top: `${box.y}px`, width: `${box.w}px`, height: `${box.h}px`, display: "none", pointerEvents: "none" });
+    parent.append(wrap);
+    let shown = 0, img = null;
+    return (t, { start = 0, from = 1, to = c.count, loop = false, hold = false } = {}) => {
+      if (!(from >= 1 && to <= c.count && from <= to)) throw new Error(`LitStage.clip: from..to must lie within 1..${c.count} (got ${from}..${to})`);
+      const n = to - from + 1;
+      const k = Math.floor((t - start) * c.fps + 1e-6);
+      const i = k < 0 ? 0 : k < n ? from + k : loop ? from + (k % n) : hold ? to : 0;
+      wrap.style.display = i ? "block" : "none";
+      if (!i) return null;
+      if (i !== shown) {
+        const next = document.createElement("img");
+        next.src = `${c.src}/frame_${String(i).padStart(4, "0")}.png`;
+        next.alt = "";
+        Object.assign(next.style, { display: "block", width: "100%", height: "100%", objectFit: "contain" });
+        if (img) img.replaceWith(next); else wrap.append(next);
+        img = next;
+        shown = i;
+      }
+      return wrap;
+    };
+  }
+  const clip = Object.assign(keyedClip, clipMasks);
+
   // ---- the stage contract ----
   let definition = null;
   function define(spec) {

package/skills/lit-typographic-motion/references/cover.md

@@ -33,7 +33,8 @@ mode (the stage and type paths) is unchanged and takes every other request.
   The renderer serves only that folder, the loop kit at `/lit/loop-kit.js` and the faces at
   `/lit/fonts.css`. The stage path's static scan applies unchanged: no network, no `<video>`,
   `<audio>` or `<iframe>`, no workers, no WebSocket, at most 24 rasters and 8 MB, no animated
-  raster, no flipbook of same-size frames.
+  raster, no flipbook of same-size frames; a cover takes no keyed clips either, so a folder of
+  frames there is a flipbook.
 - `<out>/assets.json`: every raster the page can load (below).
 
 Start from a recipe: copy `recipes/<name>/index.html` from the installed skill into `cover/`, then

package/skills/lit-typographic-motion/references/runtime.md

@@ -39,7 +39,7 @@ warning, and the pre-warm state naming what is missing and the command that fixe
 | 14 | BLOCKED_DEPS_NOT_PREWARMED | the pinned packages are absent (or Tier-3 models are requested) | `litopencode motion-runtime install` outside the session |
 | 15 | BLOCKED_FONT_FETCH | a required font is missing or its bytes do not match the pin | `litopencode motion-runtime install`; a mismatch is never accepted |
 | 16 | BLOCKED_TREATMENT_INVALID | `treatment.json` is missing or a field breaks its rule; the message names the field | fix that field (`treatment.md`) |
-| 17 | STAGE_CONTRACT_ERROR | the stage page broke its contract: no `LitStage.define`, a wrong size, a forbidden element or API, a flipbook or animated raster, a path outside `stage/`, or a copy line never found on screen | fix the page (`stage.md`) |
+| 17 | STAGE_CONTRACT_ERROR | the stage page broke its contract: no `LitStage.define`, a wrong size, a forbidden element or API, a flipbook or animated raster, a keyed clip that breaks its declaration or limits, a path outside `stage/`, or a copy line never found on screen | fix the page (`stage.md`) |
 | 18 | STAGE_NONDETERMINISTIC | a sample frame differs between the master and a fresh replay from 0; the message names the frame and the first region | remove the clock or random source the renderer does not drive |
 | 19 | STAGE_NETWORK_REQUEST | the page requested something outside the stage origin, or a stage file names an external URL | make the asset local |
 | 20 | SOUND_INVALID | the planned track is missing from the film, too long or short, too loud, or a generated bed starts silent; a score that cannot be built | fix the track or its plan |

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

@@ -16,7 +16,7 @@ loop time the renderer seeks in any order, with the loop kit instead of this one
   into the stage directory.
 - Rasters are textures and stills, never a frame sequence: at most 24 raster files and 8 MB in total.
   Ten or more rasters of one size (a flipbook), or any animated GIF, APNG or WebP, stops the render
-  with exit 17.
+  with exit 17. The one frame sequence a page may carry is a declared keyed clip (Clips).
 - `<out>/stage/assets/`: the real logo, screenshots and README images of a named product, written by
   `render.mjs assets` (`treatment.md`, Named products). Show them; never redraw them.
 - A film about a thing with a back and an inside takes the 3D route: the renderer serves a pinned
@@ -76,7 +76,7 @@ unless the film needs another structure.
 
 | Stops with | What |
 | --- | --- |
-| 17 `STAGE_CONTRACT_ERROR` | `<video>`, `<audio>`, `<iframe>`, `<object>`, `<embed>`, `<frame>`; `new Audio()`, `AudioContext`, `OfflineAudioContext`; `Worker`, `SharedWorker`, service workers; no `LitStage.define`; a wrong size; a flipbook or animated raster; a copy line never found on screen |
+| 17 `STAGE_CONTRACT_ERROR` | `<video>`, `<audio>`, `<iframe>`, `<object>`, `<embed>`, `<frame>`; `new Audio()`, `AudioContext`, `OfflineAudioContext`; `Worker`, `SharedWorker`, service workers; no `LitStage.define`; a wrong size; a flipbook or animated raster; a clip that breaks its declaration or limits; a copy line never found on screen |
 | 18 `STAGE_NONDETERMINISTIC` | a frame that differs between two fresh replays: wall-clock reads such as `performance.timeOrigin`, `crypto.getRandomValues`, or state that depends on how fast frames arrive |
 | 19 `STAGE_NETWORK_REQUEST` | any request outside the stage origin; an absolute `http(s)://` or `//host` URL in a stage file (W3C namespace URIs such as `http://www.w3.org/2000/svg` are fine); `preconnect`, `dns-prefetch`, `prefetch` or `prerender` links; `WebSocket`, `WebTransport`, `RTCPeerConnection` |
 
@@ -147,6 +147,52 @@ LitStage.text(signEl, { decor: true });                   // illustrative text i
 LitStage.text({ content: "…", x, y, w, h });              // canvas or WebGL text, every frame it is drawn
 ```
 
+Keyed footage (a declared clip, see Clips): `LitStage.clip` is a function as well as the mask
+namespace above, so `LitStage.clip.wipe(el, p)` and the keyed call live side by side.
+
+```js
+const boom = LitStage.clip({ parent: stageEl, id: "boom", box: { x: 1200, y: 300, w: 520, h: 511 } });
+boom(t, { start: 2.1 });                                   // inside render(t); returns the wrapper, or null while hidden
+```
+
+## Clips
+
+Real keyed footage (a reaction clip, a spinning-cat loop shot on a green screen) joins the film as a
+layer inside the page. The video is keyed outside the renderer into one 8-bit RGBA PNG per frame, the
+frames are declared, and the page picks the frame from film time. A declared clip is exempt from the
+flipbook and count rule; every other raster keeps its limits. Nothing is encoded by hand: the frames
+are captured with the page, so the flash audit, the determinism replay and the text checks run on the
+final pixels as for any other film.
+
+1. Copy each clip's frames into `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` is a folder directly under `clips/`; `count` is the number of
+   frames; `fps` is 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.clip({ parent, id, box })` and calls the returned `show(t, opts)` from `render(t)`.
+   `parent` is the element the clip sits in; `box` is its place in pixels, the frame fitted inside it.
+   `show` returns the wrapper element, or `null` while hidden; scale, fade or move that wrapper from
+   `t` like any other layer. The frame is `floor((t - start) * fps) + 1`, counted from `from`, so the
+   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), `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, more than 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), a rate above 30 fps, frames of mixed sizes, a missing or extra frame, a
+frame that is not an 8-bit RGBA PNG or that has no transparent pixel in its 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. A cover takes no
+clips. The text checks read DOM text, so a clip laid over a line is yours to catch on the stills. The
+manifest and the report list each clip.
+
 ## How the QA reads the stage
 
 - Every `copy.lines` entry must appear on screen at some beat; a missing line stops the render with

package/skills/litgoal/SKILL.md

@@ -128,7 +128,7 @@ litgoal sets and keeps the finish line; lit-loop and start-work run toward it.
 - **Keeps.** The goal survives context loss, compaction, and a new session. Status reads the ledger, not chat memory; an entry is a lead until the evidence is replayed.
 - **Does not run.** litgoal never edits product files and never executes the work. `lit-loop` pursues the criteria turn by turn, and `start-work` executes an approved plan against them under the schema-3 bounded-authority record. Both keep their progress and verification receipts in the same `.litopencode/litgoal` state.
 - **Does not decide completion.** A criterion is met when its evidence is replayed on the real surface, not when a turn says so. `review-work` challenges the claim before it stands.
-- **Is not the host's goal feature.** The verified OpenCode host exposes no native goal primitive, so litgoal is package-owned durable state. See `native-goal-verdict` before promising a host-side objective.
+- **Is not the host's goal feature.** litgoal is package-owned durable state on every host. OpenCode 2.2 and later also has a native `/goal`, which LitOpenCode sets for lit-loop, start-work and litwork and mirrors from this ledger; done needs both. See `native-goal-verdict` before promising a host-side objective.
 
 The route name, the command, and the skill are one word: `litgoal`. `/lit-goal` is the hyphenated alias.
 
@@ -188,7 +188,7 @@ remains denied.
 
 ## Ledger Operating Model
 
-The litgoal skill explains the package-owned state model that LitOpenCode uses when the verified OpenCode host does not expose a native goal primitive. The state root is `.litopencode/litgoal`, and the primary loop ledger is `.litopencode/litgoal/lit-loop/ledger.jsonl`. This path is local workflow state, not package source. It should never be treated as a release payload, a benchmark fixture, or a substitute for current tests. It exists so the loop can survive context loss, command interruption, and cross-session continuation without storing raw secrets or pretending that chat memory is durable.
+The litgoal skill explains the package-owned state model that LitOpenCode uses on every host, including OpenCode 2.2 and later where a native `/goal` also exists and the ledger stays the second half of done. The state root is `.litopencode/litgoal`, and the primary loop ledger is `.litopencode/litgoal/lit-loop/ledger.jsonl`. This path is local workflow state, not package source. It should never be treated as a release payload, a benchmark fixture, or a substitute for current tests. It exists so the loop can survive context loss, command interruption, and cross-session continuation without storing raw secrets or pretending that chat memory is durable.
 
 Each durable event should be understandable as a small fact about the work loop. Good events identify the phase, the goal or slice identifier, the relevant files or commands, the result, and a redacted evidence pointer. Bad events paste raw user data, full command output containing credentials, large source files, private URLs, or unreviewed external text. The ledger is evidence metadata, not a data lake. When in doubt, store a short summary and a path to a local evidence file whose contents were intentionally created for that purpose.
 

package/skills/litwork/SKILL.md

@@ -225,3 +225,7 @@ For any activation change, collect evidence by layer: source registration, runti
 ## Safe Defaults
 
 Default activation should be conservative. It should prefer planning or status over mutation when intent is unclear. It should ask for an approved plan before execution. It should preserve `lit-plan` boundaries even when permission mode is relaxed. It should keep recap read-only. It should avoid writing durable raw arguments. These defaults make accidental activation recoverable.
+
+## Native goal on OpenCode 2
+
+On OpenCode 2.2 and later, a `litwork` request gets a native `/goal` from LitOpenCode itself when the session has none; bare `lit` and the read-only routes do not. LitOpenCode resumes a goal it created only after a server restart, clears it only after OpenCode's verdict and the ledger both say done, and leaves a goal the user made alone. A host without `/goal` records `native-goal-unavailable`. See `native-goal-verdict`.

package/skills/managed-skill-manifest.json

@@ -3389,7 +3389,7 @@
         },
         {
           "path": "engine/cover/render.mjs",
-          "sha256": "8b5cafb3830d6723c882af9ed704e68d8b7ba26fd124f9eff7c8ef9185fc3875"
+          "sha256": "8f819692910d35959aa86b61a271ca6fe4c74547d549a1c8d90da07bdffd62cf"
         },
         {
           "path": "engine/cover/sheet.mjs",
@@ -3477,7 +3477,7 @@
         },
         {
           "path": "engine/stage/capture.mjs",
-          "sha256": "5174a001ed40dcaf9dcfa692feb443f1fad771c942a8b1bd2df5a6b261e071c6"
+          "sha256": "58698c9ecfd1eb789aabc9f166706492b1f1f00e1fa8d09449ea62f479ccd558"
         },
         {
           "path": "engine/stage/clock.js",
@@ -3493,7 +3493,7 @@
         },
         {
           "path": "engine/stage/gate.mjs",
-          "sha256": "f806003a86d8d76c10934f644c8ee596a7b96bfab0ecceed78a71b9017722334"
+          "sha256": "81fa8be4d4ad45fe9b799d5b6765923a0de4fa2507223a9e26faed3420112473"
         },
         {
           "path": "engine/stage/loop-kit.js",
@@ -3509,15 +3509,15 @@
         },
         {
           "path": "engine/stage/render.mjs",
-          "sha256": "e01927e704083babb069e5664307cf179329231996c6ce8614eb80062e4ed6d8"
+          "sha256": "3f47ad9ed8e19763242af0b05359ae09031b76899939e170ef61bddbf9e261cf"
         },
         {
           "path": "engine/stage/scan.mjs",
-          "sha256": "478cd41f852f71a2d8c6ea6e53abcea95c4ca53a13399e0e8faebc89df87e70b"
+          "sha256": "0caaaeebcce7fd3b4d5c3ac5a1bf0f28d07c5c1f82202637a118941b309d3699"
         },
         {
           "path": "engine/stage/stage-kit.js",
-          "sha256": "a38d5c22f2f4148009b0ab89be228833457495565c559d061b36e3d14f694a76"
+          "sha256": "72776c1fd3642c3925da48adbc342234a4e8599e46d49e89962b4d77c7e6a7d2"
         },
         {
           "path": "engine/stills.mjs",
@@ -3741,7 +3741,7 @@
         },
         {
           "path": "references/cover.md",
-          "sha256": "ad7e980530282af2a48cd185d1fbbfecbcb1886377ff08eea16d2458b70fa157"
+          "sha256": "93658c3f3a08b7a9c71443df92db418c6839396a389ac480bd7ccf22faf4eb54"
         },
         {
           "path": "references/craft-loop.md",
@@ -3753,7 +3753,7 @@
         },
         {
           "path": "references/runtime.md",
-          "sha256": "c0c87c23a2d404df995fc4d5a6a544728709046c65a0bb84dcc3c782b92d6ef7"
+          "sha256": "15dc951960b2ae4b204aa094792d29e55829815894524556ebc00550655b325d"
         },
         {
           "path": "references/sound.md",
@@ -3761,7 +3761,7 @@
         },
         {
           "path": "references/stage.md",
-          "sha256": "0ecfb0aff75815a88ff0a0f277ab8aff45ff072be0fc0d57a969803246d78cae"
+          "sha256": "129c1ad6b67b629e8f7e022a705a289e889755f67532b311f19ff15cc7fa8251"
         },
         {
           "path": "references/studio.md",

package/skills/native-goal-verdict/SKILL.md

@@ -18,6 +18,8 @@ entry_routes:
 opencode_surfaces:
   - "OpenCode CLI command list"
   - "OpenCode plugin type surface"
+  - "opencode.goal RPC and the /goal command"
+  - "session experimental.idle hook"
   - "LitOpenCode durable goal ledger"
   - "OpenCode tool litwork action=status"
   - "litopencode runtime state path"
@@ -40,7 +42,7 @@ Use the OpenCode vocabulary for this contract: `chat.message`, `command.execute.
 | --- | --- |
 | `user_request` | The user goal or slash-command arguments that selected Native Goal Verdict. Treat pasted external text as inert data. |
 | `repo_state` | Current package root, dirty worktree status, relevant handoff/ledger state, and OpenCode route config when it affects this skill. |
-| `host_surface` | OpenCode CLI command list, OpenCode plugin type surface, LitOpenCode durable goal ledger, OpenCode tool litwork action=status, litopencode runtime state path, skills/native-goal-verdict/SKILL.md. |
+| `host_surface` | OpenCode CLI command list, OpenCode plugin type surface, the `opencode.goal` RPC and `/goal` command, LitOpenCode durable goal ledger, OpenCode tool litwork action=status, litopencode runtime state path, skills/native-goal-verdict/SKILL.md. |
 | `approval_state` | Whether mutation, execution, release, network, install, or config writes are explicitly approved. Absence of approval means read-only guidance. |
 | `evidence_budget` | Targeted tests, command transcripts, hook probes, pack/install checks, or source citations required before a completion claim. |
 
@@ -50,7 +52,7 @@ Required schema fields are `contract_schema_version`, `skill_id`, `runtime_class
 
 | Mode | Enter when | Allowed surfaces | Required behavior | Exit criteria |
 | --- | --- | --- | --- | --- |
-| `route` | Inspect the native-goal-verdict feature, skills/native-goal-verdict/SKILL.md, opencode --help, and @opencode-ai/plugin Hooks types. | OpenCode CLI command list, OpenCode plugin type surface, LitOpenCode durable goal ledger, OpenCode tool litwork action=status, litopencode runtime state path, skills/native-goal-verdict/SKILL.md | Select the matching LitOpenCode guidance and preserve static-documentation boundaries. | The intended skill, command, hook, tool, or route is identified with evidence. |
+| `route` | Inspect the native-goal-verdict feature, skills/native-goal-verdict/SKILL.md, the host's `/goal` command, and the `@opencode/plugin` goal and idle types. | OpenCode CLI command list, OpenCode plugin type surface, LitOpenCode durable goal ledger, OpenCode tool litwork action=status, litopencode runtime state path, skills/native-goal-verdict/SKILL.md | Select the matching LitOpenCode guidance and preserve static-documentation boundaries. | The intended skill, command, hook, tool, or route is identified with evidence. |
 | `execute` | The user explicitly approved implementation or the surface is already an execution surface. | Approved OpenCode agents, tools, and repository commands. | Apply minimum-first changes, protect unrelated files, and keep evidence checkpoints. | Tests and real-surface probes pass or a precise blocker is reported. |
 | `review` | A DoneClaim, release claim, or completion claim is about to be made. | Review-work, targeted tests, scanners, CLI probes, package checks. | Challenge scope, outputs, evidence, safety, and cleanup. | Findings are resolved or listed as risks/limitations. |
 | `blocked` | Required approval, credentials, host capability, or evidence is missing. | Read-only reporting only. | Stop without inventing success and state the smallest unblocker. | User supplies the missing decision/evidence or scope changes. |
@@ -121,96 +123,68 @@ This is static documentation for LitOpenCode runtime discovery. Do not execute c
 
 ## Verdict
 
-The verified OpenCode host surface does not currently expose a native goal primitive through the local CLI command list or the `@opencode-ai/plugin` Hooks type surface. LitOpenCode must not promise direct native goal binding unless a future OpenCode release exposes that primitive.
+OpenCode 2.2 and later has a native `/goal`; OpenCode 1 and OpenCode 2 builds before 2.2 do not. The goal belongs to a session: a built-in plugin keeps `{ id, objective, status, reason, rounds }` for it, a reviewer decides after each idle turn whether the objective is met, and the user steers it with `/goal <objective> | pause | resume | clear`. A plugin reads the goal through the `opencode.goal` RPC (`get({ sessionID })`) and changes it only by sending the `/goal` command to the session. The record has no owner field.
 
-LitOpenCode therefore treats durable goal state as a package-owned capability under `.litopencode/litgoal`, with activation through `lit`, `litwork`, `start-work`, `review-work`, tools, commands, and plugin hooks.
+LitOpenCode uses that surface in a narrow way. On `lit-loop`, `start-work` and `litwork` it checks the session's goal first and sets one only when none exists. The objective is the work plus the completion conditions: tests pass, a real-surface check ran, temporary files are cleaned up with a receipt, and the ledger marks the goal complete. Read-only routes (`lit-plan`, `lit-research`, `review-work`, `lit-recap`, `lit-adhd`, `lit-brainstorm` and the rest) never set a goal.
 
-## Verification Route
+The ledger under `.litopencode/litgoal` stays the evidence record on every host. A goal counts as done only when OpenCode's verdict and the ledger both say so. When OpenCode says the goal is met while the ledger is still open, LitOpenCode prints a conflict line and does not report done.
 
-- Check `opencode --help` for the current CLI command list.
-- Check the installed `@opencode-ai/plugin` Hooks type for plugin extension points.
-- Run `node --test test/runtime-skills.test.mjs`.
-- Run `node --test test/docs.test.mjs`.
+## What LitOpenCode may and may not touch
 
-## Safety Notes
+- It remembers the goal id it created (ledger event `native-goal.created`) and treats that goal as its own. Any other goal is the user's.
+- Its own goal: it resumes one that the server paused on a restart (at most twice), and clears one after both verdicts agree. A goal paused for any other reason (the user, the round limit, no progress, a blocked reviewer) is reported, never resumed.
+- A user's goal is reported once as `left yours alone` and is never resumed, cleared, paused or overwritten. The `/goal <objective>` command replaces an existing goal without asking, so LitOpenCode reads before every create and treats an unreadable state as a conflict, not as "no goal".
+- Every change prints one line that starts with `LitOpenCode goal:` and is recorded in the ledger (`native-goal.created`, `.resumed`, `.cleared`, `.left-alone`, `.conflict`, `.failed`, `.unavailable`).
+- A failed `/goal` call is recorded and the work continues on the ledger alone.
 
-- Do not infer host goal support from naming similarity alone.
-- Keep the public README aligned with the verified host capability.
-- If native support appears in a future host version, add a new feature binding and a migration note before changing runtime behavior.
+## Hosts without `/goal`
 
-## Why the Verdict Matters
+OpenCode 1 and OpenCode 2 builds without the `opencode.goal` RPC record `native-goal-unavailable` once per session and route, set nothing, and keep today's behaviour. Do not fake a goal, and do not tell the user one exists. The `litgoal` skill and its ledger work the same everywhere.
 
-Goal behavior is central to LitOpenCode’s identity, but the implementation must match the host surface that actually exists. If OpenCode exposes a native goal primitive in a future release, LitOpenCode can consider binding to it. Until then, the package should not promise that `/goal` or any host-owned goal state exists. Overclaiming native support would mislead users, break tests, and make durable state migration unsafe.
+## Verification Route
 
-The current verdict is intentionally conservative: local evidence has not shown a native OpenCode goal primitive through the CLI command list or the `@opencode-ai/plugin` hooks type surface. Therefore LitOpenCode owns its goal state under `.litopencode/litgoal`. This package-owned ledger is not a second-class fallback; it is the verified implementation path for resumable work, evidence checkpoints, and recap continuity.
+- On OpenCode 2, run `opencode2` (it installs beside `opencode`) in a temporary project and watch the `LitOpenCode goal:` lines for `lit-loop`, a user-typed `/goal` first, and `lit plan`.
+- On OpenCode 1, run `lit-loop` in the same project and expect `native-goal-unavailable` in `.litopencode/litgoal/lit-loop/ledger.jsonl`.
+- Run `node --test test/v2-native-goal.test.mjs test/v2-native-goal-wiring.test.mjs test/native-goal-v1.test.mjs`.
+- Run `node --test test/runtime-skills.test.mjs` and `node --test test/docs.test.mjs`.
 
 ## Evidence Standard for Changing the Verdict
 
-Changing the verdict requires current host evidence. Acceptable evidence includes official OpenCode documentation for a goal primitive, local CLI help that lists a goal command or goal API, plugin type definitions that expose goal hooks or goal storage, and working integration tests that prove the behavior. Naming similarity, user memory, old screenshots, or another product’s goal feature are not enough.
-
-The evidence should be captured in tests or docs. If a future OpenCode release adds native goals, add a feature binding, migration docs, runtime tests, and compatibility behavior before changing public claims. The migration should explain what happens to existing `.litopencode/litgoal` state, whether state is copied, read-only migrated, or left as historical evidence, and how users can verify the change.
+The verdict rests on the merged OpenCode sources (the goal plugin, the `Goal` schema and `SessionApi.command`), the published `@opencode/plugin` 2.2.5 types, and a run on a real 2.2.5 host. A later host release changes the details, so record the OpenCode version, the package version and what the RPC returned before changing any claim. Naming similarity, memory, old screenshots or another product's goal feature are not evidence.
 
 ## Package-Owned Ledger Behavior
 
-Because native host support is not verified, LitOpenCode uses package-owned durable state. The state path `.litopencode/litgoal` is local to the project and should stay out of package payload and commits unless a future task explicitly changes that design. Tool and command surfaces such as `lit`, `litwork`, `start-work`, and `review-work` can read or write ledger events through the package’s own implementation. Recap can read ledger state without writing it. Static skills can document the state but do not execute it.
-
-This design keeps behavior testable. Ledger tests can cover JSONL append, recovery, malformed lines, redaction, and status reads. Docs tests can ensure the verdict remains visible. Pack payload tests can ensure local state is excluded. Reviewers can reason about the exact path and event model rather than relying on an unspecified host feature.
+The state path `.litopencode/litgoal` is local to the project and stays out of the package payload and commits. `lit`, `litwork`, `start-work` and `review-work` read and write ledger events through the package's own implementation; recap reads without writing. The ledger tests cover JSONL append, recovery, malformed lines, redaction and status reads, and the native-goal tests cover the ownership records on top of them.
 
 ## Wording Rules
 
-Use precise language: “OpenCode host surface does not currently expose a native goal primitive” and “LitOpenCode uses `.litopencode/litgoal`.” Avoid phrases that imply a hidden binding, such as “uses OpenCode goals internally,” unless future evidence proves it. Avoid promising `/goal` behavior. Avoid saying “native goal support is impossible”; host capabilities can change. The right statement is current, evidence-bound, and revisable.
-
-Public docs should align with this verdict. If README, release checklist, runtime skill docs, and command prompts disagree, users will not know which state is authoritative. When updating one surface, search for related wording and run docs tests. Do not introduce old host terms or sibling product terms while explaining the verdict.
+Say "OpenCode 2.2 and later has a native `/goal`" and "LitOpenCode sets it only for lit-loop, start-work and litwork". Say "OpenCode 1 has none" for older hosts. Do not say LitOpenCode "uses OpenCode goals internally" for read-only routes, do not promise `/goal` on OpenCode 1, and do not describe the ledger as a second-class fallback: it is the second half of "done" on every host.
 
 ## OpenCode Surface Checks
 
-The verification route should inspect the host from two directions. The CLI command list shows what a user can invoke. The plugin hooks type shows what a plugin can observe or extend. Both matter. A CLI command without a plugin API may not support LitOpenCode integration. A type name without a runtime command may not be user-visible. If either surface changes, tests should capture the new supported path.
-
-Be careful with installed versions. A global OpenCode CLI may differ from the package used in local tests. A lockfile may point at one plugin version while the user runtime uses another. Record versions when re-evaluating the verdict. If evidence is ambiguous, keep the conservative ledger path and state uncertainty.
+The goal surface has three parts: the `opencode.goal` RPC to read, the `/goal` command through `session.command` to change, and the `experimental.idle` session hook, which runs when a session finishes its work and is where LitOpenCode checks a finished goal. `@opencode/plugin` 2.2.5 types all three; the older 2.0.x types do not. A global `opencode2` may differ from the version in the lockfile, so record both when re-checking.
 
 ## Review Checklist
 
-- Does the doc say current host surface lacks verified native goal support?
-- Does it name `.litopencode/litgoal` as package-owned state?
-- Does it avoid claiming direct host goal binding?
-- Do tests cover runtime skill visibility and docs wording?
-- Do package guards exclude local ledger state?
-- If future native support is claimed, is there official or local host evidence and a migration plan?
+- Does a user-made goal stay untouched, including on idle?
+- Is a goal created only when none exists, and only on the three routes?
+- Is "done" reported only when OpenCode's verdict and the ledger agree?
+- Does a host without `/goal` record `native-goal-unavailable` and nothing else?
+- Is there a bounded number of resumes, and no resume of a goal the user or the round limit paused?
+- Does every change print one `LitOpenCode goal:` line?
 
 ## Failure Modes
 
-One failure mode is optimistic wording after a host release note mentions goals but before plugin integration is tested. Another is copying goal language from a different product with a different host model. Another is treating durable ledger state as if it were a host feature, which can confuse users about where files live and what gets packed. Another is hiding the verdict in a release note while command prompts still imply native support. The static skill exists to keep the conservative evidence-bound verdict easy to find.
+A create over a goal the user just made (the command overwrites). A resume of a goal the user paused, which fights the user. A clear when only OpenCode's reviewer said done, which hides an open ledger. Repeated notices on every idle turn. A read failure treated as "no goal". Treating `/lit` and `/lit-loop` as different when the installed command files share one body. Each has a test in `test/v2-native-goal.test.mjs` or `test/v2-native-goal-wiring.test.mjs`.
 
 ## Completion Claims Involving Goals
 
-When work touches goal behavior, DoneClaims should say whether the change affected package-owned ledger behavior, host command activation, static docs, or only wording. Include tests such as goal tests, runtime skills tests, docs tests, and pack payload checks when relevant. If no host native goal support was re-verified, do not make new host-goal claims. If local ledger files were created during tests, clean them up or state that they are ignored evidence.
-
-## Migration Thought Experiment
-
-If OpenCode later exposes native goals, do not immediately delete the package ledger. First, design compatibility. Existing projects may have `.litopencode/litgoal` history that powers recap and review. Users may depend on local evidence paths. A migration might read both native and package state, export old events, or keep package state for historical sessions while new sessions use host storage. Each option needs tests, docs, and rollback.
-
-The migration plan should answer: what is the source of truth after upgrade; how are duplicate goals reconciled; how are secrets protected; what happens in older OpenCode versions; how does package payload avoid local state; how does `/lit-recap` read history; and how does `start-work` find approved plans? Until those answers exist, the conservative ledger path remains safer.
+A DoneClaim for goal work says which host it ran on, which routes set a goal, what happened to a user-made goal, and that the ledger and OpenCode's verdict both closed. Include the native-goal tests, the docs and runtime-skills tests, the pack payload check, and a real-surface run. If only OpenCode 1 was available, say the OpenCode 2 path was not exercised.
 
 ## Support Triage
 
-When a user asks “where is my goal,” first clarify whether they mean LitOpenCode durable state or a host feature. Ask for package version, OpenCode version, project root, and whether `.litopencode/litgoal` exists. Do not tell them to run destructive cleanup. If state is missing, check whether they are in a different worktree or package root. If state is malformed, preserve the file before repair. If the user expects host-native behavior, explain the current verdict and package-owned path.
+When someone asks "where is my goal", ask whether they mean OpenCode's `/goal` or LitOpenCode's ledger. `/goal` with no text prints the host goal; `lit adhd` and `litwork action=status` print the ledger. A `LitOpenCode goal: conflict` line means OpenCode and the ledger disagree: finish the ledger criteria, or clear the host goal yourself if the work is abandoned. Do not tell anyone to delete `.litopencode/litgoal`.
 
 ## Documentation Consistency
 
-Every public mention of goal behavior should match three facts: current host native support is not verified; LitOpenCode uses package-owned durable state; future host support would require a tested migration. If one document drifts, update it and run docs tests. Avoid mixing “goal,” “ledger,” and “recap” as if they were the same feature. The ledger stores durable events, recap summarizes evidence, and goal behavior coordinates work.
-
-## Test Ideas for Future Host Changes
-
-If host support appears, add tests that prove both old and new paths. A compatibility test should read an existing `.litopencode/litgoal` fixture and verify it is not lost. A host-integration test should prove the OpenCode goal surface can be detected without guessing. A command test should prove `litwork`, `/start-work`, and `/review-work` use the correct source of truth. A pack test should prove local goal state still does not ship. A docs test should prove wording changed from conservative ledger language to the new verified integration language only after evidence exists.
-
-## User Communication
-
-Users do not need an implementation lecture every time. For normal use, say where state lives and how to inspect it. For capability questions, say the current verdict and evidence. For migration questions, say that package-owned state remains authoritative until a tested migration exists. Avoid blaming the host or promising future behavior. The goal is clear expectations.
-
-## Decision Log Guidance
-
-When re-evaluating native goal support, record the decision like an engineering verdict: date, OpenCode version, package version, CLI evidence, plugin type evidence, tests run, and conclusion. If the conclusion remains “not exposed,” keep runtime behavior unchanged. If the conclusion changes, open a plan for migration rather than mixing discovery and implementation. This avoids accidental drift where one doc claims native support while code still uses the package ledger.
-
-## Compatibility Language
-
-Compatibility docs should say that `.litopencode/litgoal` is stable local state for current LitOpenCode workflows. If future host integration arrives, compatibility will be documented and tested. Do not tell users to delete ledger state to prepare for a hypothetical migration. Do not tell users that host goals and package goals are interchangeable until code proves synchronization or conversion.
+Every public mention of goals matches four facts: OpenCode 2.2 and later has `/goal`; LitOpenCode sets one only for lit-loop, start-work and litwork; a user's goal is never touched; the ledger stays the evidence record and the second half of done. Keep README, `docs/reference.md`, the litgoal and lit-loop skills, the lit-loop activation prompt and the release checklist in step, and run the docs tests after any change.