From 5221cc10bd650067fabaaf8b271dbcd7a83442d8 Mon Sep 17 00:00:00 2001
From: Kurtis Jantzen <kurtis@telemetrytv.com>
Date: Thu, 10 Sep 2026 16:00:01 -0700
Subject: [PATCH] Add editable playlist preparation and resumable screen
 publishing

---
 src/adapters/protocol.test.ts   |   6 +-
 src/app-output.test.ts          |   2 +-
 src/argv.ts                     |   2 +
 src/authoring-input.ts          |  44 ++++++++++
 src/cli-commands/app.ts         |   2 +-
 src/cli-commands/kv.ts          |   4 +-
 src/cli-commands/media.ts       |  11 ++-
 src/cli-commands/playlist.ts    |  27 ++++--
 src/cli-commands/screen.ts      |  22 +++--
 src/cli-errors.ts               |   8 +-
 src/cli.test.ts                 |  64 +++++++-------
 src/command-input.ts            |  12 +++
 src/command-path.ts             |   2 +-
 src/command-tree.ts             |   1 +
 src/commander.test.ts           |   6 +-
 src/commands.ts                 |  82 ++++++++++++-----
 src/help.test.ts                |   4 +-
 src/if-match.ts                 |   2 +-
 src/localhost-smoke.ts          |  26 +++---
 src/native-program.test.ts      |   2 +-
 src/playlist-authoring.ts       |  62 +++++++++++++
 src/playlist-bundle.test.ts     |  10 +--
 src/playlist-bundle.ts          |   6 +-
 src/playlist-workflows.test.ts  | 150 ++++++++++++++++++++++++++++++++
 src/program.ts                  |   2 +
 src/runtime.ts                  |   4 +
 src/screen-publish.ts           | 107 +++++++++++++++++++++++
 src/server-smoke.ts             |  26 +++---
 src/validate-invocation.test.ts |   8 +-
 29 files changed, 577 insertions(+), 127 deletions(-)
 create mode 100644 src/authoring-input.ts
 create mode 100644 src/playlist-authoring.ts
 create mode 100644 src/playlist-workflows.test.ts
 create mode 100644 src/screen-publish.ts

