reelkit-cli 0.5.0 → 0.8.0

package/src/commands/build.ts

@@ -1,17 +1,26 @@
 import { execFile } from "node:child_process";
-import { mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
 import { promisify } from "node:util";
 import type { Ctx, Result } from "../context";
-import type { AssetManifest, ScenePlan } from "../pipeline/schema";
-import { compareFrames, SAMPLE_WIDTH, summariseContinuity, type Boundary } from "../render/continuity";
+import { isVoiceless, type AssetManifest, type ScenePlan } from "../pipeline/schema";
+import { compareAcross, SAMPLE_WIDTH, summariseContinuity, type Boundary } from "../render/continuity";
 import { buildManifest, missingAssets } from "../project/manifest";
+import { readBackground } from "../project/background";
 import { beatReport } from "../project/music";
-import { openProject, type Project } from "../project/project";
+import { FILES, openProject, type Project } from "../project/project";
+import { structureNotes } from "../pipeline/review";
+import type { SearchRecord } from "./assets";
+import { libraryUse, shareAfterRender } from "./components";
 import { mediaUrls, serveDir } from "../project/serve";
+import { contactSheet } from "../render/contact-sheet";
 import { bundleProject, disposeBundle, ensureRenderBrowser, renderStills, renderVideo, writeEntry, type EnsureBrowser } from "../render/render";
+import { MASTER_LUFS, MASTER_TRUE_PEAK_DB, masterLoudness, type Master, type Mastered } from "../render/master";
+import { detailLines, measureSound, soundAdvice, spokenWords, voiceAdvice, type SoundReport, type SpokenWord } from "../project/soundreport";
+import { soundNotes } from "../render/sound-notes";
 import { FILE_NAME, MAIN_FILE, jsxUses, staticCheck, typecheck } from "../render/validate";
 import { loadPlan } from "./plan";
+import { MAX_WORD_FRAMES, usesWordTiming, WORD_FRAME_AFTER, wordCalls, wordErrors, wordTargets } from "../render/word-check";
 
 const exec = promisify(execFile);
 const MEDIA_PATH = /["'`](assets\/[^"'`\s]+\.(?:mp3|wav|m4a|mp4|mov|webm|png|jpe?g|webp|svg|gif))["'`]/g;
@@ -31,6 +40,13 @@ function inspect(project: Project): { errors: string[]; manifest?: AssetManifest
       if (!project.exists(m[1])) errors.push(`${name} uses "${m[1]}", which is not in this project. Get it with \`reelkit assets pull <id>\` first.`);
     }
   }
+  // A word given to wordFrame, onWord or onWordBeat that its scene never says would stop the render, so it is an error here.
+  if (!isVoiceless(plan)) {
+    const ids = plan.scenes.map((s) => s.id);
+    for (const name of names.filter((n) => FILE_NAME.test(n))) {
+      errors.push(...wordErrors(name, wordCalls(readFileSync(project.path(join("src", name)), "utf8"), ids, name), plan.scenes));
+    }
+  }
   if (errors.length) return { errors };
   const typeErrors = typecheck(names.map((n) => project.path(join("src", n))));
   if (typeErrors.length) return { errors: typeErrors };
@@ -39,13 +55,44 @@ function inspect(project: Project): { errors: string[]; manifest?: AssetManifest
 }
 
 // Advice about a composition that passes: never an error.
