fix(cli): align skill docs and command surface with actual CLI

Fixes drifts discovered by walking the skill rules end-to-end against
the CLI on a real 47s recording.

- output.ts: add outputList<T> so `--json` list commands emit the raw
  object array instead of the display-formatted `outputTable` keys
  (was: `{"Start (ms)": "2000"}`, now: `{"startMs": 2000}`). JSON list
  shape now matches JSON add shape, so agents can use a single parser
- zoom/trim/speed/annotate list: migrated to outputList
- project-manager.ts: `--wallpaper wallpaperN` now translates to
  `/wallpapers/wallpaperN.jpg` (the path the renderer expects) in both
  createProject and editProject. Hex colors and absolute paths pass
  through unchanged. Out-of-range N (e.g. wallpaper99) now errors with
  a specific message instead of silently storing garbage
- render.ts + index.ts + mcp-server.ts: drop the `still` and `frames`
  stub commands that errored with "not yet implemented" at runtime.
  The command surface now matches what actually works so agents aren't
  led toward dead ends
- SKILL.md: remove the stills/frames rule reference and description
  line. Delete cli/skills/rules/frames-stills.md entirely
- troubleshooting.md: add the "Video decode ended early" gotcha with
  the ffprobe recipe (regions must fall within video duration — the
  CLI doesn't probe at add time). Correct the Electron install note
- export-render.md: correct the progress JSON example (phase is only
  present during `finalizing`, not `extracting`); document the new
  `--loop`/`--no-loop` tri-state contract

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: lupuleticatalin

cli/skills/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   CLI for OpenScreen — screen recording and video editing.
   Create, inspect, and modify .openscreen project files.
   Add zoom/trim/speed effects and annotations.
-  Capture stills, export frame sequences, render to MP4 or GIF.
+  Render to MP4 or GIF.
 metadata:
   tags: [video, screen-recording, editing, export, cli]
 ---
@@ -59,8 +59,5 @@ Load ./rules/annotations.md
 ## When rendering or exporting
 Load ./rules/export-render.md
 
-## When capturing frames or stills
-Load ./rules/frames-stills.md
-
 ## When troubleshooting
 Load ./rules/troubleshooting.md

cli/skills/rules/export-render.md

@@ -25,9 +25,13 @@ The render command spawns OpenScreen's Electron renderer headlessly. It:
 
 Progress is reported as JSON lines when using `--json`:
 ```json
-{"progress": 45, "current": 135, "total": 300, "phase": "extracting"}
+{"progress": 45, "current": 135, "total": 300}
+{"progress": 100, "current": 300, "total": 300, "phase": "finalizing"}
+{"success": true, "path": "/abs/path/demo.mp4", "format": "mp4", "size": 1076106}
 ```
 
+Agents should parse the `done` line (with `success: true`) as the terminal event and use `path`/`size`/`format` from it. The `phase` key is only present during the `finalizing` phase; during frame extraction it is absent. On failure, a single `{"error": "..."}` line is emitted to stderr and the process exits non-zero.
+
 ## Rendering to GIF
 
 ```bash
@@ -36,14 +40,13 @@ openscreen gif \
   --output demo.gif \
   --frame-rate 15 \
   --size-preset medium \
-  --loop \
   --overwrite
 ```
 
 ### GIF settings
 - `--frame-rate` — 15 (balanced), 20 (smooth), 25 (very smooth), 30 (maximum)
 - `--size-preset` — medium (720p), large (1080p), original
-- `--loop` — loop the GIF (default: true)
+- `--loop` / `--no-loop` — override the project's loop setting. If neither is passed, the GIF uses the project's `editor.gifLoop` (default: loop). Pass `--no-loop` to force a non-looping GIF regardless of project state.
 
 ### GIF best practices
 - **15 FPS** is usually enough for UI demos

cli/skills/rules/frames-stills.md

@@ -25,7 +25,10 @@ openscreen --json project create --video /new/path/recording.webm --output demo.
 The project file is missing required fields. It needs: `version`, `media` (or `videoPath`), and `editor`.
 
 ### Render commands fail with "requires Electron headless bridge"
-The `render`, `gif`, `still`, and `frames` commands need the Electron app installed. These commands are Phase 3 features.
+The `render` and `gif` commands spawn a headless Electron process from the repo's `node_modules/.bin/electron`. Run `npm run build-vite` first so `dist-electron/main.js` exists.
+
+### Render fails partway through: "Video decode ended early at X.Ys (needed Y.Ys)"
+A region (zoom/trim/speed/annotation) extends past the end of the underlying video. The CLI does not probe video duration at add time — it trusts the caller. Before adding regions with large timestamps, confirm the video is long enough (e.g. with `ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 recording.webm`). Timestamps are in milliseconds and must fall within `[0, duration]`.
 
 ## Debugging tips
 
@@ -59,5 +62,5 @@ echo "Exit code: $?"
 ## Performance notes
 
 - CLI commands that manipulate project files (create, edit, zoom/trim/speed/annotate add/remove) are pure Node.js and run in milliseconds
-- Render, still, and frames commands spawn Electron headlessly — expect seconds to minutes depending on video length and quality
+- `render` and `gif` spawn Electron headlessly — expect seconds to minutes depending on video length and quality
 - Use `--quiet` to suppress progress output for faster piped workflows

cli/skills/rules/troubleshooting.md

@@ -4,7 +4,7 @@ import {
 	listAnnotationRegions,
 	removeAnnotationRegion,
 } from "../core/region-manager";
-import { outputError, outputSuccess, outputTable } from "../output";
+import { outputError, outputList, outputSuccess } from "../output";
 
 export const annotateCommand = new Command("annotate").description("Manage annotations");
 
@@ -67,17 +67,17 @@ annotateCommand
 	.action((opts) => {
 		try {
 			const regions = listAnnotationRegions(opts.project);
-			outputTable(
-				["ID", "Type", "Start (ms)", "End (ms)", "Position", "Content"],
-				regions.map((r) => [
+			outputList(regions, {
+				headers: ["ID", "Type", "Start (ms)", "End (ms)", "Position", "Content"],
+				rows: regions.map((r) => [
 					r.id,
 					r.type,
 					String(r.startMs),
 					String(r.endMs),
 					`(${r.position.x}, ${r.position.y})`,
 					(r.textContent || r.content || "").slice(0, 30),
 				]),
-			);
+			});
 		} catch (e) {
 			outputError(e instanceof Error ? e.message : String(e));
 		}

cli/src/commands/annotate.ts

@@ -60,29 +60,3 @@ export const gifCommand = new Command("gif")
 			outputError(e instanceof Error ? e.message : String(e));
 		}
 	});
-
-export const stillCommand = new Command("still")
-	.description("Capture a single frame as PNG or JPEG (requires built Electron app)")
-	.requiredOption("--project <path>", "Path to .openscreen project file")
-	.requiredOption("--output <path>", "Output image file path")
-	.option("--frame <ms>", "Timestamp in milliseconds", "0")
-	.option("--format <f>", "Image format (png, jpeg)", "png")
-	.option("--jpeg-quality <q>", "JPEG quality (1-100)", "90")
-	.option("--scale <n>", "Device scale factor", "1")
-	.option("--overwrite", "Overwrite existing output file")
-	.action((_opts) => {
-		outputError("The still command is not yet implemented. Use render for full video export.");
-	});
-
-export const framesCommand = new Command("frames")
-	.description("Export a sequence of frames as images (requires built Electron app)")
-	.requiredOption("--project <path>", "Path to .openscreen project file")
-	.requiredOption("--output-dir <dir>", "Output directory for frames")
-	.option("--start <ms>", "Start timestamp in milliseconds", "0")
-	.option("--end <ms>", "End timestamp (default: video end)")
-	.option("--every-nth <n>", "Export every Nth frame", "1")
-	.option("--format <f>", "Image format (png, jpeg)", "png")
-	.option("--overwrite", "Overwrite existing output files")
-	.action((_opts) => {
-		outputError("The frames command is not yet implemented. Use render for full video export.");
-	});

cli/src/commands/render.ts

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import { addSpeedRegion, listSpeedRegions, removeSpeedRegion } from "../core/region-manager";
-import { outputError, outputSuccess, outputTable } from "../output";
+import { outputError, outputList, outputSuccess } from "../output";
 
 export const speedCommand = new Command("speed").description("Manage speed regions");
 
@@ -38,10 +38,10 @@ speedCommand
 	.action((opts) => {
 		try {
 			const regions = listSpeedRegions(opts.project);
-			outputTable(
-				["ID", "Start (ms)", "End (ms)", "Speed"],
-				regions.map((r) => [r.id, String(r.startMs), String(r.endMs), `${r.speed}x`]),
-			);
+			outputList(regions, {
+				headers: ["ID", "Start (ms)", "End (ms)", "Speed"],
+				rows: regions.map((r) => [r.id, String(r.startMs), String(r.endMs), `${r.speed}x`]),
+			});
 		} catch (e) {
 			outputError(e instanceof Error ? e.message : String(e));
 		}

cli/src/commands/speed.ts

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import { addTrimRegion, listTrimRegions, removeTrimRegion } from "../core/region-manager";
-import { outputError, outputSuccess, outputTable } from "../output";
+import { outputError, outputList, outputSuccess } from "../output";
 
 export const trimCommand = new Command("trim").description("Manage trim regions");
 
@@ -32,10 +32,10 @@ trimCommand
 	.action((opts) => {
 		try {
 			const regions = listTrimRegions(opts.project);
-			outputTable(
-				["ID", "Start (ms)", "End (ms)"],
-				regions.map((r) => [r.id, String(r.startMs), String(r.endMs)]),
-			);
+			outputList(regions, {
+				headers: ["ID", "Start (ms)", "End (ms)"],
+				rows: regions.map((r) => [r.id, String(r.startMs), String(r.endMs)]),
+			});
 		} catch (e) {
 			outputError(e instanceof Error ? e.message : String(e));
 		}

cli/src/commands/trim.ts

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import { addZoomRegion, listZoomRegions, removeZoomRegion } from "../core/region-manager";
-import { outputError, outputSuccess, outputTable } from "../output";
+import { outputError, outputList, outputSuccess } from "../output";
 
 export const zoomCommand = new Command("zoom").description("Manage zoom regions");
 
@@ -40,9 +40,9 @@ zoomCommand
 	.action((opts) => {
 		try {
 			const regions = listZoomRegions(opts.project);
-			outputTable(
-				["ID", "Start (ms)", "End (ms)", "Depth", "Focus X", "Focus Y", "Mode"],
-				regions.map((r) => [
+			outputList(regions, {
+				headers: ["ID", "Start (ms)", "End (ms)", "Depth", "Focus X", "Focus Y", "Mode"],
+				rows: regions.map((r) => [
 					r.id,
 					String(r.startMs),
 					String(r.endMs),
@@ -51,7 +51,7 @@ zoomCommand
 					r.focus.cy.toFixed(2),
 					r.focusMode ?? "manual",
 				]),
-			);
+			});
 		} catch (e) {
 			outputError(e instanceof Error ? e.message : String(e));
 		}

cli/src/commands/zoom.ts

@@ -104,6 +104,22 @@ export function saveProject(projectPath: string, data: EditorProjectData): void
 	fs.renameSync(tmpPath, absPath);
 }
 
+// Translate wallpaper shortcuts (wallpaper1..wallpaper18) into the bundled
+// path the renderer expects (/wallpapers/wallpaperN.jpg). Hex colors, absolute
+// paths, and anything already matching a known wallpaper path pass through
+// unchanged so GUI-saved projects stay valid.
+function normalizeWallpaperInput(value: string): string {
+	const match = /^wallpaper(\d+)$/.exec(value);
+	if (!match) return value;
+	const index = Number.parseInt(match[1], 10);
+	if (!Number.isFinite(index) || index < 1 || index > WALLPAPER_PATHS.length) {
+		throw new Error(
+			`Invalid wallpaper shortcut: ${value}. Expected wallpaper1 through wallpaper${WALLPAPER_PATHS.length}, a hex color (#rrggbb), or an absolute path.`,
+		);
+	}
+	return WALLPAPER_PATHS[index - 1];
+}
+
 export function createProject(
 	options: CreateProjectOptions,
 	outputPath: string,
@@ -131,7 +147,8 @@ export function createProject(
 
 	const editorOverrides: Partial<ProjectEditorState> = {};
 
-	if (options.wallpaper !== undefined) editorOverrides.wallpaper = options.wallpaper;
+	if (options.wallpaper !== undefined)
+		editorOverrides.wallpaper = normalizeWallpaperInput(options.wallpaper);
 	if (options.padding !== undefined) editorOverrides.padding = options.padding;
 	if (options.borderRadius !== undefined) editorOverrides.borderRadius = options.borderRadius;
 	if (options.aspectRatio !== undefined) editorOverrides.aspectRatio = options.aspectRatio;
@@ -211,7 +228,8 @@ export function editProject(projectPath: string, edits: EditProjectOptions): Edi
 
 	const updatedEditor: ProjectEditorState = { ...project.editor };
 
-	if (edits.wallpaper !== undefined) updatedEditor.wallpaper = edits.wallpaper;
+	if (edits.wallpaper !== undefined)
+		updatedEditor.wallpaper = normalizeWallpaperInput(edits.wallpaper);
 	if (edits.padding !== undefined) updatedEditor.padding = edits.padding;
 	if (edits.borderRadius !== undefined) updatedEditor.borderRadius = edits.borderRadius;
 	if (edits.shadowIntensity !== undefined) updatedEditor.shadowIntensity = edits.shadowIntensity;