diff --git a/src/adapters/protocol.test.ts b/src/adapters/protocol.test.ts
index 9fe914be..fbfb5f89 100644
--- a/src/adapters/protocol.test.ts
+++ b/src/adapters/protocol.test.ts
@@ -412,7 +412,7 @@ test("screen observation is optional, read-only, and absent from ScreenPatch", (
   // The CLI reads observation from GET /api/v1/screens/{id}. Players PUT the
   // runtime route; this command surface must not.
   assert.doesNotMatch(commands, /\/runtime\/v1\/observation/);
-  assert.match(commands, /screen update requires <id>, --if-match, and --name, --playlist-id, or --timezone/);
+  assert.match(commands, /screen update requires <id>, --expect-rev, and --name, --playlist-id, or --timezone/);
 });
 
 test("screen online is required, last_online_at and last_ip are optional, and ScreenPatch cannot write them", () => {
@@ -448,7 +448,7 @@ test("screen online is required, last_online_at and last_ip are optional, and Sc
   assert.match(screenSchema, /maxLength: 45/);
   assert.match(screenSchema, /ScreenPatch, pairing bodies, session[\s\S]*runtime manifest\s+body cannot write it/);
   assert.doesNotMatch(commands, /--online|--last-online-at|--last-ip/);
-  assert.match(commands, /screen update requires <id>, --if-match, and --name, --playlist-id, or --timezone/);
+  assert.match(commands, /screen update requires <id>, --expect-rev, and --name, --playlist-id, or --timezone/);
 });
 
 test("published problem codes include payment_required and dependency_timeout", () => {
@@ -872,7 +872,7 @@ test("opaque agent comments are optional on GET resources, dedicated comment rou
         assert.equal(options.has(name), action === "set");
         if (action === "set") assert.equal(options.get(name)?.type, "value");
       }
-      assert.equal(options.has("--if-match"), false);
+      assert.equal(options.has("--expect-rev"), false);
       assert.equal(options.has("--value-base64"), false);
     }
   }
diff --git a/src/app-output.test.ts b/src/app-output.test.ts
index a9db4e73..d4ebb334 100644
--- a/src/app-output.test.ts
+++ b/src/app-output.test.ts
@@ -34,7 +34,7 @@ for (const action of ["upload", "update"] as const) {
       const stdout = new Writable({ write(chunk, _encoding, callback) { output += chunk; callback(); } });
       const stderr = new Writable({ write(_chunk, _encoding, callback) { callback(); } });
       const argv = ["--json", "app", action,
-        ...(action === "update" ? ["app_EXISTING", appDir, "--if-match", "7"] : [appDir]),
+        ...(action === "update" ? ["app_EXISTING", appDir, "--expect-rev", "7"] : [appDir]),
         ...(noWait ? ["--no-wait"] : ["--poll-ms", "1"]),
       ];
       const code = await run({
diff --git a/src/argv.ts b/src/argv.ts
index 75b4a351..3061622e 100644
--- a/src/argv.ts
+++ b/src/argv.ts
@@ -1,3 +1,4 @@
+import { normalizeRevisionArgs } from "./command-input.js";
 import { CommanderError } from "commander";
 import { commandInput, createCommandTree } from "./command-tree.js";
 import type { ParsedArgs } from "./command-input.js";
@@ -7,6 +8,7 @@ export { flagString, flagBool, flagNumber, type ParsedArgs } from "./command-inp
 
 /** Inspect the same native command tree without executing an application handler. */
 export function parseArgv(argv: string[]): ParsedArgs & { help?: HelpDocument } {
+  argv = normalizeRevisionArgs(argv);
   const tree = createCommandTree(argv);
   try {
     tree.root.parse(argv, { from: "user" });
diff --git a/src/authoring-input.ts b/src/authoring-input.ts
new file mode 100644
index 00000000..77107f4b
--- /dev/null
+++ b/src/authoring-input.ts
@@ -0,0 +1,44 @@
+import { open } from "node:fs/promises";
+import path from "node:path";
+import type { CliRuntime } from "./runtime.js";
+import { usageError } from "./problems.js";
+
+const MAX_INPUT_BYTES = 8 * 1024 * 1024;
+export async function readAuthoringText(file: string, runtime: CliRuntime, maxBytes = MAX_INPUT_BYTES): Promise<string> {
+  try {
+    if (file !== "-") {
+      const handle = await open(path.resolve(runtime.cwd(), file), "r");
+      try {
+        if ((await handle.stat()).size > maxBytes) throw usageError("Input exceeds its size limit.");
+        let size = 0; const chunks: Buffer[] = [];
+        for await (const chunk of handle.createReadStream({ autoClose: false })) {
+          size += chunk.length;
+          if (size > maxBytes) throw usageError("Input exceeds its size limit.");
+          chunks.push(chunk);
+        }
+        return Buffer.concat(chunks).toString("utf8");
+      } finally { await handle.close(); }
+    }
+    if (!runtime.stdin || runtime.isStdinTty?.()) throw usageError("Pipe input when using '-'.");
+    let size = 0; const chunks: Buffer[] = [];
+    for await (const chunk of runtime.stdin) {
+      const bytes = Buffer.from(chunk); size += bytes.length;
+      if (size > maxBytes) throw usageError("Input exceeds its size limit.");
+      chunks.push(bytes);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+  } catch { throw usageError("Cannot read input; provide a readable file or pipe, within the size limit."); }
+}
+export async function readAuthoringJson(file: string, runtime: CliRuntime): Promise<any> {
+  const text = await readAuthoringText(file, runtime);
+  try { return JSON.parse(text); } catch { throw usageError("Input is not valid JSON."); }
+}
+/** Exclusive creation keeps a prepared document safe from accidental replacement. */
+export async function writeAuthoringJson(file: string, document: unknown, runtime: CliRuntime): Promise<string> {
+  const output = path.resolve(runtime.cwd(), file);
+  try {
+    const handle = await open(output, "wx", 0o600);
+    try { await handle.writeFile(JSON.stringify(document, null, 2) + "\n"); } finally { await handle.close(); }
+  } catch { throw usageError("Cannot create output; choose a new file in an existing directory."); }
+  return output;
+}
diff --git a/src/cli-commands/app.ts b/src/cli-commands/app.ts
index 1eaa04d3..7f8d34de 100644
--- a/src/cli-commands/app.ts
+++ b/src/cli-commands/app.ts
@@ -21,7 +21,7 @@ export function registerAppCommands(root: Command, bind: CommandActionBinder): v
   app.command("update").description("Update an application")
     .argument("<id>", "Application identifier")
     .argument("<directory>", "Local directory")
-    .requiredOption("--if-match <REVISION>", "Require the current resource revision (required)", revision)
+    .requiredOption("--expect-rev <REVISION>", "Require the current resource revision (required)", revision)
     .option("--no-wait", "Return after acceptance without waiting for processing")
     .option("--poll-ms <MS>", "Set the operation polling interval", positiveInteger("poll-ms"))
     .action(bind(handleAppUpdate));
diff --git a/src/cli-commands/kv.ts b/src/cli-commands/kv.ts
index 1bf27dad..e4502295 100644
--- a/src/cli-commands/kv.ts
+++ b/src/cli-commands/kv.ts
@@ -18,13 +18,13 @@ export function registerKvCommands(root: Command, bind: CommandActionBinder): vo
     .addOption(new Option("--file <FILE>", "Read the value from a file").conflicts(["jsonValue", "valueBase64"]))
     .addOption(new Option("--value-base64 <BASE64>", "Supply canonical base64 bytes (may be empty)").conflicts(["jsonValue", "file"]))
     .addOption(new Option("--content-type <TYPE>", "Declare the content MIME type").conflicts(["jsonValue"]))
-    .option("--if-match <REVISION>", "Require the current resource revision", revision)
+    .option("--expect-rev <REVISION>", "Require the current resource revision", revision)
     .action(bind(handleKvSet));
 
   kv.command("delete").description("Delete an application key")
     .argument("<key>", "Application key")
     .requiredOption("--application-id <ID>", "Select the application's K/V namespace (required)")
-    .requiredOption("--if-match <REVISION>", "Require the current resource revision (required)", revision)
+    .requiredOption("--expect-rev <REVISION>", "Require the current resource revision (required)", revision)
     .action(bind(handleKvDelete));
 
   kv.command("list").description("List application keys")
diff --git a/src/cli-commands/media.ts b/src/cli-commands/media.ts
index bdda364c..c61d0b16 100644
--- a/src/cli-commands/media.ts
+++ b/src/cli-commands/media.ts
@@ -1,3 +1,4 @@
+import { usageError } from "../problems.js";
 import { positiveInteger, positiveNumber, revision } from "./options.js";
 import type { CommandActionBinder } from "./types.js";
 import { handleMediaGenerate, handleMediaUpload, handleMediaUploadBatch, handleMediaShow, handleMediaDownload, handleMediaList, handleMediaUpdate, handleMediaDelete } from "../commands.js";
@@ -9,11 +10,15 @@ export function registerMediaCommands(root: Command, bind: CommandActionBinder):
   const media = root.command("media").description("Generate, upload, and manage images and videos");
 
   addCommandNotes(media.command("generate").description("Generate an image from a prompt")
-    .requiredOption("--prompt <TEXT>", "Describe the complete image to generate (required)")
+    .addOption(new Option("--prompt <TEXT>", "Describe the complete image to generate").conflicts("promptFile"))
+    .addOption(new Option("--prompt-file <FILE>", "Read the complete prompt from a file or stdin (-)").conflicts("prompt"))
     .option("--aspect-ratio <RATIO>", "Choose the generated image aspect ratio")
     .option("--quality <low|medium|high>", "Choose generation quality")
     .option("--tag <TAG>", "Set the media tag")
     .option("--no-progress", "Suppress stderr progress")
+    .hook("preAction", (command) => {
+      if (command.getOptionValue("prompt") === undefined && command.getOptionValue("promptFile") === undefined) throw usageError("Provide --prompt TEXT or --prompt-file FILE.");
+    })
     .action(bind(handleMediaGenerate)), CREDIT_HELP);
 
   media.command("upload").description("Upload an image or video")
@@ -66,11 +71,11 @@ export function registerMediaCommands(root: Command, bind: CommandActionBinder):
     .argument("<id>", "Media identifier")
     .addOption(new Option("--tag <TAG>", "Set the media tag").conflicts(["clearTag"]))
     .addOption(new Option("--clear-tag", "Remove the media tag").conflicts(["tag"]))
-    .requiredOption("--if-match <REVISION>", "Require the current resource revision (required)", revision)
+    .requiredOption("--expect-rev <REVISION>", "Require the current resource revision (required)", revision)
     .action(bind(handleMediaUpdate));
 
   media.command("delete").description("Delete media")
     .argument("<id>", "Media identifier")
-    .requiredOption("--if-match <REVISION>", "Require the current resource revision (required)", revision)
+    .requiredOption("--expect-rev <REVISION>", "Require the current resource revision (required)", revision)
     .action(bind(handleMediaDelete));
 }
diff --git a/src/cli-commands/playlist.ts b/src/cli-commands/playlist.ts
index e768c507..ed665eb9 100644
--- a/src/cli-commands/playlist.ts
+++ b/src/cli-commands/playlist.ts
@@ -1,7 +1,7 @@
 import { usageError } from "../problems.js";
 import { nonnegativeInteger, positiveInteger, revision } from "./options.js";
 import type { CommandActionBinder } from "./types.js";
-import { handlePlaylistValidate, handlePlaylistPreview, handlePlaylistTemplates, handlePlaylistCreate, handlePlaylistUpdate, handlePlaylistExport, handlePlaylistImport, handlePlaylistShow, handlePlaylistList, handlePlaylistDelete } from "../commands.js";
+import { handlePlaylistInit, handlePlaylistValidate, handlePlaylistPreview, handlePlaylistTemplates, handlePlaylistCreate, handlePlaylistUpdate, handlePlaylistExport, handlePlaylistImport, handlePlaylistShow, handlePlaylistList, handlePlaylistDelete } from "../commands.js";
 import type { Command } from "commander";
 import { addCommandNotes } from "./notes.js";
 import { LOOK_AT_THE_CONTACT_SHEET } from "../playlist-preview.js";
@@ -9,6 +9,17 @@ import { LOOK_AT_THE_CONTACT_SHEET } from "../playlist-preview.js";
 export function registerPlaylistCommands(root: Command, bind: CommandActionBinder): void {
   const playlist = root.command("playlist").description("Author, validate, preview, and manage playlists");
 
+  playlist.command("init").description("Prepare an editable full-screen playlist from ready media")
+    .argument("<media-ids...>", "Media identifiers in playback order")
+    .requiredOption("--name <NAME>", "Playlist name")
+    .requiredOption("--output <FILE>", "Create an editable playlist file")
+    .option("--screen <ID>", "Use this screen's reported playback dimensions")
+    .option("--target-width <PX>", "Override canvas width", positiveInteger("target-width"))
+    .option("--target-height <PX>", "Override canvas height", positiveInteger("target-height"))
+    .option("--duration-ms <MS>", "Image page duration (default: 8000)", positiveInteger("duration-ms"))
+    .option("--fit <FIT>", "Content fit: contain (default), cover, or fill")
+    .action(bind(handlePlaylistInit));
+
   playlist.command("validate").description("Validate a playlist file")
     .argument("<file>", "Local input file")
     .option("--lint-only", "Run the command's local validation/lint mode")
@@ -32,7 +43,7 @@ export function registerPlaylistCommands(root: Command, bind: CommandActionBinde
   playlist.command("update").description("Update a playlist")
     .argument("<id>", "Playlist identifier")
     .argument("<file>", "Local input file")
-    .requiredOption("--if-match <REVISION>", "Require the current resource revision (required)", revision)
+    .requiredOption("--expect-rev <REVISION>", "Require the current resource revision (required)", revision)
     .action(bind(handlePlaylistUpdate));
 
   playlist.command("export").description("Export a playlist bundle")
@@ -44,16 +55,18 @@ export function registerPlaylistCommands(root: Command, bind: CommandActionBinde
     .argument("<directory>", "Local directory")
     .option("--name <NAME>", "Set the imported playlist name")
     .option("--update <ID>", "Update this playlist when importing")
-    .option("--if-match <REVISION>", "Require the current resource revision", revision)
+    .option("--expect-rev <REVISION>", "Require the current resource revision", revision)
     .option("--poll-ms <MS>", "Set the operation polling interval", positiveInteger("poll-ms"))
     .hook("preAction", (command) => {
       const update = command.getOptionValueSource("update") === "cli";
-      const ifMatch = command.getOptionValueSource("ifMatch") === "cli";
-      if (update !== ifMatch) throw usageError("playlist import --update and --if-match must be supplied together.");
+      const ifMatch = command.getOptionValueSource("expectRev") === "cli";
+      if (update !== ifMatch) throw usageError("playlist import --update and --expect-rev must be supplied together.");
     })
     .action(bind(handlePlaylistImport));
 
-  playlist.command("show").description("Inspect a playlist")
+  playlist.command("show").description("Inspect a playlist or write an editable document")
+    .option("--output <FILE>", "Create an editable playlist file; report its revision on stdout")
+    .option("--editable", "Return an editable document and revision in the JSON envelope")
     .alias("get")
     .argument("<id>", "Playlist identifier")
     .action(bind(handlePlaylistShow));
@@ -63,6 +76,6 @@ export function registerPlaylistCommands(root: Command, bind: CommandActionBinde
 
   playlist.command("delete").description("Delete a playlist")
     .argument("<id>", "Playlist identifier")
-    .requiredOption("--if-match <REVISION>", "Require the current resource revision (required)", revision)
+    .requiredOption("--expect-rev <REVISION>", "Require the current resource revision (required)", revision)
     .action(bind(handlePlaylistDelete));
 }
diff --git a/src/cli-commands/screen.ts b/src/cli-commands/screen.ts
index 306409a9..388047fa 100644
--- a/src/cli-commands/screen.ts
+++ b/src/cli-commands/screen.ts
@@ -1,11 +1,17 @@
 import { positiveInteger, revision, toastDuration } from "./options.js";
 import type { CommandActionBinder } from "./types.js";
-import { handleScreenPair, handleScreenProvision, handleScreenUpdate, handleScreenList, handleScreenShow, handleScreenAssign, handleScreenSetTimezone, handleScreenArchive, handleScreenUnarchive, handleScreenDelete, handleScreenRotatePublicId, handleScreenToast, handleScreenScreenshot } from "../commands.js";
+import { handleScreenPublish, handleScreenPair, handleScreenProvision, handleScreenUpdate, handleScreenList, handleScreenShow, handleScreenAssign, handleScreenSetTimezone, handleScreenArchive, handleScreenUnarchive, handleScreenDelete, handleScreenRotatePublicId, handleScreenToast, handleScreenScreenshot } from "../commands.js";
 import type { Command } from "commander";
 
 export function registerScreenCommands(root: Command, bind: CommandActionBinder): void {
   const screen = root.command("screen").description("Pair, configure, and inspect screens");
 
+  screen.command("publish").description("Create a prepared playlist and assign it, with resumable recovery")
+    .argument("<id>", "Screen identifier")
+    .argument("<file>", "Prepared playlist file, or - for stdin")
+    .requiredOption("--expect-rev <REVISION>", "Expected screen revision", revision)
+    .action(bind(handleScreenPublish));
+
   screen.command("pair").description("Claim a Player pairing code")
     .argument("<code>", "Player pairing code")
     .option("--label <LABEL>", "Set the screen label")
@@ -22,7 +28,7 @@ export function registerScreenCommands(root: Command, bind: CommandActionBinder)
     .option("--name <NAME>", "Set the screen name")
     .option("--playlist-id <ID>", "Select the playlist to assign")
     .option("--timezone <ZONE>", "Set an IANA timezone")
-    .requiredOption("--if-match <REVISION>", "Require the current resource revision (required)", revision)
+    .requiredOption("--expect-rev <REVISION>", "Require the current resource revision (required)", revision)
     .action(bind(handleScreenUpdate));
 
   screen.command("list").description("List screens")
@@ -36,33 +42,33 @@ export function registerScreenCommands(root: Command, bind: CommandActionBinder)
   screen.command("assign").description("Assign a playlist to a screen")
     .argument("<id>", "Screen identifier")
     .requiredOption("--playlist-id <ID>", "Select the playlist to assign (required)")
-    .requiredOption("--if-match <REVISION>", "Require the current resource revision (required)", revision)
+    .requiredOption("--expect-rev <REVISION>", "Require the current resource revision (required)", revision)
     .action(bind(handleScreenAssign));
 
   screen.command("set-timezone").description("Set a screen's timezone")
     .argument("<id>", "Screen identifier")
     .requiredOption("--timezone <ZONE>", "Set an IANA timezone (required)")
-    .requiredOption("--if-match <REVISION>", "Require the current resource revision (required)", revision)
+    .requiredOption("--expect-rev <REVISION>", "Require the current resource revision (required)", revision)
     .action(bind(handleScreenSetTimezone));
 
   screen.command("archive").description("Archive a screen")
     .argument("<id>", "Screen identifier")
-    .requiredOption("--if-match <REVISION>", "Require the current resource revision (required)", revision)
+    .requiredOption("--expect-rev <REVISION>", "Require the current resource revision (required)", revision)
     .action(bind(handleScreenArchive));
 
   screen.command("unarchive").description("Restore an archived screen")
     .argument("<id>", "Screen identifier")
-    .requiredOption("--if-match <REVISION>", "Require the current resource revision (required)", revision)
+    .requiredOption("--expect-rev <REVISION>", "Require the current resource revision (required)", revision)
     .action(bind(handleScreenUnarchive));
 
   screen.command("delete").description("Delete a screen")
     .argument("<id>", "Screen identifier")
-    .requiredOption("--if-match <REVISION>", "Require the current resource revision (required)", revision)
+    .requiredOption("--expect-rev <REVISION>", "Require the current resource revision (required)", revision)
     .action(bind(handleScreenDelete));
 
   screen.command("rotate-public-id").description("Rotate a screen's public identifier")
     .argument("<id>", "Screen identifier")
-    .requiredOption("--if-match <REVISION>", "Require the current resource revision (required)", revision)
+    .requiredOption("--expect-rev <REVISION>", "Require the current resource revision (required)", revision)
     .action(bind(handleScreenRotatePublicId));
 
   screen.command("toast").description("Show a temporary screen message")
diff --git a/src/cli-errors.ts b/src/cli-errors.ts
index eda0ef17..12e1220e 100644
--- a/src/cli-errors.ts
+++ b/src/cli-errors.ts
@@ -7,10 +7,10 @@ export function commandError(error: CommanderError, command: Command): never {
   const path = commandPath(command).join(" ");
   // Preserve actionable migration hints using only known command/flag names.
   const has = (flag: string) => command.args.some((arg) => arg === `--${flag}` || arg.startsWith(`--${flag}=`));
-  if (path === "screen" && command.args[0] === "revoke-credential") throw usageError("screen revoke-credential is retired. Archive the screen instead.", { command: "screenrig screen archive <id> --if-match REVISION", reason: "Archive hides the screen; it does not unbind the player." });
+  if (path === "screen" && command.args[0] === "revoke-credential") throw usageError("screen revoke-credential is retired. Archive the screen instead.", { command: "screenrig screen archive <id> --expect-rev REVISION", reason: "Archive hides the screen; it does not unbind the player." });
   if (path.startsWith("comment ")) {
     if (command.commands.length) throw usageError("comment commands require screen <id> or playlist <id>.");
-    if (has("if-match")) throw usageError("comment commands do not take --if-match; last write wins and does not bump revision.");
+    if (has("expect-rev")) throw usageError("comment commands do not take --expect-rev; last write wins and does not bump revision.");
     if (has("page") && command.name() === "screen") throw usageError("comment screen commands do not take --page; use comment playlist <id> --page PAGE_ID.");
     if (has("value-base64")) throw usageError("comment set requires --json-value or --file.");
     if (error.code === "commander.conflictingOption") throw usageError("comment set requires exactly one of --json-value or --file.");
@@ -18,14 +18,14 @@ export function commandError(error: CommanderError, command: Command): never {
   if (path === "media list" && has("kind")) throw usageError("media list uses --primitive image|video, not --kind.");
   switch (error.code) {
     case "commander.missingArgument":
-      if (path === "screen set-timezone") throw usageError("screen set-timezone requires <id> --timezone --if-match.");
+      if (path === "screen set-timezone") throw usageError("screen set-timezone requires <id> --timezone --expect-rev.");
       throw usageError(`${path} requires ${command.registeredArguments.filter((arg) => arg.required).map((arg) => `<${arg.name()}>`).join(" ")}.`);
     case "commander.excessArguments":
       throw usageError(`${path || "screenrig"} does not accept ${command.registeredArguments.length ? "extra" : "positional"} arguments.`);
     case "commander.conflictingOption":
       throw usageError("Conflicting options. See command help.");
     case "commander.missingMandatoryOptionValue": {
-      if (path === "screen set-timezone") throw usageError("screen set-timezone requires <id> --timezone --if-match.");
+      if (path === "screen set-timezone") throw usageError("screen set-timezone requires <id> --timezone --expect-rev.");
       const required = command.options.filter((option) => option.mandatory && command.getOptionValue(option.attributeName()) === undefined);
       const positional = command.registeredArguments.filter((arg, index) => arg.required && index >= command.args.length).map((arg) => `<${arg.name()}>`);
       throw usageError(`${path} requires ${[...positional, ...required.map((option) => option.long)].join(" ")}.`);
diff --git a/src/cli.test.ts b/src/cli.test.ts
index 306c3e41..c0a2bd2a 100644
--- a/src/cli.test.ts
+++ b/src/cli.test.ts
@@ -3848,7 +3848,7 @@ test("comment set rejects non-objects, oversize payloads, and last-write-wins fl
       [["comment", "set", "screen", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--json-value", "[]"], /JSON object/],
       [["comment", "set", "screen", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--json-value", '{"note":"x"}', "--file", "x.json"], /exactly one of --json-value or --file/],
       [["comment", "set", "screen", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--value-base64", "e30="], /--json-value or --file/],
-      [["comment", "set", "screen", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--json-value", '{"note":"x"}', "--if-match", "1"], /do not take --if-match/],
+      [["comment", "set", "screen", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--json-value", '{"note":"x"}', "--expect-rev", "1"], /do not take --expect-rev/],
       [["comment", "set", "screen", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--page", "poster", "--json-value", '{"note":"x"}'], /do not take --page/],
       [["comment", "show", "playlist", "pl_AAAAAAAAAAAAAAAAAAAAAAAA", "--page", "1poster"], /playlist page id/],
       [["comment", "set", "screen", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--json-value", `{"x":"${"a".repeat(1017)}"}`], /1024 bytes/],
@@ -4076,7 +4076,7 @@ test("media, operation, screen credential, and K/V revision commands bind the fr
 
     result = await withRuntime(["--json", "media", "show", "med_AAAAAAAAAAAAAAAAAAAAAAAA"], transport, runtimeExtra);
     assert.equal(result.code, 0, result.stdout);
-    result = await withRuntime(["--json", "media", "delete", "med_AAAAAAAAAAAAAAAAAAAAAAAA", "--if-match", "1"], transport, runtimeExtra);
+    result = await withRuntime(["--json", "media", "delete", "med_AAAAAAAAAAAAAAAAAAAAAAAA", "--expect-rev", "1"], transport, runtimeExtra);
     assert.equal(result.code, 0, result.stdout);
     assert.equal(transport.calls.at(-1)?.headers?.["if-match"], '"1"');
 
@@ -4086,10 +4086,10 @@ test("media, operation, screen credential, and K/V revision commands bind the fr
 
     result = await withRuntime(["--json", "screen", "pair", "ABC234"], transport, runtimeExtra);
     const paired = (JSON.parse(result.stdout) as { data: { screen: { id: string; revision: number } } }).data.screen;
-    result = await withRuntime(["--json", "screen", "rotate-public-id", paired.id, "--if-match", String(paired.revision)], transport, runtimeExtra);
+    result = await withRuntime(["--json", "screen", "rotate-public-id", paired.id, "--expect-rev", String(paired.revision)], transport, runtimeExtra);
     assert.equal(result.code, 0, result.stdout);
     const rotated = (JSON.parse(result.stdout) as { data: { revision: number } }).data;
-    result = await withRuntime(["--json", "screen", "archive", paired.id, "--if-match", String(rotated.revision)], transport, runtimeExtra);
+    result = await withRuntime(["--json", "screen", "archive", paired.id, "--expect-rev", String(rotated.revision)], transport, runtimeExtra);
     assert.equal(result.code, 0, result.stdout);
     assert.equal(transport.calls.at(-1)?.path, `/api/v1/screens/${paired.id}/archive`);
 
@@ -4104,10 +4104,10 @@ test("media, operation, screen credential, and K/V revision commands bind the fr
 
     result = await withRuntime(["--json", "kv", "set", "settings", "--application-id", "app_AAAAAAAAAAAAAAAAAAAAAAAA", "--json-value", '{"v":1}'], transport, runtimeExtra);
     assert.equal(result.code, 0, result.stdout);
-    result = await withRuntime(["--json", "kv", "set", "settings", "--application-id", "app_AAAAAAAAAAAAAAAAAAAAAAAA", "--json-value", '{"v":2}', "--if-match", "1"], transport, runtimeExtra);
+    result = await withRuntime(["--json", "kv", "set", "settings", "--application-id", "app_AAAAAAAAAAAAAAAAAAAAAAAA", "--json-value", '{"v":2}', "--expect-rev", "1"], transport, runtimeExtra);
     assert.equal(result.code, 0, result.stdout);
     assert.equal(transport.calls.at(-1)?.headers?.["if-match"], '"1"');
-    result = await withRuntime(["--json", "kv", "set", "settings", "--application-id", "app_AAAAAAAAAAAAAAAAAAAAAAAA", "--json-value", '{"v":3}', "--if-match", "1"], transport, runtimeExtra);
+    result = await withRuntime(["--json", "kv", "set", "settings", "--application-id", "app_AAAAAAAAAAAAAAAAAAAAAAAA", "--json-value", '{"v":3}', "--expect-rev", "1"], transport, runtimeExtra);
     assert.equal(result.code, ExitCode.Precondition);
     assert.equal((JSON.parse(result.stdout) as { error: { current_revision: number } }).error.current_revision, 2);
   } finally {
@@ -4139,7 +4139,7 @@ test("screen archive, unarchive, archived list, and retired unbind drive the rea
     );
 
     const archived = await withRuntime(
-      ["--json", "screen", "archive", screen.id, "--if-match", String(screen.revision)],
+      ["--json", "screen", "archive", screen.id, "--expect-rev", String(screen.revision)],
       transport,
       { fs: fsLike },
     );
@@ -4170,7 +4170,7 @@ test("screen archive, unarchive, archived list, and retired unbind drive the rea
     assert.equal((JSON.parse(shown.stdout) as { data: { state: string } }).data.state, "archived");
 
     const unarchived = await withRuntime(
-      ["--json", "screen", "unarchive", screen.id, "--if-match", String(archivedScreen.revision)],
+      ["--json", "screen", "unarchive", screen.id, "--expect-rev", String(archivedScreen.revision)],
       transport,
       { fs: fsLike },
     );
@@ -4191,7 +4191,7 @@ test("screen archive, unarchive, archived list, and retired unbind drive the rea
 
     const callsBeforeDelete = transport.calls.length;
     const deleted = await withRuntime(
-      ["--json", "screen", "delete", screen.id, "--if-match", String(restored.revision)],
+      ["--json", "screen", "delete", screen.id, "--expect-rev", String(restored.revision)],
       transport,
       { fs: fsLike },
     );
@@ -4210,7 +4210,7 @@ test("screen archive, unarchive, archived list, and retired unbind drive the rea
 
     const callsBeforeRevoke = transport.calls.length;
     const revoked = await withRuntime(
-      ["--json", "screen", "revoke-credential", screen.id, "--if-match", String(restored.revision)],
+      ["--json", "screen", "revoke-credential", screen.id, "--expect-rev", String(restored.revision)],
       transport,
       { fs: fsLike },
     );
@@ -4308,7 +4308,7 @@ test("screen set-timezone patches only the timezone and carries the revision", a
   const transport = memoryBackend();
   const { configDir, fsLike } = await scheduledPlaylistFixture(false, "tz-set-");
   const result = await withRuntime(
-    ["--json", "screen", "set-timezone", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--timezone", "America/Los_Angeles", "--if-match", "1"],
+    ["--json", "screen", "set-timezone", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--timezone", "America/Los_Angeles", "--expect-rev", "1"],
     transport,
     { fs: fsLike },
   );
@@ -4328,7 +4328,7 @@ test("screen set-timezone forwards the identifier unchanged and never carries a
   // would go stale, so an unknown name must still reach the server to be
   // rejected there.
   await withRuntime(
-    ["--json", "screen", "set-timezone", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--timezone", "Mars/Olympus_Mons", "--if-match", "1"],
+    ["--json", "screen", "set-timezone", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--timezone", "Mars/Olympus_Mons", "--expect-rev", "1"],
     transport,
     { fs: fsLike },
   );
@@ -4341,15 +4341,15 @@ test("screen set-timezone rejects a missing id, zone, or revision", async () =>
   const transport = memoryBackend();
   const { configDir, fsLike } = await scheduledPlaylistFixture(false, "tz-usage-");
   for (const argv of [
-    ["screen", "set-timezone", "--timezone", "America/Los_Angeles", "--if-match", "1"],
-    ["screen", "set-timezone", "scr_1", "--if-match", "1"],
+    ["screen", "set-timezone", "--timezone", "America/Los_Angeles", "--expect-rev", "1"],
+    ["screen", "set-timezone", "scr_1", "--expect-rev", "1"],
     ["screen", "set-timezone", "scr_1", "--timezone", "America/Los_Angeles"],
   ]) {
     const result = await withRuntime(["--json", ...argv], transport, { fs: fsLike });
     assert.equal(result.code, ExitCode.Usage, `${argv.join(" ")}: ${result.stdout}`);
     const envelope = JSON.parse(result.stdout) as { error: { code: string; detail: string } };
     assert.equal(envelope.error.code, "usage_error");
-    assert.match(envelope.error.detail, /requires <id> --timezone --if-match/);
+    assert.match(envelope.error.detail, /requires <id> --timezone --expect-rev/);
   }
   // A rejected invocation never reaches the server.
   assert.equal(transport.calls.some((call) => call.method === "PATCH"), false);
@@ -4364,7 +4364,7 @@ test("assigning a scheduled playlist to a screen with no timezone is refused bef
   transport.calls.length = 0;
 
   const result = await withRuntime(
-    ["--json", "screen", "assign", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--playlist-id", "pl_AAAAAAAAAAAAAAAAAAAAAAAA", "--if-match", "1"],
+    ["--json", "screen", "assign", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--playlist-id", "pl_AAAAAAAAAAAAAAAAAAAAAAAA", "--expect-rev", "1"],
     transport,
     { fs: fsLike },
   );
@@ -4415,7 +4415,7 @@ test("a page disabled outright still counts as scheduled", async () => {
   await withRuntime(["--json", "playlist", "create", file], transport, { fs: fsLike });
 
   const result = await withRuntime(
-    ["--json", "screen", "assign", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--playlist-id", "pl_AAAAAAAAAAAAAAAAAAAAAAAA", "--if-match", "1"],
+    ["--json", "screen", "assign", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--playlist-id", "pl_AAAAAAAAAAAAAAAAAAAAAAAA", "--expect-rev", "1"],
     transport,
     { fs: fsLike },
   );
@@ -4430,7 +4430,7 @@ test("an unscheduled playlist assigns to a screen with no timezone", async () =>
   await withRuntime(["--json", "playlist", "create", file], transport, { fs: fsLike });
 
   const result = await withRuntime(
-    ["--json", "screen", "assign", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--playlist-id", "pl_AAAAAAAAAAAAAAAAAAAAAAAA", "--if-match", "1"],
+    ["--json", "screen", "assign", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--playlist-id", "pl_AAAAAAAAAAAAAAAAAAAAAAAA", "--expect-rev", "1"],
     transport,
     { fs: fsLike },
   );
@@ -4444,13 +4444,13 @@ test("a scheduled playlist assigns once the screen carries a timezone", async ()
   await withRuntime(["--json", "screen", "pair", "ABC234"], transport, { fs: fsLike });
   await withRuntime(["--json", "playlist", "create", file], transport, { fs: fsLike });
   await withRuntime(
-    ["--json", "screen", "set-timezone", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--timezone", "America/Los_Angeles", "--if-match", "1"],
+    ["--json", "screen", "set-timezone", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--timezone", "America/Los_Angeles", "--expect-rev", "1"],
     transport,
     { fs: fsLike },
   );
 
   const result = await withRuntime(
-    ["--json", "screen", "assign", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--playlist-id", "pl_AAAAAAAAAAAAAAAAAAAAAAAA", "--if-match", "2"],
+    ["--json", "screen", "assign", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--playlist-id", "pl_AAAAAAAAAAAAAAAAAAAAAAAA", "--expect-rev", "2"],
     transport,
     { fs: fsLike },
   );
@@ -4470,7 +4470,7 @@ test("one screen update that sets both a playlist and a timezone skips the sched
       "--json", "screen", "update", "scr_PAIRINGAAAAAAAAAAAAAAAA",
       "--playlist-id", "pl_AAAAAAAAAAAAAAAAAAAAAAAA",
       "--timezone", "America/Los_Angeles",
-      "--if-match", "1",
+      "--expect-rev", "1",
     ],
     transport,
     { fs: fsLike },
@@ -4535,7 +4535,7 @@ test("screen assign emits aspect_mismatch beside credits_low from resolved playl
   const transport = aspectMismatchTransport();
   transport.extraResponseHeaders = { "screenrig-credits-remaining": "999" };
   const result = await withAuthenticatedRuntime(
-    ["--json", "screen", "assign", "scr_ASPECT", "--playlist-id", "pl_ASPECT", "--if-match", "1"],
+    ["--json", "screen", "assign", "scr_ASPECT", "--playlist-id", "pl_ASPECT", "--expect-rev", "1"],
     transport,
   );
   assert.equal(result.code, ExitCode.Success, result.stdout);
@@ -4561,7 +4561,7 @@ test("screen assign emits aspect_mismatch beside credits_low from resolved playl
 test("screen update --playlist-id emits aspect_mismatch without media lookups", async () => {
   const transport = aspectMismatchTransport();
   const result = await withAuthenticatedRuntime(
-    ["--json", "screen", "update", "scr_ASPECT", "--playlist-id", "pl_ASPECT", "--if-match", "1"],
+    ["--json", "screen", "update", "scr_ASPECT", "--playlist-id", "pl_ASPECT", "--expect-rev", "1"],
     transport,
   );
   assert.equal(result.code, ExitCode.Success, result.stdout);
@@ -4654,7 +4654,7 @@ test("screen update cannot send observation", async () => {
     [
       "--json", "screen", "update", "scr_PAIRINGAAAAAAAAAAAAAAAA",
       "--name", "Lobby",
-      "--if-match", "1",
+      "--expect-rev", "1",
       "--observation", JSON.stringify(SAMPLE_OBSERVATION),
     ],
     transport,
@@ -4796,7 +4796,7 @@ test("screen update cannot send online, last_online_at, or last_ip", async () =>
     [
       "--json", "screen", "update", "scr_PAIRINGAAAAAAAAAAAAAAAA",
       "--name", "Lobby",
-      "--if-match", "1",
+      "--expect-rev", "1",
       "--online", "true",
       "--last-online-at", "2026-08-19T12:00:00Z",
       "--last-ip", DOCUMENTATION_IPV4,
@@ -4817,7 +4817,7 @@ test("adding a schedule to a playlist an unzoned screen already runs is refused"
   await withRuntime(["--json", "screen", "pair", "ABC234"], transport, { fs: fsLike });
   await withRuntime(["--json", "playlist", "create", file], transport, { fs: fsLike });
   await withRuntime(
-    ["--json", "screen", "assign", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--playlist-id", "pl_AAAAAAAAAAAAAAAAAAAAAAAA", "--if-match", "1"],
+    ["--json", "screen", "assign", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--playlist-id", "pl_AAAAAAAAAAAAAAAAAAAAAAAA", "--expect-rev", "1"],
     transport,
     { fs: fsLike },
   );
@@ -4825,7 +4825,7 @@ test("adding a schedule to a playlist an unzoned screen already runs is refused"
   const scheduled = await scheduledPlaylistFixture(true, "tz-playlist-update-src-");
   transport.calls.length = 0;
   const result = await withRuntime(
-    ["--json", "playlist", "update", "pl_AAAAAAAAAAAAAAAAAAAAAAAA", scheduled.file, "--if-match", "1"],
+    ["--json", "playlist", "update", "pl_AAAAAAAAAAAAAAAAAAAAAAAA", scheduled.file, "--expect-rev", "1"],
     transport,
     { fs: fsLike },
   );
@@ -4876,12 +4876,12 @@ test("app update publishes to the existing application with revision and release
   const appDir = path.join(configDir, "app");
   await mkdir(appDir);
   await writeFile(path.join(appDir, "index.html"), "<!doctype html><html><head></head><body>updated</body></html>");
-  const result = await withRuntime(["--json", "app", "update", "app_EXISTING", appDir, "--if-match", "7", "--no-wait"], transport, { fs: fsLike });
+  const result = await withRuntime(["--json", "app", "update", "app_EXISTING", appDir, "--expect-rev", "7", "--no-wait"], transport, { fs: fsLike });
   assert.equal(result.code, ExitCode.Success, result.stdout);
   assert.equal(JSON.parse(result.stdout).data.id, "app_EXISTING");
   assert.equal(JSON.parse(result.stdout).data.release_id, "rel_NEW");
   const count = transport.calls.length;
-  for (const flags of [[], ["--if-match", "0"], ["--if-match", "7", "--name", "changed"]]) {
+  for (const flags of [[], ["--expect-rev", "0"], ["--expect-rev", "7", "--name", "changed"]]) {
     const invalid = await withRuntime(["--json", "app", "update", "app_EXISTING", appDir, ...flags], transport, { fs: fsLike });
     assert.equal(invalid.code, ExitCode.Usage, invalid.stdout);
     assert.equal(transport.calls.length, count, "invalid update does not upload or request capabilities");
@@ -5222,7 +5222,7 @@ test("playback list, media filters, media update, and app --name bind the consum
     assert.equal(listedEnvelope.data.items[0]?.source_filename, "lobby-poster.png", "media list carries the handle");
 
     const updated = await withRuntime(
-      ["--json", "media", "update", "med_AAAAAAAAAAAAAAAAAAAAAAAA", "--tag", "lobby2", "--if-match", "1"],
+      ["--json", "media", "update", "med_AAAAAAAAAAAAAAAAAAAAAAAA", "--tag", "lobby2", "--expect-rev", "1"],
       transport,
       { fs: fsLike },
     );
@@ -5232,7 +5232,7 @@ test("playback list, media filters, media update, and app --name bind the consum
     assert.equal(patch?.headers?.["if-match"], '"1"');
 
     const cleared = await withRuntime(
-      ["--json", "media", "update", "med_AAAAAAAAAAAAAAAAAAAAAAAA", "--clear-tag", "--if-match", "2"],
+      ["--json", "media", "update", "med_AAAAAAAAAAAAAAAAAAAAAAAA", "--clear-tag", "--expect-rev", "2"],
       transport,
       { fs: fsLike },
     );
@@ -5241,7 +5241,7 @@ test("playback list, media filters, media update, and app --name bind the consum
     assert.deepEqual(clearPatch?.body, { tag: null });
 
     const both = await withRuntime(
-      ["--json", "media", "update", "med_AAAAAAAAAAAAAAAAAAAAAAAA", "--tag", "lobby", "--clear-tag", "--if-match", "3"],
+      ["--json", "media", "update", "med_AAAAAAAAAAAAAAAAAAAAAAAA", "--tag", "lobby", "--clear-tag", "--expect-rev", "3"],
       transport,
       { fs: fsLike },
     );
diff --git a/src/command-input.ts b/src/command-input.ts
index b7ea1c1a..c7ad42f1 100644
--- a/src/command-input.ts
+++ b/src/command-input.ts
@@ -22,3 +22,15 @@ export function flagNumber(flags: Record<string, string | boolean>, name: string
   const n = Number(value);
   return Number.isFinite(n) ? n : undefined;
 }
+
+/** Normalize the legacy spelling before Commander validation; never inspect operands. */
+export function normalizeRevisionArgs(argv: string[]): string[] {
+  let ended = false;
+  return argv.map((arg) => {
+    if (arg === "--") ended = true;
+    if (ended) return arg;
+    if (arg === "--if-match") return "--expect-rev";
+    if (arg.startsWith("--if-match=")) return "--expect-rev=" + arg.slice(11);
+    return arg;
+  });
+}
diff --git a/src/command-path.ts b/src/command-path.ts
index df70fdd0..bc578b06 100644
--- a/src/command-path.ts
+++ b/src/command-path.ts
@@ -21,7 +21,7 @@ export function invocationFlags(command: Command): Record<string, string | boole
   for (let current: Command | null = command; current; current = current.parent) {
     for (const option of current.options) {
       if (current.getOptionValueSource(option.attributeName()) !== "cli") continue;
-      flags[option.long!.slice(2)] = option.negate ? true : current.getOptionValue(option.attributeName());
+      flags[option.long === "--expect-rev" ? "if-match" : option.long!.slice(2)] = option.negate ? true : current.getOptionValue(option.attributeName());
     }
   }
   return flags;
diff --git a/src/command-tree.ts b/src/command-tree.ts
index f62a91b4..a625ed90 100644
--- a/src/command-tree.ts
+++ b/src/command-tree.ts
@@ -88,6 +88,7 @@ export function createCommandTree(
         throw error;
       });
     for (const option of command.options) {
+      if (option.long === "--expect-rev") option.description += " (--if-match alias)";
       // Commander handles the built-in version option before emitting option events.
       if (option.long !== "--version") protectOption(command, option, tokens, seen);
     }
diff --git a/src/commander.test.ts b/src/commander.test.ts
index cc53a01a..c1346fc8 100644
--- a/src/commander.test.ts
+++ b/src/commander.test.ts
@@ -40,14 +40,14 @@ test("missing option values cannot swallow switches or use text after the termin
 
 test("command-specific flags are scoped to their command", () => {
   assert.throws(() => parseArgv(["screen", "list", "--name", "Lobby"]), usage);
-  assert.throws(() => parseArgv(["--name", "Lobby", "screen", "update", "scr_TEST", "--if-match", "1"]), usage);
-  assert.equal(parseArgv(["screen", "update", "scr_TEST", "--name", "Lobby", "--if-match", "1"]).flags.name, "Lobby");
+  assert.throws(() => parseArgv(["--name", "Lobby", "screen", "update", "scr_TEST", "--expect-rev", "1"]), usage);
+  assert.equal(parseArgv(["screen", "update", "scr_TEST", "--name", "Lobby", "--expect-rev", "1"]).flags.name, "Lobby");
 });
 
 test("required options are discoverable and enforced before dispatch", () => {
   assert.throws(() => parseArgv(["screen", "assign", "scr_TEST"]), usage);
   const help = commandHelp(["screen", "assign"]);
-  for (const name of ["--playlist-id", "--if-match"]) assert.equal(help.options.find((option) => option.name === name)?.required, true);
+  for (const name of ["--playlist-id", "--expect-rev"]) assert.equal(help.options.find((option) => option.name === name)?.required, true);
   assert.doesNotThrow(() => parseArgv(["screen", "assign", "--help"]));
 });
 
diff --git a/src/commands.ts b/src/commands.ts
index 4b233ea8..14ffe348 100644
--- a/src/commands.ts
+++ b/src/commands.ts
@@ -1,3 +1,6 @@
+import { publishScreen } from "./screen-publish.js";
+import { readAuthoringJson, readAuthoringText, writeAuthoringJson } from "./authoring-input.js";
+import { editablePlaylist, initializePlaylist, targetDimensions } from "./playlist-authoring.js";
 import { createHash } from "node:crypto";
 import { open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
@@ -420,7 +423,7 @@ export const handlePlaylistValidate = commandHandler(async (args, runtime, resol
   const file = args.positionals[2];
   if (!file) throw usageError("playlist validate requires one JSON file.");
   let parsed: Record<string, unknown>;
-  try { parsed = JSON.parse(await readFile(path.resolve(runtime.cwd(), file), "utf8")); }
+  try { parsed = await readAuthoringJson(file, runtime); }
   catch { throw usageError("Cannot read playlist JSON."); }
   const body = parsed && typeof parsed === "object" && Array.isArray(parsed.pages) ? { ...parsed, pages: expandPlaylistPages(parsed.pages) } : parsed;
   assertPlaylistValid(body);
@@ -1551,7 +1554,7 @@ async function appUpload(args: ParsedArgs, runtime: CliRuntime, resolved: Awaite
   requireFlagValue(args, "if-match", "1");
   const revision = flagString(args.flags, "if-match");
   if (!dir || (update && (!id || !revision))) {
-    throw usageError(update ? "app update requires <id> <directory> --if-match REVISION." : "app upload requires one directory.");
+    throw usageError(update ? "app update requires <id> <directory> --expect-rev REVISION." : "app upload requires one directory.");
   }
   if (update && args.flags.name !== undefined) throw usageError("app update preserves the application name; omit --name.");
   const ifMatch = update ? quotedRevision(revision!) : undefined;
@@ -1716,7 +1719,7 @@ export const handleMediaDelete = commandHandler(async (args, runtime, resolved)
 
   const id = args.positionals[2];
   const revision = flagString(args.flags, "if-match");
-  if (!id || !revision) throw usageError("media delete requires <id> and --if-match.");
+  if (!id || !revision) throw usageError("media delete requires <id> and --expect-rev.");
   const response = await client.call({
     method: "DELETE",
     path: `/api/v1/media/${id}`,
@@ -1876,9 +1879,10 @@ async function mediaGenerate(
   requireFlagValue(args, "prompt", `"Finished event poster with title, facts, and type in the image"`);
   requireFlagValue(args, "aspect-ratio", "16:9");
   requireFlagValue(args, "quality", "medium");
-  const prompt = flagString(args.flags, "prompt");
+  const promptFile = flagString(args.flags, "prompt-file");
+  const prompt = promptFile ? await readAuthoringText(promptFile, runtime, GENERATE_PROMPT_MAX * 4) : flagString(args.flags, "prompt");
   if (prompt === undefined || prompt.length < 1 || prompt.length > GENERATE_PROMPT_MAX) {
-    throw usageError("media generate requires --prompt TEXT of 1 to 4000 characters.");
+    throw usageError("media generate requires --prompt TEXT or --prompt-file FILE containing 1 to 4000 characters.");
   }
   const aspectRatio = flagString(args.flags, "aspect-ratio") ?? "16:9";
   if (!isGenerateAspectRatio(aspectRatio)) {
@@ -1952,7 +1956,7 @@ async function mediaUpdate(args: ParsedArgs, client: ApiClient): Promise<Command
   const clearTag = flagBool(args.flags, "clear-tag");
   const tag = mediaTagFromArgs(args);
   if (!id || !revision) {
-    throw usageError("media update requires <id>, --if-match, and --tag TAG or --clear-tag.");
+    throw usageError("media update requires <id>, --expect-rev, and --tag TAG or --clear-tag.");
   }
   if (clearTag === Boolean(tag)) {
     throw usageError("media update requires exactly one of --tag TAG or --clear-tag.");
@@ -2521,7 +2525,7 @@ async function playlistPreviewCommand(
   let client: ApiClient | undefined;
   let fromFile = false;
   try {
-    playlist = JSON.parse(await readFile(filePath, "utf8"));
+    playlist = await readAuthoringJson(target, runtime);
     fromFile = true;
   } catch {
     fromFile = false;
@@ -2568,7 +2572,15 @@ export const handlePlaylistShow = commandHandler(async (args, runtime, resolved)
 
   const id = args.positionals[2];
   if (!id) throw usageError("playlist get requires an id.");
-  return simpleGet(args, runtime, resolved, `/api/v1/playlists/${id}`, "Playlist");
+  const output = flagString(args.flags, "output");
+  if (!output && !flagBool(args.flags, "editable")) return simpleGet(args, runtime, resolved, `/api/v1/playlists/${id}`, "Playlist");
+  const client = clientFor(runtime, args, resolved.apiUrl, requireToken(resolved.token));
+  const response = await client.call({ method: "GET", path: `/api/v1/playlists/${id}` });
+  const resource = response.body as { id: string; revision: number };
+  if (resource.id !== id || !Number.isSafeInteger(resource.revision) || resource.revision < 1) throw usageError("Playlist response has invalid identity or revision.");
+  const document = editablePlaylist(response.body);
+  const file = output ? await writeAuthoringJson(output, document, runtime) : undefined;
+  return { envelope: successEnvelope({ playlist_id: id, revision: resource.revision, ...(file ? { output: file } : { document }) }, { request_id: client.requestId }), exitCode: ExitCode.Success, human: file ? `Editable playlist written to ${file}` : JSON.stringify(document, null, 2) };
 }, true);
 
 export const handlePlaylistExport = commandHandler(async (args, runtime, resolved) => {
@@ -2639,15 +2651,15 @@ async function playlistCreateUpdateAction(args: ParsedArgs, runtime: CliRuntime,
   const file = action === "update" ? args.positionals[3] : args.positionals[2];
   const ifMatch = flagString(args.flags, "if-match");
   if (!file || (action === "update" && (!id || !ifMatch))) {
-    throw usageError(`playlist ${action} requires ${action === "update" ? "<id> <file> --if-match" : "<file>"}.`);
+    throw usageError(`playlist ${action} requires ${action === "update" ? "<id> <file> --expect-rev" : "<file>"}.`);
   }
   let parsed: Record<string, unknown>;
   try {
-    parsed = JSON.parse(await readFile(path.resolve(runtime.cwd(), file), "utf8")) as Record<string, unknown>;
+    parsed = await readAuthoringJson(file, runtime) as Record<string, unknown>;
   } catch (err) {
     throw usageError(`Cannot read playlist JSON: ${err instanceof Error ? err.message : "invalid JSON"}`);
   }
-  if (typeof parsed.name !== "string" || !Array.isArray(parsed.pages)) {
+  if (!parsed || typeof parsed !== "object" || typeof parsed.name !== "string" || !Array.isArray(parsed.pages)) {
     throw usageError("Playlist JSON must contain string name and array pages.");
   }
   const extra = Object.keys(parsed).filter((key) => key !== "name" && key !== "pages");
@@ -2687,7 +2699,7 @@ export const handlePlaylistDelete = commandHandler(async (args, runtime, resolve
 
   const id = args.positionals[2];
   const ifMatch = flagString(args.flags, "if-match");
-  if (!id || !ifMatch) throw usageError("playlist delete requires <id> and --if-match.");
+  if (!id || !ifMatch) throw usageError("playlist delete requires <id> and --expect-rev.");
   const response = await client.call({
     method: "DELETE",
     path: `/api/v1/playlists/${id}`,
@@ -2718,7 +2730,7 @@ function scheduleZoneError(screenId: string): CliError {
   return usageError(
     `Screen ${screenId} has no timezone, and the playlist schedules pages with visibility. Page visibility rules are civil times, so the screen needs an IANA zone before it can run them.`,
     {
-      command: `screenrig screen set-timezone ${screenId} --timezone America/Los_Angeles --if-match REVISION`,
+      command: `screenrig screen set-timezone ${screenId} --timezone America/Los_Angeles --expect-rev REVISION`,
       reason: "Set the screen timezone first, then assign the playlist. Read the current revision from screen show.",
     },
   );
@@ -2884,7 +2896,7 @@ export const handleScreenUpdate = commandHandler(async (args, runtime, resolved)
   const playlistId = flagString(args.flags, "playlist-id");
   const timezone = flagString(args.flags, "timezone");
   if (!id || !ifMatch || (!name && !playlistId && !timezone)) {
-    throw usageError("screen update requires <id>, --if-match, and --name, --playlist-id, or --timezone.");
+    throw usageError("screen update requires <id>, --expect-rev, and --name, --playlist-id, or --timezone.");
   }
   // A patch that sets both a playlist and a timezone satisfies the schedule
   // rule in one request, so only check when the patch leaves the screen
@@ -2922,7 +2934,7 @@ export const handleScreenAssign = commandHandler(async (args, runtime, resolved)
   const id = args.positionals[2];
   const playlistId = flagString(args.flags, "playlist-id");
   const ifMatch = flagString(args.flags, "if-match");
-  if (!id || !playlistId || !ifMatch) throw usageError("screen assign requires <id> --playlist-id --if-match.");
+  if (!id || !playlistId || !ifMatch) throw usageError("screen assign requires <id> --playlist-id --expect-rev.");
   const playlist = await assertScheduledPlaylistHasZone(client, id, playlistId);
   const body: ScreenPatch = { playlist_id: playlistId };
   const response = await client.call({
@@ -2947,7 +2959,7 @@ export const handleScreenSetTimezone = commandHandler(async (args, runtime, reso
   const id = args.positionals[2];
   const timezone = flagString(args.flags, "timezone");
   const ifMatch = flagString(args.flags, "if-match");
-  if (!id || !timezone || !ifMatch) throw usageError("screen set-timezone requires <id> --timezone --if-match.");
+  if (!id || !timezone || !ifMatch) throw usageError("screen set-timezone requires <id> --timezone --expect-rev.");
   // The zone database belongs to the server, which validates the identifier
   // against it. Sending the value unchanged keeps one authority for what a
   // real zone is, so the CLI never carries a list that can go stale.
@@ -2968,7 +2980,7 @@ async function screenArchiveUnarchiveAction(args: ParsedArgs, runtime: CliRuntim
 
   const id = args.positionals[2];
   const revision = flagString(args.flags, "if-match");
-  if (!id || !revision) throw usageError(`screen ${action} requires <id> and --if-match.`);
+  if (!id || !revision) throw usageError(`screen ${action} requires <id> and --expect-rev.`);
   const response = await client.call({
     method: "POST",
     path: `/api/v1/screens/${id}/${action}`,
@@ -2997,7 +3009,7 @@ export const handleScreenDelete = commandHandler(async (args, runtime, resolved)
 
   const id = args.positionals[2];
   const ifMatch = flagString(args.flags, "if-match");
-  if (!id || !ifMatch) throw usageError("screen delete requires <id> and --if-match.");
+  if (!id || !ifMatch) throw usageError("screen delete requires <id> and --expect-rev.");
   const response = await client.call({
     method: "DELETE",
     path: `/api/v1/screens/${id}`,
@@ -3013,7 +3025,7 @@ export const handleScreenRotatePublicId = commandHandler(async (args, runtime, r
 
   const id = args.positionals[2];
   const revision = flagString(args.flags, "if-match");
-  if (!id || !revision) throw usageError("screen rotate-public-id requires <id> and --if-match.");
+  if (!id || !revision) throw usageError("screen rotate-public-id requires <id> and --expect-rev.");
   const response = await client.call({
     method: "POST",
     path: `/api/v1/screens/${id}/public-id/rotate`,
@@ -3357,7 +3369,7 @@ export const handleKvDelete = commandHandler(async (args, runtime, resolved) =>
 
   if (!key) throw usageError("kv delete requires a key.");
   const ifMatch = flagString(args.flags, "if-match");
-  if (!ifMatch) throw usageError("kv delete requires --if-match.");
+  if (!ifMatch) throw usageError("kv delete requires --expect-rev.");
   const response = await client.call({
     method: "DELETE",
     path: `/api/v1/applications/${applicationId}/kv/${encodeURIComponent(key)}`,
@@ -3384,7 +3396,7 @@ function commentTarget(args: ParsedArgs, target: "screen" | "playlist") {
   }
 
   if (Object.hasOwn(args.flags, "if-match")) {
-    throw usageError("comment commands do not take --if-match; last write wins and does not bump revision.");
+    throw usageError("comment commands do not take --expect-rev; last write wins and does not bump revision.");
   }
   requireFlagValue(args, "page", "poster");
   const pageId = flagString(args.flags, "page");
@@ -4028,3 +4040,31 @@ async function doctor(
 }
 
 export type { Operation };
+
+export const handlePlaylistInit = commandHandler(async (args, runtime, resolved) => {
+  const client = clientFor(runtime, args, resolved.apiUrl, requireToken(resolved.token));
+  const screenId = flagString(args.flags, "screen");
+  const width = flagNumber(args.flags, "target-width"), height = flagNumber(args.flags, "target-height");
+  const screen = screenId ? (await client.call({ method: "GET", path: `/api/v1/screens/${encodeURIComponent(screenId)}` })).body : undefined;
+  const dimensions = targetDimensions(screen, width, height);
+  const media = [];
+  for (const id of args.positionals.slice(2)) {
+    if (!/^med_[A-Za-z0-9_-]+$/.test(id)) throw usageError("playlist init requires media identifiers.");
+    const response = await client.call({ method: "GET", path: `/api/v1/media/${id}` });
+    const record = response.body as Record<string, any>;
+    if (record.id !== id) throw usageError("Media response identity did not match.");
+    media.push(record);
+  }
+  const document = initializePlaylist({ name: flagString(args.flags, "name")!, media, ...dimensions, durationMs: flagNumber(args.flags, "duration-ms") ?? 8000, fit: flagString(args.flags, "fit") ?? "contain" });
+  const output = await writeAuthoringJson(flagString(args.flags, "output")!, document, runtime);
+  return { envelope: successEnvelope({ output, ...dimensions, page_count: media.length }, { request_id: client.requestId }), exitCode: ExitCode.Success, human: `Playlist prepared at ${output}` };
+});
+
+export const handleScreenPublish = commandHandler(async (args, runtime, resolved) => {
+  const parsed = await readAuthoringJson(args.positionals[3]!, runtime);
+  const document = parsed && typeof parsed === "object" && Array.isArray(parsed.pages) ? { ...parsed, pages: expandPlaylistPages(parsed.pages) } : parsed;
+  assertPlaylistValid(document);
+  const client = clientFor(runtime, args, resolved.apiUrl, requireToken(resolved.token));
+  const result = await publishScreen({ client, runtime, configPath: resolved.configPath, apiUrl: resolved.apiUrl, screenId: args.positionals[2]!, revision: flagString(args.flags, "if-match")!, document, requestedKey: flagString(args.flags, "idempotency-key") });
+  return { envelope: successEnvelope(result, { request_id: client.requestId }), exitCode: ExitCode.Success, human: `Assigned ${result.playlist_id} to ${result.screen_id}; assignment read back. Playback still needs verification.` };
+});
diff --git a/src/help.test.ts b/src/help.test.ts
index 95a49b2b..1c0662a3 100644
--- a/src/help.test.ts
+++ b/src/help.test.ts
@@ -56,6 +56,7 @@ test("root help is compact and every command is discoverable through immediate c
     "compose catalog",
     "compose batch",
     "compose render",
+    "playlist init",
     "playlist validate",
     "playlist preview",
     "playlist templates",
@@ -66,6 +67,7 @@ test("root help is compact and every command is discoverable through immediate c
     "playlist show",
     "playlist list",
     "playlist delete",
+    "screen publish",
     "screen pair",
     "screen provision",
     "browser setup",
@@ -142,7 +144,7 @@ test("help paths, --help, and bare groups work before configuration or authentic
   }
   const action = invoke(["screen", "assign", "--help"]).data;
   assert.match(action.usage, /Usage: screenrig screen assign \[options\] <id>/);
-  for (const name of ["--playlist-id", "--if-match"]) {
+  for (const name of ["--playlist-id", "--expect-rev"]) {
     const option = action.options.find((item) => item.name === name);
     assert.equal(option?.type, "value");
     assert.ok(option?.description);
diff --git a/src/if-match.ts b/src/if-match.ts
index 17497357..4781cc56 100644
--- a/src/if-match.ts
+++ b/src/if-match.ts
@@ -6,7 +6,7 @@ export function quotedRevision(raw: string): string {
   const match = POSITIVE_INTEGER.exec(raw);
   const digits = match?.[1] ?? match?.[2];
   if (!digits) {
-    throw usageError("--if-match must be a positive integer, optionally wrapped in double quotes.");
+    throw usageError("--expect-rev must be a positive integer, optionally wrapped in double quotes.");
   }
   return `"${digits}"`;
 }
diff --git a/src/localhost-smoke.ts b/src/localhost-smoke.ts
index 1c2bf164..2f0034ec 100644
--- a/src/localhost-smoke.ts
+++ b/src/localhost-smoke.ts
@@ -208,7 +208,7 @@ async function main(): Promise<void> {
     await run("playlist", "create", playlist);
     await run("playlist", "list");
     await run("playlist", "show", "pl_AAAAAAAAAAAAAAAAAAAAAAAA");
-    await run("playlist", "update", "pl_AAAAAAAAAAAAAAAAAAAAAAAA", playlist, "--if-match", "1");
+    await run("playlist", "update", "pl_AAAAAAAAAAAAAAAAAAAAAAAA", playlist, "--expect-rev", "1");
     const commentsSet = await run(
       "comment",
       "set",
@@ -239,11 +239,11 @@ async function main(): Promise<void> {
     // The playlist schedules a page, and a schedule is a civil rule, so the
     // screen needs a zone before it can carry the playlist. Setting it first is
     // what lets the assignment below through.
-    const zoned = await run("screen", "set-timezone", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--timezone", "America/Los_Angeles", "--if-match", "1");
+    const zoned = await run("screen", "set-timezone", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--timezone", "America/Los_Angeles", "--expect-rev", "1");
     assert.equal((zoned.data as { timezone?: string }).timezone, "America/Los_Angeles");
-    await run("screen", "update", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--playlist-id", "pl_AAAAAAAAAAAAAAAAAAAAAAAA", "--if-match", "1");
+    await run("screen", "update", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--playlist-id", "pl_AAAAAAAAAAAAAAAAAAAAAAAA", "--expect-rev", "1");
     // `screen assign` is the last step of the documented application flow.
-    const assigned = await run("screen", "assign", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--playlist-id", "pl_AAAAAAAAAAAAAAAAAAAAAAAA", "--if-match", "2");
+    const assigned = await run("screen", "assign", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--playlist-id", "pl_AAAAAAAAAAAAAAAAAAAAAAAA", "--expect-rev", "2");
     assert.equal((assigned.data as { playlist_id?: string }).playlist_id, "pl_AAAAAAAAAAAAAAAAAAAAAAAA");
     const toast = await run(
       "screen",
@@ -270,12 +270,12 @@ async function main(): Promise<void> {
     assert.deepEqual(await readFile(downloadPath), mediaBytes);
     assert.doesNotMatch(JSON.stringify(downloaded), /\u0089PNG|iVBOR/, "download envelope must not carry pixels");
     await run("media", "list", "--tag", "lobby", "--primitive", "image");
-    await run("media", "update", mediaId, "--tag", "lobby2", "--if-match", "1");
+    await run("media", "update", mediaId, "--tag", "lobby2", "--expect-rev", "1");
     await run("playback", "list", "--screen-id", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--day", "2026-08-14");
     await run("kv", "set", "greeting", "--application-id", "app_AAAAAAAAAAAAAAAAAAAAAAAA", "--json-value", "{\"message\":\"hello\"}");
     await run("kv", "get", "greeting", "--application-id", "app_AAAAAAAAAAAAAAAAAAAAAAAA");
     await run("kv", "list", "--application-id", "app_AAAAAAAAAAAAAAAAAAAAAAAA");
-    await run("kv", "set", "greeting", "--application-id", "app_AAAAAAAAAAAAAAAAAAAAAAAA", "--json-value", "{\"message\":\"updated\"}", "--if-match", "1");
+    await run("kv", "set", "greeting", "--application-id", "app_AAAAAAAAAAAAAAAAAAAAAAAA", "--json-value", "{\"message\":\"updated\"}", "--expect-rev", "1");
     const bug = await run("feedback", "bug", "Smoke bug", "--body", "Recorded by the localhost smoke.", "--command", "media upload");
     assert.equal((bug.data as { kind?: string }).kind, "bug");
     await run("feedback", "feature", "Smoke feature", "--body", "Recorded by the localhost smoke.");
@@ -288,20 +288,20 @@ async function main(): Promise<void> {
     await run("events", "follow", "--after", "ev1_0", "--timeout", "200");
     await run("operations", "wait", "op_AAAAAAAAAAAAAAAAAAAAAAAA", "--poll-ms", "1");
     await run("operations", "cancel", "op_MEDIAAAAAAAAAAAAAAAAAAAAA");
-    await run("kv", "delete", "greeting", "--application-id", "app_AAAAAAAAAAAAAAAAAAAAAAAA", "--if-match", "2");
-    await run("media", "delete", mediaId, "--if-match", "2");
-    await run("screen", "rotate-public-id", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--if-match", "2");
-    const archived = await run("screen", "archive", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--if-match", "3");
+    await run("kv", "delete", "greeting", "--application-id", "app_AAAAAAAAAAAAAAAAAAAAAAAA", "--expect-rev", "2");
+    await run("media", "delete", mediaId, "--expect-rev", "2");
+    await run("screen", "rotate-public-id", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--expect-rev", "2");
+    const archived = await run("screen", "archive", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--expect-rev", "3");
     assert.equal((archived.data as { state?: string }).state, "archived");
     const listed = await run("screen", "list");
     assert.equal(((listed.data as { items?: unknown[] }).items ?? []).length, 0);
     const archivedList = await run("screen", "list", "--state", "archived");
     assert.equal(((archivedList.data as { items?: Array<{ id?: string }> }).items ?? [])[0]?.id, "scr_PAIRINGAAAAAAAAAAAAAAAA");
-    await run("screen", "unarchive", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--if-match", "4");
-    const deleted = await invoke(["screen", "delete", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--if-match", "5"]);
+    await run("screen", "unarchive", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--expect-rev", "4");
+    const deleted = await invoke(["screen", "delete", "scr_PAIRINGAAAAAAAAAAAAAAAA", "--expect-rev", "5"]);
     assert.equal(deleted.code, 5, `screen delete must surface screen_archive_required: ${deleted.stderr || deleted.stdout}`);
     assert.equal((JSON.parse(deleted.stdout) as { error?: { code?: string } }).error?.code, "screen_archive_required");
-    await run("playlist", "delete", "pl_AAAAAAAAAAAAAAAAAAAAAAAA", "--if-match", "2");
+    await run("playlist", "delete", "pl_AAAAAAAAAAAAAAAAAAAAAAAA", "--expect-rev", "2");
     process.stdout.write(`localhost v1 smoke passed: ${apiUrl} (mock-backed control-plane routes)\n`);
   } finally {
     await new Promise<void>((resolve, reject) => server.close((err) => err ? reject(err) : resolve()));
diff --git a/src/native-program.test.ts b/src/native-program.test.ts
index cb262b3c..b7b94774 100644
--- a/src/native-program.test.ts
+++ b/src/native-program.test.ts
@@ -82,7 +82,7 @@ for (const outcome of ["success", "rejection"] as const) {
 
 test("unauthenticated native mutation actions reject before local preparation or transport", async () => {
   for (const argv of [
-    ["app", "update", "app_TEST", "missing-app", "--if-match", "1"],
+    ["app", "update", "app_TEST", "missing-app", "--expect-rev", "1"],
     ["media", "generate", "--prompt", "A sample information board"],
     ["media", "upload-batch", "missing-manifest.json", "--state", "resume.json"],
   ]) {
diff --git a/src/playlist-authoring.ts b/src/playlist-authoring.ts
new file mode 100644
index 00000000..25067f23
--- /dev/null
+++ b/src/playlist-authoring.ts
@@ -0,0 +1,62 @@
+import { assertPlaylistValid } from "./playlist-validate.js";
+import { usageError } from "./problems.js";
+
+type RecordValue = Record<string, any>;
+function object(value: unknown): RecordValue {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw usageError("Expected a playlist object.");
+  return value as RecordValue;
+}
+/** Preserve authored selectors; strip only fields the backend derives on reads. */
+export function editablePlaylist(value: unknown): RecordValue {
+  const resource = object(value);
+  const document = structuredClone({ name: resource.name, pages: resource.pages });
+  if (!Array.isArray(document.pages)) throw usageError("Playlist pages are missing.");
+  for (const page of document.pages) {
+    object(page);
+    if (page.advance?.mode === "media_end") delete page.advance.max_ms;
+    if (!Array.isArray(page.primitives)) throw usageError("Playlist primitives are missing.");
+    for (const primitive of page.primitives) {
+      object(primitive);
+      if (primitive.primitive === "image" || primitive.primitive === "video") {
+        delete primitive.resolved_media;
+        // Omit the server-inserted false default without changing selector behavior.
+        if (primitive.selector?.by === "id" && primitive.selector.one_at_a_time === false) delete primitive.selector.one_at_a_time;
+      }
+    }
+  }
+  assertPlaylistValid(document);
+  return document;
+}
+
+export function initializePlaylist(options: {
+  name: string; media: RecordValue[]; width: number; height: number; durationMs: number; fit: string;
+}): RecordValue {
+  const document = { name: options.name, pages: options.media.map((media, index) => {
+    if (media.state !== "ready" || !["image", "video"].includes(media.primitive)) throw usageError("Every media item must be a ready image or video.");
+    const video = media.primitive === "video";
+    return {
+      id: `page_${index + 1}`,
+      canvas: { width: options.width, height: options.height, viewport_fit: "contain", background: "#000000FF" },
+      transition: { type: "crossfade", duration_ms: 200 },
+      advance: video ? { mode: "media_end" } : { mode: "duration", after_ms: options.durationMs },
+      primitives: [{ id: "content", primitive: media.primitive,
+        selector: { by: "id", media_id: media.id },
+        rect: { x: 0, y: 0, width: options.width, height: options.height }, layer: 0, content_fit: options.fit,
+        ...(video ? { muted: true, loop: false } : {}),
+      }],
+    };
+  }) };
+  assertPlaylistValid(document);
+  return document;
+}
+
+export function targetDimensions(screen: unknown, width?: number, height?: number): { width: number; height: number } {
+  if ((width === undefined) !== (height === undefined)) throw usageError("Provide both --target-width and --target-height.");
+  if (width === undefined) {
+    const surfaces = (screen as RecordValue | undefined)?.observation?.surfaces;
+    if (!Array.isArray(surfaces) || surfaces.length !== 1) throw usageError("Screen dimensions are unknown or ambiguous; provide --target-width and --target-height.");
+    width = surfaces[0]?.width; height = surfaces[0]?.height;
+  }
+  if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width! <= 0 || height! <= 0) throw usageError("Provide positive whole-number target dimensions.");
+  return { width: width!, height: height! };
+}
diff --git a/src/playlist-bundle.test.ts b/src/playlist-bundle.test.ts
index e88d506e..26efb281 100644
--- a/src/playlist-bundle.test.ts
+++ b/src/playlist-bundle.test.ts
@@ -807,7 +807,7 @@ test("import of a bundle whose playlist name is taken points at --name, and --na
       assert.match(error.problem.detail, /playlist name is already in use/);
       assert.match(error.problem.detail, /unique per account/);
       assert.equal(error.problem.next?.command, `screenrig playlist import ${dir} --name NAME`);
-      assert.match(error.problem.next?.reason ?? "", /--update ID --if-match REVISION/);
+      assert.match(error.problem.next?.reason ?? "", /--update ID --expect-rev REVISION/);
       return true;
     },
   );
@@ -899,9 +899,9 @@ test("import validates create/update flags and all local bytes before any networ
   await writeBundle(dir, [{ id: "med_SOURCE", filename: "hero.png", bytes: Uint8Array.from([1, 2]) }]);
   const transport = importTransport([]);
   const common = { directory: dir, client: new ApiClient({ transport, token: "token" }), runtime: runtimeForImport([]) };
-  await assert.rejects(() => importPlaylistBundle({ ...common, updateId: "pl_TARGET" }), /requires --if-match/);
+  await assert.rejects(() => importPlaylistBundle({ ...common, updateId: "pl_TARGET" }), /requires --expect-rev/);
   await assert.rejects(() => importPlaylistBundle({ ...common, ifMatch: "1" }), /requires --update/);
-  await assert.rejects(() => importPlaylistBundle({ ...common, updateId: "pl_TARGET", ifMatch: "not-a-revision" }), /--if-match/);
+  await assert.rejects(() => importPlaylistBundle({ ...common, updateId: "pl_TARGET", ifMatch: "not-a-revision" }), /--expect-rev/);
   assert.equal(transport.calls.length, 0);
   await writeFile(path.join(dir, (JSON.parse(await readFile(path.join(dir, PLAYLIST_BUNDLE_MANIFEST), "utf8")) as PlaylistBundleManifest).media[0]!.path), Uint8Array.from([9, 9]));
   await assert.rejects(() => importPlaylistBundle(common), /SHA-256 mismatch/);
@@ -995,7 +995,7 @@ function collect(stream: PassThrough): Promise<string> {
 }
 
 test("command parser and JSON help expose playlist export/import including update", async () => {
-  const parsed = parseArgv(["playlist", "import", "./bundle", "--update", "pl_TARGET", "--if-match", "8"]);
+  const parsed = parseArgv(["playlist", "import", "./bundle", "--update", "pl_TARGET", "--expect-rev", "8"]);
   assert.equal(parsed.flags.update, "pl_TARGET");
   assert.equal(parsed.flags["if-match"], "8");
   const exportHelp = commandHelp(["playlist", "export"]);
@@ -1003,7 +1003,7 @@ test("command parser and JSON help expose playlist export/import including updat
   assert.equal(exportHelp.options.find((option) => option.name === "--output")?.type, "value");
   const importHelp = commandHelp(["playlist", "import"]);
   assert.match(importHelp.synopsis[0]!, /playlist import \[options\] <directory>/);
-  for (const name of ["--name", "--update", "--if-match"]) {
+  for (const name of ["--name", "--update", "--expect-rev"]) {
     assert.equal(importHelp.options.find((option) => option.name === name)?.type, "value");
   }
 
diff --git a/src/playlist-bundle.ts b/src/playlist-bundle.ts
index 7e5fa477..8c721841 100644
--- a/src/playlist-bundle.ts
+++ b/src/playlist-bundle.ts
@@ -846,8 +846,8 @@ export async function importPlaylistBundle(options: {
     const trimmed = options.name.trim();
     if (trimmed.length === 0 || trimmed.length > 120) throw usageError("playlist import --name must be 1 to 120 characters.");
   }
-  if (options.updateId && !options.ifMatch) throw usageError("playlist import --update requires --if-match REVISION.");
-  if (!options.updateId && options.ifMatch) throw usageError("playlist import --if-match requires --update PLAYLIST_ID.");
+  if (options.updateId && !options.ifMatch) throw usageError("playlist import --update requires --expect-rev REVISION.");
+  if (!options.updateId && options.ifMatch) throw usageError("playlist import --expect-rev requires --update PLAYLIST_ID.");
   if (options.updateId && !options.updateId.startsWith("pl_")) throw usageError("playlist import --update requires a playlist id starting with pl_.");
   const ifMatch = options.ifMatch ? quotedRevision(options.ifMatch) : undefined;
 
@@ -1000,7 +1000,7 @@ function rethrowNameConflict(error: unknown, state: {
       detail: `${error.problem.detail} Playlist names are unique per account, and this bundle's name is already taken.`,
       next: {
         command: `screenrig playlist import ${state.directory} --name NAME`,
-        reason: "Import as a new playlist under a different name, or replace the existing one with --update ID --if-match REVISION.",
+        reason: "Import as a new playlist under a different name, or replace the existing one with --update ID --expect-rev REVISION.",
       },
     },
     error.exitCode,
diff --git a/src/playlist-workflows.test.ts b/src/playlist-workflows.test.ts
new file mode 100644
index 00000000..be24cffb
--- /dev/null
+++ b/src/playlist-workflows.test.ts
@@ -0,0 +1,150 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { mkdtemp, writeFile, readFile, rm } from "node:fs/promises";
+import { Writable, Readable } from "node:stream";
+import { run, processRuntime } from "./main.js";
+import { initializePlaylist, editablePlaylist, targetDimensions } from "./playlist-authoring.js";
+import { FakeTransport } from "./transport/fake.js";
+import { parseArgv } from "./argv.js";
+import { publishScreen } from "./screen-publish.js";
+import { ApiClient } from "./client.js";
+import { networkError } from "./problems.js";
+const media = [{ id: "med_IMAGE", primitive: "image", state: "ready" }, { id: "med_VIDEO", primitive: "video", state: "ready" }];
+const document = () => initializePlaylist({ name: "Lobby", media, width: 1080, height: 1920, durationMs: 8000, fit: "contain" });
+const response = (body: unknown) => ({ status: 200, headers: {}, body });
+
+test("init preserves media order, portrait geometry and video completion", () => {
+ const result = document();
+ assert.equal(result.pages[0].canvas.height, 1920);
+ assert.equal(result.pages[0].primitives[0].selector.media_id, "med_IMAGE");
+ assert.deepEqual(result.pages[1].advance, { mode: "media_end" });
+ assert.equal(result.pages[1].primitives[0].muted, true);
+ assert.throws(() => targetDimensions({ observation: { surfaces: [{width:1,height:2},{width:2,height:1}] } }));
+ assert.deepEqual(targetDimensions(undefined, 1920, 1080), {width:1920,height:1080});
+ assert.throws(() => targetDimensions(undefined, 1920));
+});
+
+test("editable projection preserves dynamic selectors, schedules, motion and application pins", () => {
+ const authored = document();
+ authored.pages[0].primitives[0].selector = { by: "tag", tag: "lobby", one_at_a_time: true };
+ authored.pages[0].primitives[0].motion = { type: "spin", direction: "cw", speed: "slow" };
+ authored.pages[0].visibility = { enabled: true, from: "2026-09-10T09:00" };
+ const app = structuredClone(authored.pages[1]); app.id = "app";
+ app.advance = { mode: "application", max_ms: 10000 };
+ app.primitives = [{id:"app",primitive:"application",controller:true,application_id:"app_TEST",release_id:"rel_TEST",rect:{x:0,y:0,width:1080,height:1920},layer:0,content_fit:"fill"}];
+ authored.pages.push(app);
+ const iframe = structuredClone(app); iframe.id="web"; iframe.advance={mode:"duration",after_ms:8000};
+ iframe.primitives=[{id:"web",primitive:"iframe",src:"https://example.com",title:"Example",rect:{x:0,y:0,width:1080,height:1920},layer:0,content_fit:"fill"}];
+ authored.pages.push(iframe);
+ const resolved = structuredClone(authored);
+ resolved.id="pl_TEST"; resolved.revision=3; resolved.comments={ note:"kept separately" };
+ resolved.pages[0].primitives[0].resolved_media=[];
+ resolved.pages[1].primitives[0].resolved_media=[];
+ resolved.pages[1].primitives[0].selector.one_at_a_time=false;
+ resolved.pages[1].advance.max_ms=12000;
+ assert.deepEqual(editablePlaylist(resolved), authored);
+ assert.equal(resolved.pages[1].advance.max_ms,12000);
+ resolved.pages[0].unknown="unexpected";
+ assert.throws(() => editablePlaylist(resolved));
+});
+
+test("revision aliases normalize, but duplicate spellings fail", () => {
+ for(const flag of ["--expect-rev", "--if-match"]) assert.equal(parseArgv(["playlist","update","pl_TEST","x.json",flag,"3"]).flags["if-match"], "3");
+ assert.equal(parseArgv(["playlist","update","pl_TEST","x.json","--if-match=3"]).flags["if-match"], "3");
+ assert.throws(()=>parseArgv(["playlist","update","pl_TEST","x.json","--expect-rev","3","--if-match","3"]));
+});
+
+test("stdin validation and editable output need no jq or metadata stripping", async t => {
+ const dir=await mkdtemp('/tmp/playlist-workflows-'); t.after(()=>rm(dir,{recursive:true,force:true}));
+ const config=dir+'/config.json'; await writeFile(config,JSON.stringify({api_url:'https://api.screenrig.ai',token:'test-token'}),{mode:0o600});
+ async function invoke(argv:string[], transport=new FakeTransport(), input=JSON.stringify(document())) {
+  let out=''; const code=await run({...processRuntime(),argv:['--config',config,...argv],env:{},cwd:()=>dir,transport,stdin:Readable.from([input]),isStdinTty:()=>false,stdout:new Writable({write(c,e,done){out+=c;done();}}),stderr:new Writable({write(c,e,done){done();}})});
+  return {code,body:JSON.parse(out)};
+ }
+ assert.equal((await invoke(['playlist','validate','-'])).code,0);
+ assert.equal((await invoke(['playlist','validate','-'],undefined,'secret invalid JSON')).code,2);
+ const transport=new FakeTransport().on('GET','/api/v1/playlists/pl_TEST',()=>response({...document(),id:'pl_TEST',revision:4}));
+ const result=await invoke(['playlist','show','pl_TEST','--output','editable.json'],transport);
+ assert.equal(result.code,0); assert.equal(result.body.data.revision,4);
+ assert.deepEqual(JSON.parse(await readFile(dir+'/editable.json','utf8')),document());
+ assert.equal((await invoke(['playlist','show','pl_TEST','--output','editable.json'],transport)).code,2);
+ assert.throws(()=>parseArgv(['media','generate','--prompt','a','--prompt-file','b']));
+});
+
+for (const failure of ['create','assign','verify']) test(`publish resumes an ambiguous ${failure} without duplicating resources`, async t => {
+ const dir=await mkdtemp('/tmp/publish-workflows-'); t.after(()=>rm(dir,{recursive:true,force:true}));
+ let created=false, assigned=false, failed=false, reads=0;
+ const createKeys:string[]=[],assignKeys:string[]=[];
+ const transport=new FakeTransport()
+ .on('GET','/api/v1/account',()=>response({id:'acc_TEST'}))
+ .on('GET','/api/v1/screens/scr_TEST',()=>{
+  reads++; if(failure==='verify'&&assigned&&!failed){failed=true;throw networkError('Test connection failure');}
+  return response({id:'scr_TEST',revision:assigned?8:7,playlist_id:assigned?'pl_TEST':undefined});
+ })
+ .on('POST','/api/v1/playlists',req=>{
+  createKeys.push(req.headers!['idempotency-key']!); created=true;
+  if(failure==='create'&&!failed){failed=true;throw networkError('Test connection failure');}
+  return response({id:'pl_TEST',revision:1});
+ })
+ .on('PATCH','/api/v1/screens/scr_TEST',req=>{
+  assert.equal(req.headers!['if-match'],'"7"');assignKeys.push(req.headers!['idempotency-key']!);assigned=true;
+  if(failure==='assign'&&!failed){failed=true;throw networkError('Test connection failure');}
+  return response({id:'scr_TEST',revision:8,playlist_id:'pl_TEST'});
+ });
+ const options={client:new ApiClient({transport,token:'test-token'}),runtime:processRuntime(),configPath:dir+'/config.json',apiUrl:'https://api.screenrig.ai',screenId:'scr_TEST',revision:'7',document:document()};
+ await assert.rejects(()=>publishScreen(options));
+ const result=await publishScreen(options);
+ assert.equal(result.assignment_verified,true); assert.equal(result.playback_verified,false);
+ assert.equal(new Set(createKeys).size,1);assert.equal(new Set(assignKeys).size,1);
+ await publishScreen(options);
+ assert.equal(createKeys.length,failure==='create'?2:1);
+ assert.equal(assignKeys.length,failure==='assign'?2:1);
+ assert.ok(created&&assigned);
+});
+
+test("publish checks the expected screen revision before creating a playlist",async t=>{
+ const dir=await mkdtemp('/tmp/publish-conflict-');t.after(()=>rm(dir,{recursive:true,force:true}));
+ const transport=new FakeTransport().on('GET','/api/v1/account',()=>response({id:'acc_TEST'})).on('GET','/api/v1/screens/scr_TEST',()=>response({id:'scr_TEST',revision:9}));
+ await assert.rejects(()=>publishScreen({client:new ApiClient({transport}),runtime:processRuntime(),configPath:dir+'/config.json',apiUrl:'https://api.screenrig.ai',screenId:'scr_TEST',revision:'7',document:document()}));
+ assert.equal(transport.calls.some(c=>c.method!=='GET'),false);
+});
+
+test("init CLI writes a reusable document and prompt-file preserves exact text", async t => {
+ const dir=await mkdtemp('/tmp/authoring-commands-');t.after(()=>rm(dir,{recursive:true,force:true}));
+ const config=dir+'/config.json';await writeFile(config,JSON.stringify({api_url:'https://api.screenrig.ai',token:'test-token'}),{mode:0o600});
+ const transport=new FakeTransport().on('GET','/api/v1/media/med_IMAGE',()=>response(media[0])).on('GET','/api/v1/media/med_VIDEO',()=>response(media[1]));
+ async function invoke(argv:string[], input?:string) {
+  let out=''; const code=await run({...processRuntime(),argv:['--config',config,...argv],env:{},cwd:()=>dir,transport,stdin:Readable.from([input??'']),isStdinTty:()=>false,stdout:new Writable({write(c,e,d){out+=c;d();}}),stderr:new Writable({write(c,e,d){d();}})});
+  return {code,data:JSON.parse(out)};
+ }
+ const initialized=await invoke(['playlist','init','med_IMAGE','med_VIDEO','--name','Lobby','--output','lobby.json','--target-width','1080','--target-height','1920']);
+ assert.equal(initialized.code,0,JSON.stringify(initialized.data));
+ assert.equal(initialized.data.data.page_count,2);
+ assert.deepEqual(JSON.parse(await readFile(dir+'/lobby.json','utf8')),document());
+ assert.equal((await invoke(['playlist','validate','lobby.json'])).code,0);
+ await writeFile(dir+'/prompt.txt',' exact copy\n');
+ let seen='';transport.on('POST','/api/v1/media/generations',req=>{seen=(req.body as any).prompt;return {status:402,headers:{},body:{code:'payment_required',title:'Test refusal',detail:'Test',status:402}};});
+ await invoke(['media','generate','--prompt-file','prompt.txt','--no-progress']);
+ assert.equal(seen,' exact copy\n');
+ assert.equal((await invoke(['media','generate','--prompt-file','-'], 'x'.repeat(4001))).code,2);
+});
+
+test("expired ambiguous publish journals never retry writes", async t => {
+ const dir=await mkdtemp('/tmp/publish-expiry-');t.after(()=>rm(dir,{recursive:true,force:true}));
+ let now=Date.now();
+ const transport=new FakeTransport().on('GET','/api/v1/account',()=>response({id:'acc_TEST'})).on('GET','/api/v1/screens/scr_TEST',()=>response({id:'scr_TEST',revision:7})).on('POST','/api/v1/playlists',()=>{throw networkError('Test interruption');});
+ const options={client:new ApiClient({transport}),runtime:{...processRuntime(),now:()=>new Date(now)},configPath:dir+'/config.json',apiUrl:'https://api.screenrig.ai',screenId:'scr_TEST',revision:'7',document:document()};
+ await assert.rejects(()=>publishScreen(options));now+=24*60*60*1000;
+ await assert.rejects(()=>publishScreen(options),/replay window has expired/);
+ assert.equal(transport.calls.filter(c=>c.method==='POST').length,1);
+});
+
+test("assignment conflicts retain the created playlist and never create another on retry",async t=>{
+ const dir=await mkdtemp('/tmp/publish-assignment-conflict-');t.after(()=>rm(dir,{recursive:true,force:true}));
+ const transport=new FakeTransport().on('GET','/api/v1/account',()=>response({id:'acc_TEST'})).on('GET','/api/v1/screens/scr_TEST',()=>response({id:'scr_TEST',revision:7}))
+ .on('POST','/api/v1/playlists',()=>response({id:'pl_TEST',revision:1}))
+ .on('PATCH','/api/v1/screens/scr_TEST',()=>({status:409,headers:{},body:{code:'revision_conflict',title:'Conflict',status:409,detail:'Screen changed',current_revision:8}}));
+ const options={client:new ApiClient({transport}),runtime:processRuntime(),configPath:dir+'/config.json',apiUrl:'https://api.screenrig.ai',screenId:'scr_TEST',revision:'7',document:document()};
+ for(let i=0;i<2;i++) await assert.rejects(()=>publishScreen(options),(e:any)=>{assert.equal(e.problem.errors.at(-1).playlist_id,'pl_TEST');return true;});
+ assert.equal(transport.calls.filter(c=>c.method==='POST').length,1);
+});
diff --git a/src/program.ts b/src/program.ts
index 04fd13e2..92d16df9 100644
--- a/src/program.ts
+++ b/src/program.ts
@@ -1,3 +1,4 @@
+import { normalizeRevisionArgs } from "./command-input.js";
 import { CommanderError } from "commander";
 import { createCommandTree } from "./command-tree.js";
 import { handleVersion, type CommandResult } from "./commands.js";
@@ -9,6 +10,7 @@ import type { CliRuntime } from "./runtime.js";
 /** Run one native Commander action and return its result to the output boundary. */
 export async function executeCommand(argv: string[], runtime: CliRuntime): Promise<CommandResult> {
   let result: CommandResult | undefined;
+  argv = normalizeRevisionArgs(argv);
   const tree = createCommandTree(argv, async (handler, args) => {
     result = await handler(args, runtime);
   });
diff --git a/src/runtime.ts b/src/runtime.ts
index 9557fbac..45807525 100644
--- a/src/runtime.ts
+++ b/src/runtime.ts
@@ -8,6 +8,8 @@ import type { OperationLogger } from "./log/types.js";
 import { openExternalUrl, openLocalPath, type OpenPath, type OpenUrl } from "./open-url.js";
 
 export interface CliRuntime {
+  stdin?: AsyncIterable<Uint8Array | string>;
+  isStdinTty?: () => boolean;
   argv: string[];
   env: NodeJS.Dict<string>;
   stdout: Writable;
@@ -224,6 +226,8 @@ export function fetchSignedRawPut(fetchImpl: typeof fetch = fetch): SignedRawPut
 export function processRuntime(): CliRuntime {
   return {
     argv: process.argv.slice(2),
+    stdin: process.stdin,
+    isStdinTty: () => process.stdin.isTTY === true,
     env: process.env,
     stdout: process.stdout,
     stderr: process.stderr,
diff --git a/src/screen-publish.ts b/src/screen-publish.ts
new file mode 100644
index 00000000..f6eb50b2
--- /dev/null
+++ b/src/screen-publish.ts
@@ -0,0 +1,107 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { ApiClient } from "./client.js";
+import { newIdempotencyKey } from "./ids.js";
+import { quotedRevision } from "./if-match.js";
+import { CliError, makeProblem, usageError } from "./problems.js";
+import type { CliRuntime } from "./runtime.js";
+
+type Resource = { id: string; revision: number; playlist_id?: string; timezone?: string };
+interface Journal { version: 1; created_at: number; fingerprint: string; create_key: string; assign_key: string; playlist?: Resource; assigned?: boolean }
+const digest = (value: string) => createHash("sha256").update(value).digest("hex");
+function resource(value: unknown, prefix: string): Resource {
+  const item = value as Resource;
+  if (!item || typeof item.id !== "string" || !item.id.startsWith(prefix) || !Number.isSafeInteger(item.revision) || item.revision < 1) throw usageError("Server response has invalid resource identity or revision.");
+  return item;
+}
+function conflict(detail: string, revision?: number): never {
+  throw new CliError(makeProblem("revision_conflict", "Publish needs reconciliation", 409, detail, { current_revision: revision }));
+}
+
+/** Multi-request publishing is resumable, not atomic. The journal contains no authored content. */
+export async function publishScreen(options: {
+  client: ApiClient; runtime: CliRuntime; configPath: string; apiUrl: string;
+  screenId: string; revision: string; document: any; requestedKey?: string;
+}) {
+  const { client, screenId, document } = options;
+  const expected = Number(options.revision.replaceAll('"', ''));
+  quotedRevision(options.revision);
+  if (!/^scr_[A-Za-z0-9_-]+$/.test(screenId)) throw usageError("screen publish requires a screen identifier.");
+  const account = (await client.call({ method: "GET", path: "/api/v1/account" })).body as { id: string };
+  if (!account?.id?.startsWith("acc_")) throw usageError("Account identity is missing.");
+  const fingerprint = digest(JSON.stringify([options.apiUrl, account.id, screenId, expected, document, options.requestedKey ?? ""]));
+  const directory = path.join(path.dirname(options.configPath), "publishes");
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const journalPath = path.join(directory, `${fingerprint}.json`);
+  // A dead local process can be recovered without expiring an active publisher's lock.
+  const lockPath = `${journalPath}.lock`;
+  for (let attempt = 0; ; attempt++) {
+    try {
+      await mkdir(lockPath, { mode: 0o700 });
+      await writeFile(path.join(lockPath, "pid"), String(process.pid), { mode: 0o600 });
+      break;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      let dead = false;
+      try {
+        const pid = Number(await readFile(path.join(lockPath, "pid"), "utf8"));
+        if (Number.isSafeInteger(pid) && pid > 0) {
+          try { process.kill(pid, 0); } catch (probe) { dead = (probe as NodeJS.ErrnoException).code === "ESRCH"; }
+        }
+      } catch { /* An initializing or incomplete lock is never stolen. */ }
+      if (!dead || attempt > 0) throw usageError(`Publish is already running or has an incomplete lock at ${lockPath}. Confirm no publisher is running before removing an incomplete lock.`);
+      const abandoned = `${lockPath}.${randomUUID()}.stale`;
+      try { await rename(lockPath, abandoned); await rm(abandoned, { recursive: true, force: true }); }
+      catch { throw usageError("Publish lock changed; retry the same command."); }
+    }
+  }
+  let state: Journal | undefined;
+  const save = async () => {
+    const temporary = `${journalPath}.${randomUUID()}.tmp`;
+    const file = await open(temporary, "wx", 0o600);
+    try { await file.writeFile(JSON.stringify(state) + "\n"); await file.sync(); } finally { await file.close(); }
+    await rename(temporary, journalPath);
+  };
+  try {
+    try {
+      const info = await stat(journalPath);
+      if ((info.mode & 0o077) !== 0) throw usageError("Publish journal must be private.");
+      state = JSON.parse(await readFile(journalPath, "utf8"));
+      if (state?.version !== 1 || state.fingerprint !== fingerprint || !Number.isFinite(state.created_at) || !state.create_key || !state.assign_key) throw usageError("Publish journal is invalid.");
+      if (state.playlist) resource(state.playlist, "pl_");
+    } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+    if (!state) {
+      const screen = resource((await client.call({ method: "GET", path: `/api/v1/screens/${screenId}` })).body, "scr_");
+      if (screen.id !== screenId) throw usageError("Screen response identity did not match.");
+      if (screen.revision !== expected) conflict("Screen changed before publishing. Inspect it and retry with its intended revision.", screen.revision);
+      if (document.pages.some((page: any) => page.visibility !== undefined) && !screen.timezone) throw usageError("Set the screen timezone before publishing a scheduled playlist.");
+      state = { version: 1, created_at: options.runtime.now().getTime(), fingerprint, create_key: newIdempotencyKey(), assign_key: newIdempotencyKey() };
+      await save();
+    }
+    if (!state.assigned && options.runtime.now().getTime() - state.created_at >= 24 * 60 * 60 * 1000) {
+      throw usageError("The publish replay window has expired. Inspect the account and screen before reconciling; this command will not repeat an ambiguous write after server idempotency expiry.");
+    }
+    if (!state.playlist) {
+      const response = await client.call({ method: "POST", path: "/api/v1/playlists", body: document, idempotent: true, idempotencyKey: state.create_key });
+      state.playlist = resource(response.body, "pl_");
+      // Persist identity only, never the returned playlist or resolved media.
+      state.playlist = { id: state.playlist.id, revision: state.playlist.revision };
+      await save();
+    }
+    if (!state.assigned) {
+      await client.call({ method: "PATCH", path: `/api/v1/screens/${screenId}`, body: { playlist_id: state.playlist.id }, headers: { "if-match": quotedRevision(options.revision) }, idempotent: true, idempotencyKey: state.assign_key });
+      state.assigned = true;
+      await save();
+    }
+    const screen = resource((await client.call({ method: "GET", path: `/api/v1/screens/${screenId}` })).body, "scr_");
+    if (screen.id !== screenId || screen.playlist_id !== state.playlist.id) conflict("The screen no longer has this playlist assigned. Inspect it before making another change.", screen.revision);
+    return { playlist_id: state.playlist.id, playlist_revision: state.playlist.revision, screen_id: screenId, screen_revision: screen.revision, assignment_verified: true, playback_verified: false, journal: journalPath };
+  } catch (error) {
+    if (error instanceof CliError) {
+      error.problem.errors.push({ stage: state?.assigned ? "verify" : state?.playlist ? "assign" : "create", playlist_id: state?.playlist?.id, journal: journalPath });
+      if (!error.problem.next) error.problem.next = { command: `screenrig screen show ${screenId}`, reason: "Inspect the target. After a transport failure, repeat the identical publish command to resume; revision conflicts require reconciliation. The journal records any playlist already created." };
+    }
+    throw error;
+  } finally { await rm(lockPath, { recursive: true, force: true }); }
+}
diff --git a/src/server-smoke.ts b/src/server-smoke.ts
index c9f7b19a..64c99a49 100644
--- a/src/server-smoke.ts
+++ b/src/server-smoke.ts
@@ -156,10 +156,10 @@ async function main(): Promise<void> {
     assert.ok(playlistId && Number.isInteger(playlistRevision));
     await run(["playlist", "show", playlistId]);
     await run(["playlist", "list"]);
-    const updatedPlaylist = await run(["playlist", "update", playlistId, playlistFile, "--if-match", String(playlistRevision)]);
+    const updatedPlaylist = await run(["playlist", "update", playlistId, playlistFile, "--expect-rev", String(playlistRevision)]);
     playlistRevision = Number(updatedPlaylist.data?.revision);
 
-    const assignedScreen = await run(["screen", "assign", screenId, "--playlist-id", playlistId, "--if-match", String(screenRevision)]);
+    const assignedScreen = await run(["screen", "assign", screenId, "--playlist-id", playlistId, "--expect-rev", String(screenRevision)]);
     screenRevision = Number(assignedScreen.data?.revision);
 
     const pairingEventsResponse = await fetch(new URL("/runtime/v1/pairing-events", playUrl), {
@@ -209,9 +209,9 @@ async function main(): Promise<void> {
     const kv = await run(["kv", "set", "smoke", "--application-id", applicationId, "--json-value", "{\"status\":\"ok\"}"]);
     kvRevision = Number(kv.data?.revision);
     assert.ok(Number.isInteger(kvRevision));
-    const kvUpdated = await run(["kv", "set", "smoke", "--application-id", applicationId, "--json-value", "{\"status\":\"updated\"}", "--if-match", String(kvRevision)]);
+    const kvUpdated = await run(["kv", "set", "smoke", "--application-id", applicationId, "--json-value", "{\"status\":\"updated\"}", "--expect-rev", String(kvRevision)]);
     kvRevision = Number(kvUpdated.data?.revision);
-    const staleUpdate = await run(["kv", "set", "smoke", "--application-id", applicationId, "--json-value", "{\"status\":\"stale\"}", "--if-match", "1"], true);
+    const staleUpdate = await run(["kv", "set", "smoke", "--application-id", applicationId, "--json-value", "{\"status\":\"stale\"}", "--expect-rev", "1"], true);
     assert.equal(staleUpdate.ok, false);
     assert.equal(staleUpdate.error?.code, "revision_conflict");
     await run(["kv", "get", "smoke", "--application-id", applicationId]);
@@ -222,9 +222,9 @@ async function main(): Promise<void> {
     await run(["kv", "list", "--application-id", applicationId]);
     const events = await run(["events", "list"]);
     const cursor = String(events.data?.next_cursor ?? "");
-    await run(["kv", "delete", "smoke", "--application-id", applicationId, "--if-match", String(kvRevision)]);
+    await run(["kv", "delete", "smoke", "--application-id", applicationId, "--expect-rev", String(kvRevision)]);
     kvRevision = undefined;
-    await run(["kv", "delete", "smoke-binary", "--application-id", applicationId, "--if-match", String(kvBinaryRevision)]);
+    await run(["kv", "delete", "smoke-binary", "--application-id", applicationId, "--expect-rev", String(kvBinaryRevision)]);
     kvBinaryRevision = undefined;
     const followed = await new Promise<{ code: number; stdout: string; stderr: string }>((resolve) => {
       const child = spawn(process.execPath, [path.join(packageRoot, "dist", "bin.js"), "--json", "events", "follow", "--after", cursor, "--timeout", "1500"], { cwd: packageRoot, env });
@@ -242,7 +242,7 @@ async function main(): Promise<void> {
       const screenBeforeRotation = await run(["screen", "show", screenId]);
       screenRevision = Number(screenBeforeRotation.data?.revision);
       assert.ok(Number.isInteger(screenRevision));
-      const candidate = await run(["screen", "rotate-public-id", screenId, "--if-match", String(screenRevision)], true);
+      const candidate = await run(["screen", "rotate-public-id", screenId, "--expect-rev", String(screenRevision)], true);
       if (candidate.ok) {
         rotated = candidate;
         break;
@@ -253,7 +253,7 @@ async function main(): Promise<void> {
     assert.ok(rotated, "screen rotation did not converge after manifest materialization revisions settled");
     screenRevision = Number(rotated.data?.revision);
     const revisionBeforeArchive = screenRevision;
-    const archived = await run(["screen", "archive", screenId, "--if-match", String(screenRevision)]);
+    const archived = await run(["screen", "archive", screenId, "--expect-rev", String(screenRevision)]);
     screenRevision = Number(archived.data?.revision);
     assert.equal(archived.data?.state, "archived", "screen archive must set state archived");
     assert.equal(screenRevision, revisionBeforeArchive + 1, "screen archive must advance the resource revision");
@@ -275,19 +275,19 @@ async function main(): Promise<void> {
     }) + "\n");
   } finally {
     if (applicationId && kvRevision) {
-      await run(["kv", "delete", "smoke", "--application-id", applicationId, "--if-match", String(kvRevision)], true).catch(() => undefined);
+      await run(["kv", "delete", "smoke", "--application-id", applicationId, "--expect-rev", String(kvRevision)], true).catch(() => undefined);
     }
     if (applicationId && kvBinaryRevision) {
-      await run(["kv", "delete", "smoke-binary", "--application-id", applicationId, "--if-match", String(kvBinaryRevision)], true).catch(() => undefined);
+      await run(["kv", "delete", "smoke-binary", "--application-id", applicationId, "--expect-rev", String(kvBinaryRevision)], true).catch(() => undefined);
     }
     if (mediaId && Number.isInteger(mediaRevision)) {
-      await run(["media", "delete", mediaId, "--if-match", String(mediaRevision)], true).catch(() => undefined);
+      await run(["media", "delete", mediaId, "--expect-rev", String(mediaRevision)], true).catch(() => undefined);
     }
     if (screenId && Number.isInteger(screenRevision)) {
-      await run(["screen", "delete", screenId, "--if-match", String(screenRevision)], true).catch(() => undefined);
+      await run(["screen", "delete", screenId, "--expect-rev", String(screenRevision)], true).catch(() => undefined);
     }
     if (playlistId && Number.isInteger(playlistRevision)) {
-      await run(["playlist", "delete", playlistId, "--if-match", String(playlistRevision)], true).catch(() => undefined);
+      await run(["playlist", "delete", playlistId, "--expect-rev", String(playlistRevision)], true).catch(() => undefined);
     }
     await rm(temp, { recursive: true, force: true });
   }
diff --git a/src/validate-invocation.test.ts b/src/validate-invocation.test.ts
index e90e6a82..adc9a32f 100644
--- a/src/validate-invocation.test.ts
+++ b/src/validate-invocation.test.ts
@@ -6,7 +6,7 @@ import { CliError } from "./problems.js";
 import type { CliRuntime } from "./runtime.js";
 
 const invalid = [
-  ["screen", "update", "scr_TEST", "--name", "Lobby", "--if-match", "1", "--dry-run"],
+  ["screen", "update", "scr_TEST", "--name", "Lobby", "--expect-rev", "1", "--dry-run"],
   ["screen", "list", "--name", "Lobby"],
   ["screen", "show", "scr_TEST", "extra"],
   ["screen", "list", "--timeout", "oops"],
@@ -20,9 +20,9 @@ const invalid = [
   ["screen", "list", "--state", "archived", "--state", "archived"],
   ["screen", "list", "-x"],
   ["screen", "show", "scr_TEST", "--name=secret"],
-  ["screen", "archive", "scr_TEST", "--if-match", "oops"],
+  ["screen", "archive", "scr_TEST", "--expect-rev", "oops"],
   ["media", "upload", "poster.png", "--no-transcode", "--codec", "h264"],
-  ["media", "update", "med_TEST", "--tag", "x", "--clear-tag", "--if-match", "1"],
+  ["media", "update", "med_TEST", "--tag", "x", "--clear-tag", "--expect-rev", "1"],
   ["feedback", "bug", "Title", "--body", "x", "--body-file", "x.md"],
   ["kv", "set", "key", "--application-id", "app_TEST", "--json-value", "{}", "--file", "x"],
   ["compose", "render", "page.json", "--target-width", "1920"],
@@ -39,7 +39,7 @@ for (const [index, argv] of invalid.entries()) {
 
 test("supported values, aliases, empty byte payload, and help paths remain valid", () => {
   for (const argv of [
-    ["screen", "update", "scr_TEST", "--name=Lobby=North", "--if-match", '"1"'],
+    ["screen", "update", "scr_TEST", "--name=Lobby=North", "--expect-rev", '"1"'],
     ["screen", "screenshot", "scr_TEST", "--timeout", "0"],
     ["events", "follow", "--timeout", "0"],
     ["playlist", "get", "pl_TEST"],