-function compositionNotes(project: Project, plan: ScenePlan): string[] {
+function compositionNotes(project: Project, plan: ScenePlan, manifest?: AssetManifest): string[] {
   const notes: string[] = [];
   const names = readdirSync(project.path("src")).filter((f) => FILE_NAME.test(f));
   const sources = names.map((n) => [n, readFileSync(project.path(join("src", n)), "utf8")] as const);
   const rendersCaptions = sources.some(([n, src]) => jsxUses(src, n, "Captions").length > 0);
   if (plan.captions === "none" && rendersCaptions) notes.push('The plan says captions: "none" but the composition renders <Captions>. Remove them, or change the plan if the user wants captions.');
   if ((plan.captions === "word" || plan.captions === "phrase") && !rendersCaptions) notes.push(`The plan asks for captions (${plan.captions}) but the composition renders no <Captions>. Add <Captions words={s.words} group={manifest.captions} /> in each scene, or set captions to "none" in the plan if the user does not want them.`);
+  if (!isVoiceless(plan) && !sources.some(([n, src]) => usesWordTiming(src, n))) {
+    notes.push("Nothing on screen is timed to a spoken word: the composition never uses wordFrame, onWord, onWordBeat or a scene's words (other than to draw the subtitles). Place what illustrates a word on that word, e.g. <Entrance delay={onWord(s, \"tasks\")}>; see reference/voice-sync.md.");
+  }
+  notes.push(...structureNotes(plan, { footage: project.footage() }));
+  if (isVoiceless(plan) && manifest) {
+    notes.push(...soundNotes(sources.map(([name, source]) => ({ name, source })), { seconds: manifest.totalFrames / manifest.fps, fps: manifest.fps, musicSet: manifest.music !== undefined }));
+  }
+  // A ground that was chosen and then never drawn is wasted: say so. A video ground with a low dim under type is hard to read.
+  const bg = readBackground(project);
+  const recorded = [...(bg.film ? [bg.film.key] : []), ...Object.values(bg.scenes).map((e) => e.key)];
+  const usesBackground = (src: string) => /\.background\b|bgPerScene/.test(src) || recorded.some((k) => src.includes(k));
+  if (recorded.length && !sources.some(([, src]) => usesBackground(src))) notes.push(`A background is recorded (${recorded[0]}) but the composition never uses it. Draw it with <BgVideo> or <BgImage> from manifest.background, or <BgSequence items={bgPerScene(...)}>; see reference/backgrounds.md.`);
+  if (plan.scenes.some((s) => s.onScreenText.length)) {
+    for (const [name, src] of sources) {
+      const lowDim = jsxUses(src, name, "BgVideo").some((u) => { const m = /\bdim=\{\s*(\d*\.?\d+)\s*\}/.exec(u.example); return m !== null && Number(m[1]) < 0.2; });
+      if (lowDim) { notes.push(`${name}: a BgVideo with a dim under 0.2 sits behind on-screen text, which will be hard to read. Raise dim to 0.3 or more, or blur the clip.`); break; }
+    }
+  }
+  // An image scene with words on it is built in layers. Decidable only when the composition names one of the two components, or names the scene's image (its key, or
+  // imageKey): a composition that never mentions the picture says nothing here.
+  const images = project.readJsonOr<Record<string, string>>(FILES.images, {});
+  const layered = sources.some(([n, src]) => jsxUses(src, n, "ImageLayers").length > 0 || jsxUses(src, n, "TextOnImage").length > 0);
+  const withText = plan.scenes.filter((sc) => sc.treatment === "illustration" && sc.onScreenText.length > 0 && images[sc.id]);
+  if (!layered && withText.length && sources.some(([, src]) => /\bimageKey\b/.test(src) || withText.some((sc) => src.includes(images[sc.id]!)))) {
+    notes.push(`Scene ${withText.map((sc) => sc.id).join(", ")} ${withText.length === 1 ? "has" : "have"} an image and on-screen text, but the composition uses neither <ImageLayers> nor <TextOnImage>: the text is not a layer of the picture. Put the words in the picture's calm zone with <TextOnImage layers={s.imageLayers}> inside <ImageLayers layers={s.imageLayers}> (run \`reelkit assets layers --scene <id>\` for a hero picture so the words can pass behind its subject), not on a flat card beside it.`);
+  }
+  const { pulled, written } = libraryUse(project);
+  if (!pulled.length && plan.scenes.length >= 4) {
+    const searched = project.readJsonOr<SearchRecord[]>(FILES.searches, []).filter((s) => s.kind === "component").length;
+    notes.push(`No library component is used (${searched === 0 ? "no component search was made" : `${searched} component search${searched === 1 ? "" : "es"} made`} in this project). Search before writing: \`reelkit assets search "<what the scene shows>" --kind component\`.`);
+  }
   return notes;
 }
 
@@ -53,11 +100,11 @@ const failed = (errors: string[]): Result => ({ ok: false, data: { errors }, sum
 
 export async function check(ctx: Ctx): Promise<Result> {
   const project = openProject(ctx.cwd);
-  const { errors } = inspect(project);
+  const { errors, manifest } = inspect(project);
   if (errors.length) return failed(errors);
-  const shouldImprove = compositionNotes(project, loadPlan(project));
+  const shouldImprove = compositionNotes(project, loadPlan(project), manifest);
   return {
-    ok: true, data: { errors: [], shouldImprove },
+    ok: true, data: { errors: [], shouldImprove, library: libraryUse(project) },
     summary: ["The composition passes. Run `reelkit preview` to see it.", ...(shouldImprove.length ? [`Worth improving:\n- ${shouldImprove.join("\n- ")}`] : [])].join("\n"),
   };
 }
@@ -92,33 +139,54 @@ export async function ensureBrowserWithNotice(ctx: Ctx, ensure: EnsureBrowser =
 const ffmpegToJpeg = (png: string, jpg: string) => exec("ffmpeg", ["-y", "-loglevel", "error", "-i", png, "-vf", "scale=540:-2", "-q:v", "5", jpg]).then(() => undefined);
 
 type PreviewPoint = { sceneId: string; point: "early" | "late" | "middle" | "end" | "start"; frame: number; name: string };
+type WordFrameFile = { sceneId: string; word: string; label: string; frame: number; wordStart: number; name: string };
+
+// Whether any file of the composition draws a Scene3D, which is the only case that needs the software GL in the browser.
+export const usesScene3D = (project: Project): boolean => readdirSync(project.path("src")).filter((f) => f.endsWith(".tsx")).some((n) => /<Scene3D[\s>/]/.test(readFileSync(project.path(join("src", n)), "utf8")));
+
+// How many frames at each end of a scene SceneFrame may be fading or moving: 8 unless the composition asks for longer with a literal
+// transitionFrames={N} (at most 20, as SceneFrame allows). A value that is not a literal cannot be read, so the default is used.
+export const DEFAULT_FADE = 8;
+export function fadeFrames(sources: string[]): number {
+  let n = DEFAULT_FADE;
+  for (const src of sources) for (const m of src.matchAll(/transitionFrames=\{\s*(\d+)\s*\}/g)) n = Math.max(n, Math.min(20, Number(m[1])));
+  return n;
+}
 
-// Two frames per scene, at 30% and 90% of its length, so what enters late in a scene is seen as well as what opens it.
-// A scene under 4 frames has no room for two distinct frames and gets its middle one. The scene's number leads each name
-// so the files sort by scene order and then by time, whatever the scene ids are.
-export function previewPoints(scenes: { id: string; startFrame: number; durationFrames: number }[]): PreviewPoint[] {
+// The frames of a scene, counted from its start, where it is fully visible: SceneFrame fades or moves it at both ends for up to `fade` frames,
+// but never more than half its length.
+const visibleRange = (d: number, fade: number) => { const edge = Math.max(1, Math.min(fade, Math.floor(d / 2))); return { lo: edge, hi: d - edge, edge }; };
+
+// Two frames per scene, at 30% and 90% of its length, so what enters late in a scene is seen as well as what opens it, both moved into the
+// part where the scene is fully visible (a quick scene's 90% falls inside its fade and would look dim). A scene too short to have two distinct
+// fully visible frames gets its middle one. The scene's number leads each name so the files sort by scene order and then by time.
+export function previewPoints(scenes: { id: string; startFrame: number; durationFrames: number }[], fade = DEFAULT_FADE): PreviewPoint[] {
   return scenes.flatMap((s, i) => {
     const at = (point: PreviewPoint["point"], offset: number): PreviewPoint => ({ sceneId: s.id, point, frame: s.startFrame + offset, name: `${String(i + 1).padStart(2, "0")}-${s.id}-${point}` });
-    if (s.durationFrames < 4) return [at("middle", Math.floor(s.durationFrames / 2))];
-    const inside = (share: number) => Math.min(s.durationFrames - 1, Math.round(s.durationFrames * share));
+    const { lo, hi } = visibleRange(s.durationFrames, fade);
+    if (s.durationFrames < 4 || hi - lo < 2) return [at("middle", Math.floor(s.durationFrames / 2))];
+    const inside = (share: number) => Math.max(lo, Math.min(hi, Math.round(s.durationFrames * share)));
     return [at("early", inside(0.3)), at("late", inside(0.9))];
   });
 }
 
-type BoundaryPoint = { from: string; to: string; end: PreviewPoint; start: PreviewPoint };
+type BoundaryPoint = { from: string; to: string; end: PreviewPoint; start: PreviewPoint; settled: PreviewPoint };
 
-// SceneFrame fades each scene in and out over up to 8 frames, so the very last and very first frames of two scenes are nearly empty.
-// The frames that show what a scene really holds are the last one at full strength and the first one at full strength: those are the two
-// either side of every change. The files are named by the change, b01-end-<scene> then b01-start-<scene>, so that they sort in order.
-export function boundaryPoints(scenes: { id: string; startFrame: number; durationFrames: number }[]): BoundaryPoint[] {
-  const edge = (d: number) => Math.max(1, Math.min(8, Math.floor(d / 2)));
+// SceneFrame fades or moves each scene in and out, so the very last and very first frames of two scenes are nearly empty. The frames that show
+// what a scene really holds are the last one at full strength and the first one at full strength. A third frame, six frames after the first,
+// catches a move that is still settling; it is measured but not saved. The files are named by the change, b01-end-<scene> then b01-start-<scene>.
+export function boundaryPoints(scenes: { id: string; startFrame: number; durationFrames: number }[], fade = DEFAULT_FADE): BoundaryPoint[] {
   return scenes.slice(0, -1).map((a, i) => {
     const b = scenes[i + 1]!;
     const n = `b${String(i + 1).padStart(2, "0")}`;
+    const ea = visibleRange(a.durationFrames, fade), eb = visibleRange(b.durationFrames, fade);
+    const startOffset = Math.min(b.durationFrames - 1, eb.edge);
+    const settledOffset = Math.min(b.durationFrames - 1, Math.max(startOffset, Math.min(startOffset + 6, eb.hi)));
     return {
       from: a.id, to: b.id,
-      end: { sceneId: a.id, point: "end", frame: a.startFrame + Math.max(0, a.durationFrames - edge(a.durationFrames)), name: `${n}-end-${a.id}` },
-      start: { sceneId: b.id, point: "start", frame: b.startFrame + Math.min(b.durationFrames - 1, edge(b.durationFrames)), name: `${n}-start-${b.id}` },
+      end: { sceneId: a.id, point: "end", frame: a.startFrame + Math.max(0, ea.hi), name: `${n}-end-${a.id}` },
+      start: { sceneId: b.id, point: "start", frame: b.startFrame + startOffset, name: `${n}-start-${b.id}` },
+      settled: { sceneId: b.id, point: "start", frame: b.startFrame + settledOffset, name: `${n}-settled-${b.id}` },
     };
   });
 }
@@ -137,17 +205,25 @@ export async function preview(ctx: Ctx, deps: { toJpeg?: (png: string, jpg: stri
   const dir = project.path("out/preview");
   rmSync(dir, { recursive: true, force: true });
   mkdirSync(dir, { recursive: true });
-  const sceneFrames = previewPoints(manifest.scenes);
-  const boundaries = boundaryPoints(manifest.scenes);
+  const plan = loadPlan(project);
+  const intended = new Set(plan.scenes.filter((s) => s.cutIn).map((s) => s.id));
+  const fade = fadeFrames(readdirSync(project.path("src")).filter((f) => f.endsWith(".tsx")).map((n) => readFileSync(project.path(join("src", n)), "utf8")));
+  const sceneFrames = previewPoints(manifest.scenes, fade);
+  const boundaries = boundaryPoints(manifest.scenes, fade);
   const points = [...sceneFrames, ...boundaries.flatMap((b) => [b.end, b.start])];
+  // A narrated film also gets one frame just after each word its code times something to: the thing the word names should already be there.
+  const srcNames = readdirSync(project.path("src")).filter((f) => FILE_NAME.test(f));
+  const wordPlan = isVoiceless(plan) ? undefined : wordTargets(srcNames.flatMap((n) => wordCalls(readFileSync(project.path(join("src", n)), "utf8"), plan.scenes.map((sc) => sc.id), n)), manifest);
+  const wordFiles: WordFrameFile[] = (wordPlan?.targets ?? []).map((t, i) => ({ ...t, name: `w${String(i + 1).padStart(2, "0")}-${t.sceneId}-${t.word.toLowerCase().replace(/[^a-z0-9]+/g, "") || "word"}` }));
+  const measuredFrames = [...points.map((p) => p.frame), ...boundaries.map((b) => b.settled.frame), ...wordFiles.map((w) => w.frame)];
   try {
     try {
       await ensureBrowserWithNotice(ctx, deps.ensureBrowser);
-      await withBundle(project, (serveUrl, urls) => renderStills(serveUrl, { manifest, urls }, [...new Set(points.map((p) => p.frame))], dir));
+      await withBundle(project, (serveUrl, urls) => renderStills(serveUrl, { manifest, urls }, [...new Set(measuredFrames)], dir, { uses3D: usesScene3D(project) }));
     } catch (e) {
       return failed([`Render failed: ${e instanceof Error ? e.message : String(e)}`]);
     }
-    const frames: { sceneId: string; point: PreviewPoint["point"]; path: string }[] = [];
+    const frames: { sceneId: string; point: PreviewPoint["point"] | "word"; path: string; word?: string; label?: string }[] = [];
     try {
       for (const m of points) {
         // Shrunk to phone width: small enough to read cheaply, and what is unreadable here is unreadable on a phone.
@@ -155,9 +231,23 @@ export async function preview(ctx: Ctx, deps: { toJpeg?: (png: string, jpg: stri
         await toJpeg(join(dir, `still-${m.frame}.png`), project.path(path));
         frames.push({ sceneId: m.sceneId, point: m.point, path });
       }
+      for (const w of wordFiles) {
+        const path = `out/preview/${w.name}.jpg`;
+        await toJpeg(join(dir, `still-${w.frame}.png`), project.path(path));
+        frames.push({ sceneId: w.sceneId, point: "word", path, word: w.word, label: w.label });
+      }
     } catch {
       return failed(["Could not write the preview frames: ffmpeg failed. Check that ffmpeg is installed (macOS: `brew install ffmpeg`) and run `reelkit preview` again."]);
     }
+    // One picture of all the frames, so that a look at it comes before opening single frames. It is a convenience: failing to make it changes nothing else.
+    let sheetLine = "";
+    let sheet: { path: string; cols: number; rows: number } | undefined;
+    try {
+      const names = frames.map((f) => (f.point === "word" ? f.label! : `${f.sceneId} ${f.point === "early" || f.point === "late" || f.point === "middle" ? f.point : `change ${f.point}`}`));
+      const r = await contactSheet(frames.map((f) => project.path(f.path)), names, project.path("out/preview/sheet.jpg"), manifest.width / manifest.height, { newRowAt: wordFiles.length ? points.length : undefined });
+      sheet = { path: "out/preview/sheet.jpg", cols: r.cols, rows: r.rows };
+      sheetLine = `Contact sheet, one picture of all ${frames.length} frames in the order below${r.labelled ? ", each labelled with its scene and early, late or change" : ""} (${r.cols} across${wordFiles.length ? `; the word frames are in the last row${r.labelled ? ", labelled word > scene" : ""}` : ""}): out/preview/sheet.jpg. Look at it first, then open single frames where something needs a closer look.\n`;
+    } catch { /* no sheet */ }
     // Whether anything survives each scene change is advice. If it cannot be measured, the preview is still the preview.
     let continuity: { score: number | null; boundaries: Boundary[] } | undefined;
     let continuityLines: string[] = [];
@@ -165,9 +255,9 @@ export async function preview(ctx: Ctx, deps: { toJpeg?: (png: string, jpg: stri
       const h = Math.round((SAMPLE_WIDTH * manifest.height) / manifest.width);
       const measured: Boundary[] = [];
       for (const b of boundaries) {
-        const [a, c] = await Promise.all([decodeGray(join(dir, `still-${b.end.frame}.png`), SAMPLE_WIDTH, h), decodeGray(join(dir, `still-${b.start.frame}.png`), SAMPLE_WIDTH, h)]);
-        const r = compareFrames(a, c, SAMPLE_WIDTH, h);
-        measured.push({ from: b.from, to: b.to, survived: Math.round(r.survived * 100) / 100, kind: r.kind });
+        const [a, c, d] = await Promise.all([b.end.frame, b.start.frame, b.settled.frame].map((f) => decodeGray(join(dir, `still-${f}.png`), SAMPLE_WIDTH, h)));
+        const r = compareAcross(a!, [c!, d!], SAMPLE_WIDTH, h);
+        measured.push({ from: b.from, to: b.to, survived: Math.round(r.survived * 100) / 100, kind: intended.has(b.to) && r.kind !== "empty" ? "cut (intended)" : r.kind });
       }
       if (measured.length) {
         const summary = summariseContinuity(measured);
@@ -175,27 +265,73 @@ export async function preview(ctx: Ctx, deps: { toJpeg?: (png: string, jpg: stri
         continuityLines = summary.lines;
       }
     } catch { /* no continuity report */ }
-    const sceneLines = `Two frames per scene, at 30% and at 90% of its length (a scene under 4 frames gets its middle one). Look at both frames of every scene:\n${frames.filter((f) => f.point !== "end" && f.point !== "start").map((f) => `${f.sceneId} (${f.point}): ${f.path}`).join("\n")}`;
+    const wordLines = wordPlan && (wordFiles.length || wordPlan.skipped)
+      ? `\nWord frames: ${wordFiles.length} frame${wordFiles.length === 1 ? "" : "s"}, each ${WORD_FRAME_AFTER} frames AFTER its word starts, in a row of their own on the sheet (labelled "word ▸ scene"). Each word frame should already show the thing that word names: if it does not, the thing is late (or on the wrong word) and its timing needs fixing.${wordFiles.length ? `\n${wordFiles.map((w) => `${w.label}: out/preview/${w.name}.jpg`).join("\n")}` : ""}${wordPlan.skipped ? `\n${wordPlan.skipped} word timing${wordPlan.skipped === 1 ? " was" : "s were"} not shown (${[wordPlan.undecidable ? `${wordPlan.undecidable} name${wordPlan.undecidable === 1 ? "s" : ""} a word or a scene the code does not give as a literal` : "", wordPlan.capped ? `${wordPlan.capped} beyond the first ${MAX_WORD_FRAMES}` : ""].filter(Boolean).join(", ")}).` : ""}`
+      : wordPlan ? "\nWord frames: none, because the composition has no wordFrame, onWord or onWordBeat call with a literal scene and word." : "";
+    const sceneLines = `Two frames per scene, at 30% and at 90% of its length (a scene under 4 frames gets its middle one). Look at both frames of every scene:\n${frames.filter((f) => f.point !== "end" && f.point !== "start" && f.point !== "word").map((f) => `${f.sceneId} (${f.point}): ${f.path}`).join("\n")}`;
     const changeLines = boundaries.length ? `\nThe last and first frames either side of each scene change are saved too (b01-end-<scene>, b01-start-<scene>, ...), so that you can see what carries across:\n${frames.filter((f) => f.point === "end" || f.point === "start").map((f) => `${f.sceneId} (${f.point}): ${f.path}`).join("\n")}` : "";
-    const beat = beatReport(manifest);
-    return { ok: true, data: { frames, ...(continuity ? { continuity } : {}), ...(beat ? { beat: { bpm: beat.bpm, boundariesOnBeat: beat.boundariesOnBeat, boundaries: beat.boundaries } } : {}) }, summary: `${sceneLines}${changeLines}${continuityLines.length ? `\nContinuity: ${continuityLines.join("\n")}` : ""}${beat ? `\nBeat: ${beat.line}.` : ""}` };
+    const beat = beatReport(manifest, { finer: isVoiceless(plan) });
+    return { ok: true, data: { frames, ...(wordPlan ? { wordFrames: { shown: wordFiles.map((w) => ({ scene: w.sceneId, word: w.word, wordStart: w.wordStart, frame: w.frame })), skipped: wordPlan.skipped } } : {}), ...(sheet ? { sheet } : {}), ...(continuity ? { continuity } : {}), ...(beat ? { beat: { bpm: beat.bpm, boundariesOnBeat: beat.boundariesOnBeat, boundaries: beat.boundaries } } : {}) }, summary: `${sheetLine}${sceneLines}${changeLines}${wordLines}${continuityLines.length ? `\nContinuity: ${continuityLines.join("\n")}` : ""}${beat ? `\nBeat: ${beat.line}.` : ""}` };
   } finally {
     // The full-size stills are only inputs; none stays behind however this ends.
     for (const f of readdirSync(dir)) if (/^still-\d+\.png$/.test(f)) rmSync(join(dir, f), { force: true });
   }
 }
 
-export async function render(ctx: Ctx, deps: { ensureBrowser?: EnsureBrowser } = {}): Promise<Result> {
+export async function render(ctx: Ctx, deps: { ensureBrowser?: EnsureBrowser; master?: Master; noShare?: boolean; measure?: (path: string, loudness?: number, words?: SpokenWord[]) => Promise<SoundReport> } = {}): Promise<Result> {
   const project = openProject(ctx.cwd);
   const { errors, manifest } = inspect(project);
   if (!manifest) return failed(errors);
   const path = "out/video.mp4";
   try {
     await ensureBrowserWithNotice(ctx, deps.ensureBrowser);
-    await withBundle(project, (serveUrl, urls) => renderVideo(serveUrl, { manifest, urls }, project.path(path)));
+    await withBundle(project, (serveUrl, urls) => renderVideo(serveUrl, { manifest, urls }, project.path(path), { uses3D: usesScene3D(project) }));
   } catch (e) {
     return failed([`Render failed: ${e instanceof Error ? e.message : String(e)}`]);
   }
   const seconds = manifest.totalFrames / manifest.fps;
-  return { ok: true, data: { path, seconds }, summary: `Video: ${project.path(path)} (${seconds.toFixed(1)}s, ${manifest.width}x${manifest.height})` };
+  // One last pass brings the whole programme to the loudness platforms play at. If it fails the render is still the render.
+  let loudness: Mastered | undefined;
+  let masterNote = "";
+  try {
+    loudness = await (deps.master ?? masterLoudness)(project.path(path));
+    masterNote = ` Mastered to ${loudness.outputLufs} LUFS (it was ${loudness.inputLufs}), peaks under ${MASTER_TRUE_PEAK_DB} dBTP.`;
+  } catch (e) {
+    masterNote = ` It was not mastered to ${MASTER_LUFS} LUFS (${e instanceof Error ? e.message : String(e)}); the video is kept as rendered.`;
+  }
+  // How the finished film sounds against what it shows. It is advice, so a measurement that fails leaves the render as it was.
+  let sound: SoundReport | undefined;
+  let soundLine: string | undefined;
+  try {
+    const voiceless = isVoiceless(loadPlan(project));
+    sound = await (deps.measure ?? measureSound)(project.path(path), loudness?.outputLufs, voiceless ? undefined : spokenWords(manifest));
+    if (voiceless) soundLine = soundAdvice(sound);
+    else if (sound.voice) soundLine = voiceAdvice(sound.voice);
+  } catch { sound = undefined; }
+  const share = await shareAfterRender(ctx, project, { noShare: deps.noShare });
+  return {
+    ok: true, data: { path, seconds, ...(loudness ? { loudness } : {}),
+      ...(sound ? { sound: { hitsPerSecond: sound.hitsPerSecond, swellsPerSecond: sound.swellsPerSecond, pictureChanges: sound.pictureChanges, changesWithHit: sound.changesWithHit, firstSoundSec: sound.firstSoundSec }, ...(sound.voice ? { voice: sound.voice } : {}) } : {}), ...(share.data ? { shared: share.data.shared.map((s) => s.name) } : {}) },
+    summary: [`Video: ${project.path(path)} (${seconds.toFixed(1)}s, ${manifest.width}x${manifest.height}).${masterNote}`, ...(soundLine ? [soundLine] : []), ...share.lines].join("\n"),
+  };
+}
+
+// `reelkit sound [file]`: the same measurement on any film, by default the last render. `--detail` lists every picture change with its nearest hit, every swell and the first sound.
+export async function soundCommand(ctx: Ctx, file?: string, opts: { detail?: boolean } = {}, deps: { measure?: (path: string, loudness?: number, words?: SpokenWord[]) => Promise<SoundReport> } = {}): Promise<Result> {
+  let project: Project | undefined;
+  try { project = openProject(ctx.cwd); } catch { project = undefined; }
+  const path = file ? resolve(ctx.cwd, file) : project ? project.path("out/video.mp4") : resolve(ctx.cwd, "out/video.mp4");
+  if (!existsSync(path)) return { ok: false, summary: `${file ?? "out/video.mp4"} does not exist. ${file ? "Check the path." : "Run `reelkit render` first, or give the file."}` };
+  let narrated = false;
+  try { narrated = project ? !isVoiceless(loadPlan(project)) : false; } catch { narrated = false; }
+  // A narrated film is also measured against its words: the manifest has their times.
+  let words: SpokenWord[] | undefined;
+  if (narrated && project?.exists(FILES.manifest) && (!file || resolve(ctx.cwd, file) === resolve(project.path("out/video.mp4")))) { try { words = spokenWords(project.readJson<AssetManifest>(FILES.manifest)); } catch { words = undefined; } }
+  let report: SoundReport;
+  try { report = await (deps.measure ?? measureSound)(path, undefined, words); } catch (e) { return { ok: false, summary: `Could not measure the sound: ${e instanceof Error ? e.message : String(e)}` }; }
+  const numbers = `${report.hitsPerSecond} hits a second, ${report.swellsPerSecond} swells a second, ${report.changesWithHit} of ${report.pictureChanges} picture changes with a hit within 0.1s, first sound at ${report.firstSoundSec ?? "never"}s${report.loudnessLufs !== undefined ? `, ${report.loudnessLufs} LUFS` : ""}.`;
+  const { detail, ...counts } = report;
+  const body = narrated ? `${numbers}${report.voice ? `\n${voiceAdvice(report.voice)}` : ""}` : `${soundAdvice(report)}\n${numbers}`;
+  if (opts.detail && detail) return { ok: true, data: { path, ...counts, detail }, summary: `${body}\n${detailLines(detail).join("\n")}` };
+  return { ok: true, data: { path, ...counts }, summary: `${body}\nRun with --detail to see each event.` };
 }

package/src/commands/components.ts

@@ -0,0 +1,220 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import ts from "typescript";
+import { uploadTo } from "../api/client";
+import { client, type Ctx, type Result } from "../context";
+import { MAX_COMPONENT_BYTES, MAX_COMPONENT_EXAMPLE, MIN_COMPONENT_DESCRIPTION } from "../contract";
+import { configDir, loadCredentials } from "../credentials";
+import { FILES, openProject, type Project } from "../project/project";
+import { componentName, FILE_NAME, jsxUses, MAIN_FILE, staticCheck } from "../render/validate";
+
+export type SharedRecord = { name: string; libraryId: string; hash: string };
+type Prepared = { name: string; file: string; source: string; hash: string; description: string; example: string; tags: string[] };
+export type ShareOutcome = { shared: { name: string; libraryId: string; file: string; description: string; example: string }[]; skipped: { name: string; reason: string }[]; failed?: string };
+
+const STOP_WORDS = new Set(["that", "this", "with", "from", "when", "have", "your", "into", "than", "then", "each", "show", "shows", "used", "uses", "use", "very", "which", "there", "their", "about", "over", "under", "while", "where", "also", "onto"]);
+
+// The components in src/ that came from the library, and the ones written in this project.
+export function libraryUse(project: Project): { pulled: string[]; written: string[] } {
+  const entries = Object.values(project.readJsonOr<Record<string, { path: string; kind: string }>>(FILES.library, {}));
+  const names = readdirSync(project.path("src")).filter((f) => FILE_NAME.test(f) && f !== MAIN_FILE);
+  const pulled = names.filter((n) => entries.some((e) => e.kind === "component" && e.path === `src/${n}`));
+  return { pulled: pulled.map(componentName), written: names.filter((n) => !pulled.includes(n)).map(componentName) };
+}
+
+const sf = (source: string, file: string) => ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+
+// The comment block directly above `export const <name>`, as plain words.
+export function leadingComment(source: string, name: string): string | undefined {
+  const file = sf(source, `${name}.tsx`);
+  const stmt = file.statements.find((s) => ts.isVariableStatement(s) && s.declarationList.declarations.some((d) => ts.isIdentifier(d.name) && d.name.text === name));
+  if (!stmt) return undefined;
+  const ranges = ts.getLeadingCommentRanges(source, stmt.getFullStart()) ?? [];
+  const block: ts.CommentRange[] = [];
+  for (let i = ranges.length - 1; i >= 0; i--) {
+    const r = ranges[i]!;
+    // Only a comment with no blank line between it and what follows belongs to the declaration.
+    const gap = source.slice(r.end, i === ranges.length - 1 ? stmt.getStart() : ranges[i + 1]!.pos);
+    if ((gap.match(/\n/g) ?? []).length > 1) break;
+    block.unshift(r);
+  }
+  const text = block.map((r) => source.slice(r.pos, r.end).replace(/^\/\*+|\*+\/$/g, "").split("\n").map((l) => l.replace(/^\s*(\/\/+|\*+)\s?/, "").trim()).join(" ")).join(" ").replace(/\s+/g, " ").trim();
+  return text || undefined;
+}
+
+// Every piece of text a file writes out: strings, template text and JSX text. Names and comments are not text.
+export function literalTexts(source: string, file: string): string[] {
+  const out: string[] = [];
+  const visit = (n: ts.Node) => {
+    if (ts.isStringLiteralLike(n)) out.push(n.text);
+    else if (ts.isTemplateHead(n) || ts.isTemplateMiddle(n) || ts.isTemplateTail(n)) out.push(n.text);
+    else if (ts.isJsxText(n) && n.text.trim()) out.push(n.text.trim());
+    ts.forEachChild(n, visit);
+  };
+  visit(sf(source, file));
+  return out;
+}
+
+const cutShort = (t: string) => (t.length > 40 ? `${t.slice(0, 40)}…` : t);
+
+const sharesRun = (a: string, b: string, n: number): boolean => {
+  for (let i = 0; i + n <= b.length; i++) if (a.includes(b.slice(i, i + n))) return true;
+  return false;
+};
+
+// A cheap guard against sharing something that belongs to this user: their own files, their video's title, their words.
+export function privateReason(source: string, file: string, plan: { title?: string; scenes?: { narration?: string; onScreenText?: string[] }[] }): string | undefined {
+  const texts = literalTexts(source, file);
+  if (texts.some((t) => t.startsWith("assets/user/"))) return "it uses one of your own files (assets/user/...). A shared component takes its pictures and text from props.";
+  const title = plan.title?.trim().toLowerCase();
+  if (title && title.length >= 4 && texts.some((t) => t.toLowerCase().includes(title))) return "it contains this video's title. A shared component takes its text from props.";
+  const norm = (s: string) => s.replace(/\s+/g, " ").trim();
+  for (const t of texts.map(norm).filter((t) => t.length > 60)) {
+    if ((plan.scenes ?? []).some((s) => sharesRun(norm(s.narration ?? ""), t, 61) || sharesRun(t, norm(s.narration ?? ""), 61))) return "it contains a long piece of this video's narration. A shared component takes its text from props.";
+  }
+  // Anything written into the component leaves the machine with it, so a component that carries this video's own words is not
+  // shared at all, however short they are: a customer's name or a headline is eight characters as easily as eighty. Two rules, both
+  // erring toward not sharing: text that also appears in the plan, and any whole sentence written into the code.
+  const low = (v: string) => norm(v).toLowerCase();
+  const planTexts = (plan.scenes ?? []).flatMap((sc) => [sc.narration ?? "", ...(sc.onScreenText ?? [])]).map(low).filter(Boolean);
+  for (const t of texts.map(low)) {
+    if (t.length >= 8 && planTexts.some((p) => p.includes(t))) return `it contains words from this video ("${cutShort(t)}"). A shared component takes its text from props.`;
+    // A font stack, a transform or a gradient is several words too: text with code punctuation, or a comma list of short items, is not a sentence.
+    const codeLike = /[():;%#{}=<>]/.test(t) || (t.split(",").length >= 3 && t.split(",").every((part) => part.trim().split(" ").length <= 3));
+    if (!codeLike && t.split(" ").filter((w) => /\p{L}{2,}/u.test(w)).length >= 5) return `it has a sentence written into it ("${cutShort(t)}"). A shared component takes its text from props.`;
+  }
+  return undefined;
+}
+
+// Lowercase words, 3 to 6: the words of the name first, then the longer words of the description.
+export function deriveTags(name: string, description: string): string[] {
+  const fromName = name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(/\s+/);
+  const fromText = description.toLowerCase().match(/[a-z]{4,}/g) ?? [];
+  const tags = [...new Set([...fromName, ...fromText.filter((w) => !STOP_WORDS.has(w))])].filter((t) => t.length <= 40);
+  for (const filler of ["component", "motion", "video"]) if (tags.length < 3 && !tags.includes(filler)) tags.push(filler);
+  return tags.slice(0, 6);
+}
+
+function prepare(project: Project, name: string, opts: { describe?: string; example?: string; tags?: string }, plan: Parameters<typeof privateReason>[2], siblings: string[]): Prepared | { name: string; reason: string } {
+  const file = `${name}.tsx`;
+  const skip = (reason: string) => ({ name, reason });
+  if (!FILE_NAME.test(file) || file === MAIN_FILE || !project.exists(`src/${file}`)) return skip(`there is no component file src/${file}.`);
+  const source = readFileSync(project.path(`src/${file}`), "utf8");
+  if (Buffer.byteLength(source) > MAX_COMPONENT_BYTES) return skip(`it is larger than ${MAX_COMPONENT_BYTES / 1024} KB.`);
+  const problems = staticCheck(source, file, siblings);
+  if (problems.length) return skip(`it does not pass the check (${problems[0]}). Fix it with \`reelkit check\` first.`);
+  const reason = privateReason(source, file, plan);
+  if (reason) return skip(reason);
+  const description = (opts.describe ?? leadingComment(source, name) ?? "").trim();
+  if (description.length < MIN_COMPONENT_DESCRIPTION) return skip(`it has no description. Put a sentence or two above \`export const ${name}\` saying what it shows and when to use it${opts.describe === undefined ? ", or pass --describe" : ""}.`);
+  let example = opts.example?.trim();
+  if (opts.example !== undefined && !example?.startsWith(`<${name}`)) return skip(`--example must start with <${name}.`);
+  if (!example) {
+    const main = project.exists(`src/${MAIN_FILE}`) ? readFileSync(project.path(`src/${MAIN_FILE}`), "utf8") : "";
+    const use = jsxUses(main, MAIN_FILE, name)[0];
+    if (!use) return skip(`<${name}> is not used in src/${MAIN_FILE}, so there is no example to take. Pass --example '<${name} ... />'.`);
+    if (!use.literal) return skip(`its use in src/${MAIN_FILE} has props that are not plain values (variables or data from the video). Pass --example '<${name} ... />' with plain values.`);
+    example = use.example;
+  }
+  if (example.length > MAX_COMPONENT_EXAMPLE) return skip(`its example is longer than ${MAX_COMPONENT_EXAMPLE} characters. Pass a shorter --example.`);
+  const tags = opts.tags ? opts.tags.split(",").map((t) => t.trim().toLowerCase()).filter(Boolean) : deriveTags(name, description);
+  return { name, file, source, hash: createHash("sha256").update(source).digest("hex"), description, example, tags };
+}
+
+// Which components a share would send, and why any other is left out. Nothing is sent here.
+export function prepareShare(project: Project, names: string[] | undefined, opts: { describe?: string; example?: string; tags?: string } = {}): { ready: Prepared[]; skipped: { name: string; reason: string }[] } {
+  const plan = project.readJsonOr<Parameters<typeof privateReason>[2]>(FILES.plan, {});
+  const siblings = readdirSync(project.path("src")).filter((f) => f.endsWith(".tsx"));
+  const { pulled, written } = libraryUse(project);
+  const done = project.readJsonOr<SharedRecord[]>(FILES.shared, []);
+  const ready: Prepared[] = [], skipped: { name: string; reason: string }[] = [];
+  for (const name of names?.length ? names : written) {
+    if (pulled.includes(name)) { skipped.push({ name, reason: "it was pulled from the library, so it is already there." }); continue; }
+    const p = prepare(project, name, names?.length === 1 ? opts : {}, plan, siblings);
+    if ("reason" in p) { skipped.push(p); continue; }
+    // The same source is not sent twice.
+    if (done.some((d) => d.name === name && d.hash === p.hash)) continue;
+    ready.push(p);
+  }
+  return { ready, skipped };
+}
+
+async function send(ctx: Ctx, project: Project, ready: Prepared[]): Promise<ShareOutcome["shared"]> {
+  const api = client(ctx);
+  const shared: ShareOutcome["shared"] = [];
+  for (const c of ready) {
+    // Only the component's own name, source, description, example and tags leave this machine: no project name, path or plan text.
+    const bytes = new TextEncoder().encode(c.source);
+    const up = await api("libraryUpload", { kind: "component", title: c.name, description: c.description, tags: c.tags, meta: { example: c.example }, filename: c.file, contentType: "text/plain", bytes: bytes.length, shareable: true });
+    await uploadTo(up.uploadUrl, new Uint8Array(bytes), "text/plain");
+    const libraryId = (await api("libraryCommit", { id: up.id })).item.id;
+    project.writeJson(FILES.shared, [...project.readJsonOr<SharedRecord[]>(FILES.shared, []).filter((d) => d.name !== c.name), { name: c.name, libraryId, hash: c.hash }]);
+    shared.push({ name: c.name, libraryId, file: c.file, description: c.description, example: c.example });
+  }
+  return shared;
+}
+
+export const STOP_SHARING = "To stop this, run `reelkit render --no-share`, set REELKIT_NO_SHARE=1, or start new projects with `reelkit init <name> --private`.";
+
+const sentLines = (shared: ShareOutcome["shared"]) => shared.map((s) => `  ${s.file}: ${s.description} Example: ${s.example}`);
+const skippedLines = (skipped: ShareOutcome["skipped"]) => skipped.map((s) => `  Not shared: ${s.name}: ${s.reason}`);
+
+// `reelkit components share [name...]`: an explicit request, so it shares at once.
+export async function componentsShare(ctx: Ctx, names: string[], opts: { describe?: string; example?: string; tags?: string }): Promise<Result> {
+  const project = openProject(ctx.cwd);
+  if (names.length !== 1 && (opts.describe !== undefined || opts.example !== undefined || opts.tags !== undefined)) return { ok: false, summary: "--describe, --example and --tags go with exactly one component name: reelkit components share StatRing --describe \"...\"." };
+  if (!loadCredentials(ctx.env)) return { ok: false, summary: "You are not logged in. Run `reelkit auth login`, then share again." };
+  const { ready, skipped } = prepareShare(project, names, opts);
+  const shared = await send(ctx, project, ready);
+  const data: ShareOutcome = { shared, skipped };
+  if (!shared.length && !skipped.length) return { ok: true, data, summary: "Nothing to share: every component written in this project has already been shared, or there are none." };
+  return {
+    ok: shared.length > 0 || skipped.length === 0, data,
+    summary: [
+      shared.length ? `Shared ${shared.length} component${shared.length === 1 ? "" : "s"} with the Reelkit library for review: ${shared.map((s) => s.name).join(", ")}. Nothing else from this project was sent.` : "No component was shared.",
+      ...sentLines(shared), ...skippedLines(skipped),
+    ].join("\n"),
+  };
+}
+
+// The notice a person sees once per machine before components start to be shared by a render.
+export const SHARING_NOTICE = `New components you write are shared with the Reelkit library for review after a render, starting with the next one: each component's source, a description and an example, and nothing else (no project name, file paths or script). ${STOP_SHARING}`;
+
+const noticesPath = (env: Ctx["env"]) => join(configDir(env), "notices.json");
+function sharingNoticeShown(env: Ctx["env"]): boolean {
+  try { return typeof (JSON.parse(readFileSync(noticesPath(env), "utf8")) as { componentSharing?: unknown }).componentSharing === "string"; } catch { return false; }
+}
+function recordSharingNotice(env: Ctx["env"]): boolean {
+  try {
+    let all: Record<string, unknown> = {};
+    try { all = JSON.parse(readFileSync(noticesPath(env), "utf8")) as Record<string, unknown>; } catch { /* a new file */ }
+    mkdirSync(configDir(env), { recursive: true, mode: 0o700 });
+    writeFileSync(noticesPath(env), JSON.stringify({ ...all, componentSharing: new Date().toISOString() }, null, 2));
+    return true;
+  } catch { return false; }
+}
+
+// After a render: share the new components unless the person has opted out. It never fails the render; it returns the lines to add to its summary.
+export async function shareAfterRender(ctx: Ctx, project: Project, opts: { noShare?: boolean }): Promise<{ lines: string[]; data?: ShareOutcome }> {
+  const off = ctx.env.REELKIT_NO_SHARE;
+  if (opts.noShare || (off && off !== "0" && off.toLowerCase() !== "false") || project.config().shareComponents === false) return { lines: ["No components were shared with the Reelkit library (sharing is turned off)."] };
+  if (!existsSync(project.path("src"))) return { lines: [] };
+  try {
+    const { ready, skipped } = prepareShare(project, undefined);
+    const notShared = skippedLines(skipped);
+    if (!ready.length) return { lines: [...notShared, ...(notShared.length ? [] : ["No new components to share with the Reelkit library."])] };
+    if (!loadCredentials(ctx.env)) return { lines: ["Components were not shared with the Reelkit library: you are not logged in.", ...notShared] };
+    if (!sharingNoticeShown(ctx.env)) {
+      // The first time on this machine: say what will happen, and share from the next render on.
+      return { lines: recordSharingNotice(ctx.env) ? [SHARING_NOTICE, ...notShared] : [`Components were not shared: ${"the notice could not be saved in " + configDir(ctx.env)}.`] };
+    }
+    const shared = await send(ctx, project, ready);
+    return {
+      data: { shared, skipped },
+      lines: [`Shared ${shared.length} new component${shared.length === 1 ? "" : "s"} with the Reelkit library for review: ${shared.map((s) => s.name).join(", ")}. Nothing else from this project was sent. ${STOP_SHARING}`, ...sentLines(shared), ...notShared],
+    };
+  } catch (e) {
+    return { lines: [`Components were not shared with the Reelkit library (${e instanceof Error ? e.message : String(e)}). The video is not affected.`] };
+  }
+}

package/src/commands/init.ts

@@ -10,7 +10,7 @@ import { FILES, Project } from "../project/project";
 const exec = promisify(execFile);
 const DIRS = ["assets", "refs", "src", "out"];
 
-export async function init(ctx: Ctx, name: string | undefined, opts: { aspect?: string }): Promise<Result> {
+export async function init(ctx: Ctx, name: string | undefined, opts: { aspect?: string; private?: boolean }): Promise<Result> {
   const slug = name === undefined ? undefined : name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
   if (slug === "") return { ok: false, summary: "Give the project a name with letters or digits, for example: reelkit init launch-video" };
   const aspect = AspectSchema.safeParse(opts.aspect ?? "9:16");
@@ -22,11 +22,17 @@ export async function init(ctx: Ctx, name: string | undefined, opts: { aspect?:
   if (slug && existsSync(dir) && !statSync(dir).isDirectory()) return { ok: false, summary: `A file named ${slug} is in the way. Choose another project name or remove it.` };
   const project = new Project(dir);
   for (const d of DIRS) mkdirSync(project.path(d), { recursive: true });
-  if (!project.exists(FILES.config)) project.writeJson(FILES.config, { aspect: aspect.data, ...(name !== undefined && { name }) });
+  if (!project.exists(FILES.config)) project.writeJson(FILES.config, { aspect: aspect.data, ...(name !== undefined && { name }), ...(opts.private && { shareComponents: false }) });
+  else if (opts.private) project.writeJson(FILES.config, { ...project.config(), shareComponents: false });
   if (!existsSync(project.path(".gitignore"))) writeFileSync(project.path(".gitignore"), ".reelkit\nout\nrefs\n");
   ensureSkill(ctx);
   return {
     ok: true, data: { dir, config: project.config() },
-    summary: `Project ready in ${dir} (${project.config().aspect}).${slug ? ` Next: cd ${slug}` : ""}`,
+    summary: [
+      `Project ready in ${dir} (${project.config().aspect}).${slug ? ` Next: cd ${slug}` : ""}`,
+      project.config().shareComponents === false
+        ? "This project is private: nothing from it is sent to the library, not its components and not the images, clips or graphics generated for it, whatever the plan says."
+        : "After a render, new components written in this project are sent to the Reelkit library for review (their source, a description and an example; nothing else). To turn this off: `reelkit init <name> --private` for a new project, `reelkit render --no-share`, or REELKIT_NO_SHARE=1.",
+    ].join("\n"),
   };
 }

package/src/commands/install.ts

@@ -17,7 +17,7 @@ export async function install(ctx: Ctx, opts: { agent?: string; force?: boolean
   }
   const name = (id: string) => AGENTS.find((a) => a.id === id)!.name;
   const lines = [
-    ...report.installed.map((i) => `Installed the Reelkit skill for ${name(i.agent)}: ${i.path}`),
+    ...report.installed.map((i) => `Installed the Reelkit skill for ${name(i.agent)}: ${i.path}${i.commands.length ? ` and the commands ${i.commands.map((c) => `/${c}`).join(" and ")}` : ""}`),
     ...report.skipped.filter((s) => agents || s.reason !== "not installed on this machine").map((s) => `Skipped ${name(s.agent)}: ${s.reason}`),
   ];
   return { ok: true, data: report, summary: lines.join("\n") };