@putdotio/rokit 2.1.0 → 2.3.0

package/AGENTS.md

@@ -28,6 +28,8 @@ Keep it platform-focused, typed, and useful for both humans and agents.
 - Treat `process.cwd()` as the consumer app root.
 - Keep `.rokit/` consumer-local; it can hold env, generated artifacts, and
   transient device state.
+- Keep `skills/rokit/SKILL.md` aligned with agent-facing command and safety
+  guardrails.
 - Keep `examples/live-probe-channel` generic. It exists only to prove package,
   install, launch, input, SceneGraph, screenshot, and proof mechanics.
 - Wrap `roku-deploy` for package publish, screenshots, and device metadata when
@@ -53,7 +55,8 @@ Keep it platform-focused, typed, and useful for both humans and agents.
 - Avoid sleeps in generic commands. App repos can add meaningful wait/assert
   loops around `rokit` primitives.
 - Release details live in `docs/DISTRIBUTION.md`; debugging details live in
-  `docs/DEBUGGING.md`; readiness details live in `docs/READINESS.md`.
+  `docs/DEBUGGING.md`; readiness details live in `docs/READINESS.md`;
+  consumer skill guidance lives in `skills/rokit/SKILL.md`.
 
 ## When Contracts Change
 

package/README.md

@@ -106,6 +106,7 @@ App-specific scenario scripts can import the generic helpers:
 import {
   assertMediaPlayerContainer,
   assertSceneGraphNode,
+  captureScreenshot,
   pressKey,
   querySceneGraph,
   waitForSceneGraphAssertion,
@@ -124,9 +125,14 @@ const context: RokuContext = {
 };
 
 await pressKey(context, "Info");
-await querySceneGraph(context, { attempts: 3, requireComplete: true });
+await querySceneGraph(context, { attempts: 3, requireAppNode: true, requireComplete: true });
 await assertSceneGraphNode(context, "videoPlayerScreen", { state: "visible" });
 await assertMediaPlayerContainer(context, "mp4");
+await captureScreenshot(
+  { ...context, password: process.env.ROKIT_PASSWORD ?? "" },
+  "artifacts/player.jpg",
+  { attempts: 3 },
+);
 await waitForSceneGraphAssertion(context, "player ready", (xml) => {
   if (!xml.includes("videoPlayerScreen")) {
     throw new Error("expected player screen");
@@ -154,6 +160,7 @@ artifacts.
 - [Roku debugging](./docs/DEBUGGING.md)
 - [Distribution](./docs/DISTRIBUTION.md)
 - [Agent readiness](./docs/READINESS.md)
+- [rokit skill](./skills/rokit/SKILL.md)
 - [Security](./SECURITY.md)
 
 ## Repo Internals

package/dist/{debug-af6vvS9T.mjs → debug-BbJdwNkW.mjs}

@@ -4,6 +4,8 @@ import { existsSync } from "node:fs";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import * as rokuDeploy from "roku-deploy";
 import { createSocket } from "node:dgram";
+import { access, copyFile, mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
 //#region src/errors.ts
 var InvalidInput = class extends Schema.TaggedErrorClass()("InvalidInput", { message: Schema.String }) {};
 var MissingTarget = class extends Schema.TaggedErrorClass()("MissingTarget", {}) {
@@ -335,22 +337,31 @@ const waitForMediaPlayerState = async (context, expectedState, timeoutMs = 1e4)
 };
 const querySceneGraph = async (context, options = {}) => {
 	const attempts = options.attempts ?? 1;
+	const requireAppNode = options.requireAppNode ?? false;
 	const requireComplete = options.requireComplete ?? false;
 	const retryDelayMs = options.retryDelayMs ?? 500;
 	let lastXml = "";
 	let lastError;
+	let lastMissingAppNode = false;
 	for (let attempt = 0; attempt < attempts; attempt += 1) {
 		try {
 			const xml = await queryEcp(context, "/query/sgnodes/all");
-			if (!requireComplete || isCompleteSceneGraph(xml)) return xml;
+			const complete = !requireComplete || isCompleteSceneGraph(xml);
+			const hasAppNode = !requireAppNode || !xml.includes("<All_Nodes>") || xml.includes("<App ");
+			if (complete && hasAppNode) return xml;
 			lastXml = xml;
+			lastMissingAppNode = complete && !hasAppNode;
 		} catch (error) {
 			lastError = error;
 			lastXml = "";
+			lastMissingAppNode = false;
 		}
 		if (attempt < attempts - 1) await sleep(retryDelayMs);
 	}
-	if (lastXml !== "") throw new Error("SceneGraph query returned incomplete XML");
+	if (lastXml !== "") {
+		if (lastMissingAppNode) throw new Error("SceneGraph query returned complete XML without an App node");
+		throw new Error("SceneGraph query returned incomplete XML");
+	}
 	throw new Error(`SceneGraph query failed: ${formatErrorMessage$1(lastError)}`);
 };
 const assertSceneGraphNode = async (context, nodeName, expectation) => {
@@ -411,6 +422,41 @@ const takeScreenshot = async (context, outputPath) => {
 		password: context.password
 	});
 };
+const captureScreenshot = async (context, outputPath, options = {}) => {
+	const attempts = options.attempts ?? 3;
+	const retryDelayMs = options.retryDelayMs ?? 1500;
+	const resolvedOutput = resolve(outputPath);
+	await mkdir(dirname(resolvedOutput), { recursive: true });
+	let lastError = "unknown";
+	for (let attempt = 1; attempt <= attempts; attempt += 1) {
+		const captureDir = await mkdtemp(join(tmpdir(), `${safeTempPrefix(options.tempDirPrefix ?? "rokit-screenshot")}-`));
+		const capturePath = join(captureDir, basename(resolvedOutput));
+		try {
+			const tempResult = await firstExistingPath([await takeScreenshot(context, capturePath), capturePath]);
+			if (tempResult !== void 0) {
+				await copyFile(tempResult, resolvedOutput);
+				return resolvedOutput;
+			}
+			const directResult = await firstExistingPath([resolvedOutput, await takeScreenshot(context, resolvedOutput)]);
+			if (directResult === resolvedOutput) return resolvedOutput;
+			if (directResult !== void 0) {
+				await copyFile(directResult, resolvedOutput);
+				return resolvedOutput;
+			}
+			throw new Error("screenshot capture succeeded without writing an image file");
+		} catch (error) {
+			lastError = formatErrorMessage$1(error);
+			if (attempt === attempts) break;
+			await sleep(retryDelayMs);
+		} finally {
+			await rm(captureDir, {
+				force: true,
+				recursive: true
+			});
+		}
+	}
+	throw new Error(`failed to capture ${basename(resolvedOutput)}: ${lastError}`);
+};
 const packageChannel = async (outputPath, rootDir = process.cwd()) => {
 	const options = packageOptions(outputPath, rootDir);
 	await rokuDeploy.createPackage(options);
@@ -444,6 +490,18 @@ const rejectUnsafeInput$1 = (value, label) => {
 		return code < 32 || code === 127;
 	})) throw new Error(`${label} contains control characters`);
 };
+const safeTempPrefix = (value) => value.replace(/[^a-zA-Z0-9_-]/g, "-");
+const firstExistingPath = async (paths) => {
+	for (const path of paths) if (await fileExists(path)) return path;
+};
+const fileExists = async (path) => {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+};
 const validateRemoteKey = (key) => {
 	if (key.startsWith("Lit_")) return;
 	if (!remoteKeySet.has(key)) throw new Error(`unsupported remote key: ${key}`);
@@ -747,4 +805,4 @@ const validateNonNegativeInteger = (value, label) => {
 	if (!Number.isInteger(parsed) || parsed < 0) fail(`Invalid ${label}: ${value}`);
 };
 //#endregion
-export { readNamedNodeBounds as $, readMediaPlayerInfo as A, waitForSceneGraphNode as B, queryEcp as C, queryMediaPlayerXmlSafe as D, queryMediaPlayerXml as E, validateEcpPath as F, assertNamedNodeTranslation as G, assertNamedNodeSize as H, validateRemoteKey as I, isCompleteSceneGraph as J, assertSceneGraphNumberNear as K, waitForActiveApp as L, readMediaPlayerState as M, resolvePackageOutputPath as N, querySceneGraph as O, takeScreenshot as P, readNamedNodeAttributes as Q, waitForMediaPlayerState as R, queryActiveApp as S, queryMediaPlayerSafe as T, assertNamedNodeState as U, assertNamedNode as V, assertNamedNodeText as W, parseSceneGraphNumberList as X, isNamedNodeVisible as Y, readNamedNodeAttribute as Z, installPackage as _, loadEnv as a, readActiveApp as at, packageChannel as b, requirePassword as c, normalizeError as ct, resolveOutputPath as d, readNamedNodeNumber as et, assertMediaPlayerContainer as f, getDeviceInfo as g, discoverRokuDevices as h, fail as i, sceneGraphContainsText as it, readMediaPlayerPositionMs as j, readMediaPlayerContainer as k, requireTarget as l, renderError as lt, checkDevice as m, captureDebugConsole as n, readSceneGraphFailure as nt, loadLocalEnv as o, readXmlAttribute as ot, assertSceneGraphNode as p, escapeXmlAttribute as q, runDebugCommand as r, readSceneGraphStatus as rt, rejectUnsafeEcpPath as s, readXmlTag as st, buildDebugCommand as t, readNamedNodeTranslation as tt, resolveFileOutputPath as u, isActiveMediaPlayerState as v, queryMediaPlayer as w, pressKey as x, launchApp as y, waitForSceneGraphAssertion as z };
+export { readNamedNodeAttributes as $, readMediaPlayerContainer as A, waitForSceneGraphAssertion as B, queryActiveApp as C, queryMediaPlayerXml as D, queryMediaPlayerSafe as E, takeScreenshot as F, assertNamedNodeText as G, assertNamedNode as H, validateEcpPath as I, escapeXmlAttribute as J, assertNamedNodeTranslation as K, validateRemoteKey as L, readMediaPlayerPositionMs as M, readMediaPlayerState as N, queryMediaPlayerXmlSafe as O, resolvePackageOutputPath as P, readNamedNodeAttribute as Q, waitForActiveApp as R, pressKey as S, queryMediaPlayer as T, assertNamedNodeSize as U, waitForSceneGraphNode as V, assertNamedNodeState as W, isNamedNodeVisible as X, isCompleteSceneGraph as Y, parseSceneGraphNumberList as Z, getDeviceInfo as _, loadEnv as a, sceneGraphContainsText as at, launchApp as b, requirePassword as c, readXmlTag as ct, resolveOutputPath as d, readNamedNodeBounds as et, assertMediaPlayerContainer as f, discoverRokuDevices as g, checkDevice as h, fail as i, readSceneGraphStatus as it, readMediaPlayerInfo as j, querySceneGraph as k, requireTarget as l, normalizeError as lt, captureScreenshot as m, captureDebugConsole as n, readNamedNodeTranslation as nt, loadLocalEnv as o, readActiveApp as ot, assertSceneGraphNode as p, assertSceneGraphNumberNear as q, runDebugCommand as r, readSceneGraphFailure as rt, rejectUnsafeEcpPath as s, readXmlAttribute as st, buildDebugCommand as t, readNamedNodeNumber as tt, resolveFileOutputPath as u, renderError as ut, installPackage as v, queryEcp as w, packageChannel as x, isActiveMediaPlayerState as y, waitForMediaPlayerState as z };

package/dist/index.d.mts

@@ -88,6 +88,7 @@ type MediaPlayerInfo = {
 };
 type RetryOptions = {
   readonly attempts?: number;
+  readonly requireAppNode?: boolean;
   readonly requireComplete?: boolean;
   readonly retryDelayMs?: number;
 };
@@ -99,6 +100,11 @@ type WaitForSceneGraphAssertionOptions = {
 type PackageResult = {
   readonly path: string;
 };
+type ScreenshotCaptureOptions = {
+  readonly attempts?: number;
+  readonly retryDelayMs?: number;
+  readonly tempDirPrefix?: string;
+};
 declare const checkDevice: (context: RokuContext) => Promise<DeviceSummary>;
 declare const getDeviceInfo: (context: RokuContext) => Promise<rokuDeploy.DeviceInfo>;
 declare const queryActiveApp: (context: RokuContext) => Promise<ActiveApp>;
@@ -128,6 +134,9 @@ declare const installPackage: (context: RokuContext & {
 declare const takeScreenshot: (context: RokuContext & {
   readonly password: string;
 }, outputPath: string) => Promise<string>;
+declare const captureScreenshot: (context: RokuContext & {
+  readonly password: string;
+}, outputPath: string, options?: ScreenshotCaptureOptions) => Promise<string>;
 declare const packageChannel: (outputPath: string, rootDir?: string) => Promise<PackageResult>;
 declare const validateEcpPath: (path: string) => string;
 declare const validateRemoteKey: (key: string) => void;
@@ -159,4 +168,4 @@ declare const buildDebugCommand: (command: string, args: readonly string[]) => R
 declare const runDebugCommand: (context: RokuContext, command: RokuDebugCommand, durationMs: number, idleTimeoutMs: number) => Promise<DebugCommandResult>;
 declare const captureDebugConsole: (context: RokuContext, durationMs: number) => Promise<DebugConsoleCapture>;
 //#endregion
-export { type ActiveApp, type DebugCommandResult, type DebugConsoleCapture, type DeviceSummary, type DiscoveredRokuDevice, type MediaPlayerInfo, type MediaPlayerState, type NodeExpectation, type NodeState, type PackageResult, type RemoteKey, type RetryOptions, type RokuContext, type RokuDebugCommand, type RokuDebugPort, type SceneGraphAssertion, type SceneGraphBounds, type SceneGraphPoint, type SceneGraphStatus, type WaitForSceneGraphAssertionOptions, assertMediaPlayerContainer, assertNamedNode, assertNamedNodeSize, assertNamedNodeState, assertNamedNodeText, assertNamedNodeTranslation, assertSceneGraphNode, assertSceneGraphNumberNear, buildDebugCommand, captureDebugConsole, checkDevice, discoverRokuDevices, escapeXmlAttribute, getDeviceInfo, installPackage, isActiveMediaPlayerState, isCompleteSceneGraph, isNamedNodeVisible, launchApp, packageChannel, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, queryMediaPlayer, queryMediaPlayerSafe, queryMediaPlayerXml, queryMediaPlayerXmlSafe, querySceneGraph, readActiveApp, readMediaPlayerContainer, readMediaPlayerInfo, readMediaPlayerPositionMs, readMediaPlayerState, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readSceneGraphFailure, readSceneGraphStatus, readXmlAttribute, readXmlTag, runDebugCommand, sceneGraphContainsText, takeScreenshot, validateEcpPath, validateRemoteKey, waitForActiveApp, waitForMediaPlayerState, waitForSceneGraphAssertion, waitForSceneGraphNode };
+export { type ActiveApp, type DebugCommandResult, type DebugConsoleCapture, type DeviceSummary, type DiscoveredRokuDevice, type MediaPlayerInfo, type MediaPlayerState, type NodeExpectation, type NodeState, type PackageResult, type RemoteKey, type RetryOptions, type RokuContext, type RokuDebugCommand, type RokuDebugPort, type SceneGraphAssertion, type SceneGraphBounds, type SceneGraphPoint, type SceneGraphStatus, type ScreenshotCaptureOptions, type WaitForSceneGraphAssertionOptions, assertMediaPlayerContainer, assertNamedNode, assertNamedNodeSize, assertNamedNodeState, assertNamedNodeText, assertNamedNodeTranslation, assertSceneGraphNode, assertSceneGraphNumberNear, buildDebugCommand, captureDebugConsole, captureScreenshot, checkDevice, discoverRokuDevices, escapeXmlAttribute, getDeviceInfo, installPackage, isActiveMediaPlayerState, isCompleteSceneGraph, isNamedNodeVisible, launchApp, packageChannel, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, queryMediaPlayer, queryMediaPlayerSafe, queryMediaPlayerXml, queryMediaPlayerXmlSafe, querySceneGraph, readActiveApp, readMediaPlayerContainer, readMediaPlayerInfo, readMediaPlayerPositionMs, readMediaPlayerState, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readSceneGraphFailure, readSceneGraphStatus, readXmlAttribute, readXmlTag, runDebugCommand, sceneGraphContainsText, takeScreenshot, validateEcpPath, validateRemoteKey, waitForActiveApp, waitForMediaPlayerState, waitForSceneGraphAssertion, waitForSceneGraphNode };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { $ as readNamedNodeBounds, A as readMediaPlayerInfo, B as waitForSceneGraphNode, C as queryEcp, D as queryMediaPlayerXmlSafe, E as queryMediaPlayerXml, F as validateEcpPath, G as assertNamedNodeTranslation, H as assertNamedNodeSize, I as validateRemoteKey, J as isCompleteSceneGraph, K as assertSceneGraphNumberNear, L as waitForActiveApp, M as readMediaPlayerState, O as querySceneGraph, P as takeScreenshot, Q as readNamedNodeAttributes, R as waitForMediaPlayerState, S as queryActiveApp, T as queryMediaPlayerSafe, U as assertNamedNodeState, V as assertNamedNode, W as assertNamedNodeText, X as parseSceneGraphNumberList, Y as isNamedNodeVisible, Z as readNamedNodeAttribute, _ as installPackage, at as readActiveApp, b as packageChannel, et as readNamedNodeNumber, f as assertMediaPlayerContainer, g as getDeviceInfo, h as discoverRokuDevices, it as sceneGraphContainsText, j as readMediaPlayerPositionMs, k as readMediaPlayerContainer, m as checkDevice, n as captureDebugConsole, nt as readSceneGraphFailure, ot as readXmlAttribute, p as assertSceneGraphNode, q as escapeXmlAttribute, r as runDebugCommand, rt as readSceneGraphStatus, st as readXmlTag, t as buildDebugCommand, tt as readNamedNodeTranslation, v as isActiveMediaPlayerState, w as queryMediaPlayer, x as pressKey, y as launchApp, z as waitForSceneGraphAssertion } from "./debug-af6vvS9T.mjs";
-export { assertMediaPlayerContainer, assertNamedNode, assertNamedNodeSize, assertNamedNodeState, assertNamedNodeText, assertNamedNodeTranslation, assertSceneGraphNode, assertSceneGraphNumberNear, buildDebugCommand, captureDebugConsole, checkDevice, discoverRokuDevices, escapeXmlAttribute, getDeviceInfo, installPackage, isActiveMediaPlayerState, isCompleteSceneGraph, isNamedNodeVisible, launchApp, packageChannel, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, queryMediaPlayer, queryMediaPlayerSafe, queryMediaPlayerXml, queryMediaPlayerXmlSafe, querySceneGraph, readActiveApp, readMediaPlayerContainer, readMediaPlayerInfo, readMediaPlayerPositionMs, readMediaPlayerState, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readSceneGraphFailure, readSceneGraphStatus, readXmlAttribute, readXmlTag, runDebugCommand, sceneGraphContainsText, takeScreenshot, validateEcpPath, validateRemoteKey, waitForActiveApp, waitForMediaPlayerState, waitForSceneGraphAssertion, waitForSceneGraphNode };
+import { $ as readNamedNodeAttributes, A as readMediaPlayerContainer, B as waitForSceneGraphAssertion, C as queryActiveApp, D as queryMediaPlayerXml, E as queryMediaPlayerSafe, F as takeScreenshot, G as assertNamedNodeText, H as assertNamedNode, I as validateEcpPath, J as escapeXmlAttribute, K as assertNamedNodeTranslation, L as validateRemoteKey, M as readMediaPlayerPositionMs, N as readMediaPlayerState, O as queryMediaPlayerXmlSafe, Q as readNamedNodeAttribute, R as waitForActiveApp, S as pressKey, T as queryMediaPlayer, U as assertNamedNodeSize, V as waitForSceneGraphNode, W as assertNamedNodeState, X as isNamedNodeVisible, Y as isCompleteSceneGraph, Z as parseSceneGraphNumberList, _ as getDeviceInfo, at as sceneGraphContainsText, b as launchApp, ct as readXmlTag, et as readNamedNodeBounds, f as assertMediaPlayerContainer, g as discoverRokuDevices, h as checkDevice, it as readSceneGraphStatus, j as readMediaPlayerInfo, k as querySceneGraph, m as captureScreenshot, n as captureDebugConsole, nt as readNamedNodeTranslation, ot as readActiveApp, p as assertSceneGraphNode, q as assertSceneGraphNumberNear, r as runDebugCommand, rt as readSceneGraphFailure, st as readXmlAttribute, t as buildDebugCommand, tt as readNamedNodeNumber, v as installPackage, w as queryEcp, x as packageChannel, y as isActiveMediaPlayerState, z as waitForMediaPlayerState } from "./debug-BbJdwNkW.mjs";
+export { assertMediaPlayerContainer, assertNamedNode, assertNamedNodeSize, assertNamedNodeState, assertNamedNodeText, assertNamedNodeTranslation, assertSceneGraphNode, assertSceneGraphNumberNear, buildDebugCommand, captureDebugConsole, captureScreenshot, checkDevice, discoverRokuDevices, escapeXmlAttribute, getDeviceInfo, installPackage, isActiveMediaPlayerState, isCompleteSceneGraph, isNamedNodeVisible, launchApp, packageChannel, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, queryMediaPlayer, queryMediaPlayerSafe, queryMediaPlayerXml, queryMediaPlayerXmlSafe, querySceneGraph, readActiveApp, readMediaPlayerContainer, readMediaPlayerInfo, readMediaPlayerPositionMs, readMediaPlayerState, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readSceneGraphFailure, readSceneGraphStatus, readXmlAttribute, readXmlTag, runDebugCommand, sceneGraphContainsText, takeScreenshot, validateEcpPath, validateRemoteKey, waitForActiveApp, waitForMediaPlayerState, waitForSceneGraphAssertion, waitForSceneGraphNode };

package/dist/rokit.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { B as waitForSceneGraphNode, C as queryEcp, I as validateRemoteKey, L as waitForActiveApp, N as resolvePackageOutputPath, O as querySceneGraph, P as takeScreenshot, R as waitForMediaPlayerState, S as queryActiveApp, _ as installPackage, a as loadEnv, b as packageChannel, c as requirePassword, ct as normalizeError, d as resolveOutputPath, g as getDeviceInfo, h as discoverRokuDevices, i as fail, l as requireTarget, lt as renderError, m as checkDevice, n as captureDebugConsole, nt as readSceneGraphFailure, o as loadLocalEnv, p as assertSceneGraphNode, r as runDebugCommand, rt as readSceneGraphStatus, s as rejectUnsafeEcpPath, t as buildDebugCommand, u as resolveFileOutputPath, w as queryMediaPlayer, x as pressKey, y as launchApp } from "./debug-af6vvS9T.mjs";
+import { C as queryActiveApp, L as validateRemoteKey, P as resolvePackageOutputPath, R as waitForActiveApp, S as pressKey, T as queryMediaPlayer, V as waitForSceneGraphNode, _ as getDeviceInfo, a as loadEnv, b as launchApp, c as requirePassword, d as resolveOutputPath, g as discoverRokuDevices, h as checkDevice, i as fail, it as readSceneGraphStatus, k as querySceneGraph, l as requireTarget, lt as normalizeError, m as captureScreenshot, n as captureDebugConsole, o as loadLocalEnv, p as assertSceneGraphNode, r as runDebugCommand, rt as readSceneGraphFailure, s as rejectUnsafeEcpPath, t as buildDebugCommand, u as resolveFileOutputPath, ut as renderError, v as installPackage, w as queryEcp, x as packageChannel, z as waitForMediaPlayerState } from "./debug-BbJdwNkW.mjs";
 import { createRequire } from "node:module";
 import { Effect } from "effect";
 import { mkdirSync, writeFileSync } from "node:fs";
@@ -255,8 +255,7 @@ const runCommand = async (context, command, dryRun) => {
 		const path = timestampOutputPath(resolveFileOutputPath(command.outputPath, "screenshot output path"));
 		if (dryRun) return dryRunResult(command.name, { path });
 		const password = requirePassword(deviceContext);
-		mkdirSync(dirname(path), { recursive: true });
-		const screenshotPath = await takeScreenshot({
+		const screenshotPath = await captureScreenshot({
 			...deviceContext,
 			password
 		}, path);
@@ -405,7 +404,7 @@ const writeProof = async (context, outputDir, includeScreenshot) => {
 	writeJson("media-player", await observe(async () => await queryMediaPlayer(context)));
 	if (includeScreenshot) {
 		const password = requirePassword(context);
-		const path = await takeScreenshot({
+		const path = await captureScreenshot({
 			...context,
 			password
 		}, timestampOutputPath(`${outputDir}/screenshot.png`));

package/docs/DISTRIBUTION.md

@@ -38,11 +38,11 @@ Release writes use the `putio-release-bot` installation token. The default `GITH
 
 ## Package Contents
 
-The npm package includes `dist`, `README.md`, `docs`, `examples`, `AGENTS.md`,
-`CONTRIBUTING.md`, and `SECURITY.md`. The docs and generic live probe are
-included so agents consuming the package can inspect readiness, distribution,
-security, and generic Roku proof mechanics without cloning extra private
-context.
+The npm package includes `dist`, `README.md`, `docs`, `examples`, `skills`,
+`AGENTS.md`, `CONTRIBUTING.md`, and `SECURITY.md`. The docs, consumer skill, and
+generic live probe are included so agents consuming the package can inspect
+readiness, distribution, security, and generic Roku proof mechanics without
+cloning extra private context.
 
 ## Release Smoke
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@putdotio/rokit",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "A tiny CLI companion for Roku device harness work.",
   "keywords": [
     "cli",
@@ -28,7 +28,8 @@
     "docs",
     "examples",
     "README.md",
-    "SECURITY.md"
+    "SECURITY.md",
+    "skills"
   ],
   "type": "module",
   "sideEffects": false,
@@ -57,19 +58,19 @@
     "verify": "vp check . && tsc --noEmit && vp run test && npm pack --dry-run"
   },
   "dependencies": {
-    "@effect/platform-node": "4.0.0-beta.66",
-    "effect": "4.0.0-beta.66",
-    "roku-deploy": "3.17.3"
+    "@effect/platform-node": "4.0.0-beta.69",
+    "effect": "4.0.0-beta.69",
+    "roku-deploy": "3.17.4"
   },
   "devDependencies": {
-    "@effect/vitest": "4.0.0-beta.66",
+    "@effect/vitest": "4.0.0-beta.69",
     "@types/node": "^25.8.0",
     "typescript": "^6.0.2",
-    "vite-plus": "^0.1.20",
+    "vite-plus": "^0.1.22",
     "vitest": "^4.1.6"
   },
   "engines": {
     "node": ">=24.14.0"
   },
-  "packageManager": "pnpm@11.0.0"
+  "packageManager": "pnpm@11.2.2"
 }

package/{docs/skills/rokit-harness → skills/rokit}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: rokit-harness
-description: Use rokit as a generic Roku harness adapter for packaging, installing, launching, key input, ECP/SceneGraph/media-player observation, readiness waits, debug console capture, screenshots, and proof bundles.
+name: rokit
+description: Use when testing, sideloading, deploying, or debugging Roku apps with rokit, including package/install/launch flows, remote key input, BrightScript console capture, ECP/SceneGraph/media-player observation, screenshots, readiness waits, and proof bundles.
 ---
 
-# rokit Harness
+# rokit
 
 Use this skill when a repo consumes `@putdotio/rokit` for Roku device harness
 work. Keep `rokit` generic and put app journeys, product selectors, fixture
@@ -33,6 +33,18 @@ repo.
 9. Use `rokit press --until-node ...` for bounded navigation loops instead of
    arbitrary sleeps.
 
+## Common Commands
+
+```bash
+rokit describe
+rokit --json snapshot --fields command,status,data.activeApp,data.mediaPlayer
+rokit --dry-run package --out artifacts/live/channel.zip
+rokit --dry-run launch dev
+rokit --json proof artifacts/live/proof --screenshot
+rokit --input-json '{"command":"press","keys":["Down","Select"]}'
+rokit console artifacts/live/console.log --duration-ms 30000
+```
+
 ## Boundaries
 
 - Device IPs, developer passwords, screenshots, packages, and proof bundles stay