@gentbajko/slopify 2.0.1 → 2.0.3

package/dist/adapters/llm/run-cli.js

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { cliCommand } from "../../kernel/cli-command.js";
 import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
+import { cliName, commandOf, quoted } from "../explain.js";
 // ceiling: the last 8 KiB of stderr is kept. A CLI that writes megabytes of progress there
 // would otherwise be held in memory for the length of a run, and the tail is the part that
 // says why it stopped. Streaming stderr to the log is the upgrade if a provider ever
@@ -117,7 +118,7 @@ export async function deliveredInput(run) {
     catch {
         throw providerError({
             kind: "unavailable",
-            message: "The full prompt could not be delivered to the CLI. Review before retrying.",
+            message: "Slopify could not hand the whole prompt to the CLI, so it cannot tell what the CLI worked on (it may already have used your quota). Use Retry stage to run it again.",
         });
     }
 }
@@ -126,7 +127,7 @@ export function cliInput(text) {
     if (Buffer.byteLength(text) >= 8 * 1024 * 1024)
         throw providerError({
             kind: "unsupported",
-            message: "The text prompt exceeds the CLI input limit (8 MiB). No text was truncated or submitted.",
+            message: "This prompt is larger than the CLI accepts (8 MB), so nothing was sent. Make the inputs shorter in Edit project, or choose an API provider such as OpenRouter in its Providers section, then use Retry stage.",
         });
     return text;
 }
@@ -151,15 +152,17 @@ export function promptOf(messages) {
         .join("\n\n");
 }
 // A bare non-zero exit tells the user nothing, so the stage shows whatever the CLI put on
-// stderr - the provider's error text, verbatim.
+// stderr - the provider's error text, verbatim - after a sentence saying what to do.
 export function endedWithout(binary, ended, stderr) {
     const said = redact(stderr.trim());
-    const how = ended.error === null
-        ? `exited ${ended.code === null ? "on a signal" : String(ended.code)}`
-        : `could not be started (${redact(ended.error.message)})`;
-    return said === ""
-        ? `the ${binary} CLI ${how} without answering`
-        : `the ${binary} CLI ${how} without answering: ${said}`;
+    if (ended.error !== null)
+        return `The ${cliName(binary)} could not be started${quoted("", redact(ended.error.message))}. Check it is installed and set up in Settings → Providers, then use Retry stage.`;
+    const how = ended.code === null ? "killed by the system" : `exit code ${String(ended.code)}`;
+    return `The ${cliName(binary)} stopped without answering${quoted(how, said)}. Run ${commandOf(binary)} in a terminal to check it works and is signed in, then use Retry stage.`;
+}
+// The run outlived both the polite and the forced stop.
+export function stuckCli(binary) {
+    return `The ${cliName(binary)} stopped responding and could not be shut down. Close any leftover ${commandOf(binary)} processes or restart your computer, then use Retry stage.`;
 }
 // Unreachable while stdio names `pipe` for fd 1; it is here so the type carries no null
 // and no non-null assertion is needed to read the stream.
@@ -180,7 +183,7 @@ export function cliEvent(binary, line) {
         // know. The text is not echoed back: half a JSON object is noise to the user.
         throw providerError({
             kind: "other",
-            message: `the ${binary} CLI wrote a line this app could not read`,
+            message: `The ${cliName(binary)} sent output Slopify could not read. Update it to the latest version, then use Retry stage.`,
         });
     }
     return { type: parsed.data.type, value };
@@ -190,7 +193,7 @@ export function cliShaped(binary, schema, value) {
     if (!parsed.success) {
         throw providerError({
             kind: "other",
-            message: `the ${binary} CLI wrote an event this app could not read`,
+            message: `The ${cliName(binary)} sent output Slopify could not read. Update it to the latest version, then use Retry stage.`,
         });
     }
     return parsed.data;

package/dist/adapters/tts/cartesia.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
+import { httpFailure, missingKey, noAudio, voiceFix } from "../explain.js";
 import { retryAfter } from "../retry-after.js";
 // The HTTP gateway adapter for Cartesia. `fetch` and
 // nothing else; `/tts/bytes` streams the audio it renders, so the response body is
@@ -54,7 +55,7 @@ export function cartesiaTts(deps) {
                 throw await failure(response, req.voiceId);
             }
             if (response.body === null) {
-                throw providerError({ kind: "other", message: "Cartesia answered with no audio" });
+                throw providerError({ kind: "other", message: noAudio("Cartesia") });
             }
             return { audio: response.body, container: "mp3" };
         },
@@ -64,7 +65,7 @@ function keyOf(deps) {
     const key = deps.key();
     // An absent key is terminal, so it never becomes a request.
     if (key === undefined || key === "") {
-        throw providerError({ kind: "missing_key", message: "no Cartesia key is stored" });
+        throw providerError({ kind: "missing_key", message: missingKey("Cartesia") });
     }
     return key;
 }
@@ -88,7 +89,13 @@ async function failure(response, voiceId) {
         kind: kindOf(response.status),
         // `voice_not_found` has to say which voice was asked for; Cartesia's
         // own message does not repeat the id.
-        message: `Cartesia answered ${response.status} for voice ${voiceId}: ${message}`,
+        message: httpFailure({
+            provider: "Cartesia",
+            status: response.status,
+            detail: message,
+            subject: `narration request for voice "${voiceId}"`,
+            fix: voiceFix(voiceId),
+        }),
         ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
     });
 }

package/dist/adapters/tts/elevenlabs.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
+import { httpFailure, missingKey, noAudio, refreshList, unreadable, voiceFix } from "../explain.js";
 import { retryAfter } from "../retry-after.js";
 // The HTTP gateway adapter for ElevenLabs: the platform's own `fetch` and nothing else. The
 // response body already is the `ReadableStream<Uint8Array>` the port asks for, so an SDK
@@ -44,12 +45,12 @@ export function elevenLabsTts(deps) {
                 signal: AbortSignal.timeout(10_000),
             });
             if (!response.ok)
-                throw await failure(response);
+                throw await failure(response, undefined, refreshList);
             const parsed = modelList.safeParse(safeJson(await response.text()));
             if (!parsed.success) {
                 throw providerError({
                     kind: "other",
-                    message: "ElevenLabs' model list was not in the shape this app can read",
+                    message: unreadable("ElevenLabs"),
                 });
             }
             return parsed.data
@@ -70,7 +71,7 @@ export function elevenLabsTts(deps) {
                 throw await failure(response, req.voiceId);
             }
             if (response.body === null) {
-                throw providerError({ kind: "other", message: "ElevenLabs answered with no audio" });
+                throw providerError({ kind: "other", message: noAudio("ElevenLabs") });
             }
             return { audio: response.body, container: "mp3" };
         },
@@ -80,7 +81,7 @@ function keyOf(deps) {
     const key = deps.key();
     // `missing_key`, not `auth`, because that rule makes it terminal.
     if (key === undefined || key === "") {
-        throw providerError({ kind: "missing_key", message: "no ElevenLabs key is stored" });
+        throw providerError({ kind: "missing_key", message: missingKey("ElevenLabs") });
     }
     return key;
 }
@@ -97,7 +98,7 @@ function kindOf(status) {
     // port's error contract first, which is not this adapter's to widen.
     return "other";
 }
-async function failure(response, voiceId) {
+async function failure(response, voiceId, next) {
     const text = await response.text().catch(() => "");
     // The provider's own words, through the redactor - an error body may quote the key back.
     const message = redact(detailOf(text) || response.statusText);
@@ -106,7 +107,18 @@ async function failure(response, voiceId) {
         kind: kindOf(response.status),
         // A rejected voice ID has to be named, and it is the one part of the
         // request the user chose. It is not secret, unlike everything else on the wire.
-        message: `ElevenLabs answered ${response.status}${voiceId === undefined ? "" : ` for voice ${voiceId}`}: ${message}`,
+        message: httpFailure({
+            provider: "ElevenLabs",
+            status: response.status,
+            detail: message,
+            next,
+            ...(voiceId === undefined
+                ? {}
+                : {
+                    subject: `narration request for voice "${voiceId}"`,
+                    fix: voiceFix(voiceId),
+                }),
+        }),
         ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
     });
 }

package/dist/adapters/tts/inworld-async.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
+import { httpFailure, internalError, noAudio, providerSaid, unreadable, voiceFix, } from "../explain.js";
 import { retryAfter } from "../retry-after.js";
 const operationName = /^workspaces\/[A-Za-z0-9_-]+\/ttsAsyncJobs\/[A-Za-z0-9_-]+\/operations\/[A-Za-z0-9_-]+$/;
 const operationSchema = z.object({
@@ -15,11 +16,14 @@ const operationSchema = z.object({
 export async function* inworldAsync(deps, request, key) {
     const saved = request.continuation?.read();
     if (saved !== undefined && !operationName.test(saved))
-        throw invalid("returned an invalid operation name");
+        throw providerError({
+            kind: "other",
+            message: internalError("the saved Inworld job reference is damaged"),
+        });
     if (saved === undefined && request.text.length > 100_000) {
         throw providerError({
             kind: "unsupported",
-            message: "Inworld async accepts up to 100,000 characters per request (10,000 for On-Demand accounts). Select paragraph chunking for longer articles.",
+            message: "This narration part is longer than the 100,000 characters Inworld takes at once (10,000 on On-Demand accounts). Set Chunking to Paragraph in the Providers section of Edit project, then use Retry stage.",
         });
     }
     const headers = { Authorization: `Basic ${key}`, "Content-Type": "application/json" };
@@ -45,10 +49,10 @@ export async function* inworldAsync(deps, request, key) {
     let expected = saved;
     for (;;) {
         request.signal.throwIfAborted();
-        await check(response, key);
+        await check(response, key, request.voiceId);
         const parsed = operationSchema.safeParse(await response.json().catch(() => null));
         if (!parsed.success || (expected && parsed.data.name !== expected))
-            throw invalid("returned an invalid operation");
+            throw unreadableAnswer();
         const operation = parsed.data;
         expected = operation.name;
         request.continuation?.write(operation.name);
@@ -65,11 +69,11 @@ export async function* inworldAsync(deps, request, key) {
                             : code === 3 || code === 5 || code === 9
                                 ? "unsupported"
                                 : "other",
-                    message: `Inworld async job failed: ${clean(message ?? "audio generation stopped", key)}`,
+                    message: streamFailure(code, clean(message ?? "", key), request.voiceId),
                 });
             }
             if (!operation.response)
-                throw invalid("finished without an audio download");
+                throw providerError({ kind: "other", message: noAudio("Inworld") });
             yield* download(deps.fetch, operation.response.audioUri, request.signal);
             return;
         }
@@ -85,7 +89,7 @@ export async function* inworldAsync(deps, request, key) {
 async function* download(fetch, uri, signal) {
     const url = URL.parse(uri);
     if (url?.protocol !== "https:" || url.username || url.password)
-        throw invalid("returned an invalid audio download URL");
+        throw unreadableAnswer();
     // This is a signed storage URL, not an Inworld API endpoint. Never forward Basic auth.
     let response;
     try {
@@ -94,12 +98,12 @@ async function* download(fetch, uri, signal) {
     catch {
         signal.throwIfAborted();
         // Signed query parameters must not become a persisted error or log entry.
-        throw invalid("audio download could not be reached; retrying the existing job");
+        throw downloadFailed("");
     }
     if (!response.ok)
-        throw invalid(`audio download answered ${response.status}; retrying the existing job`);
+        throw downloadFailed(` (error ${String(response.status)})`);
     if (!response.body)
-        throw invalid("answered with no audio");
+        throw providerError({ kind: "other", message: noAudio("Inworld") });
     const reader = response.body.getReader();
     let heard = false;
     try {
@@ -116,16 +120,16 @@ async function* download(fetch, uri, signal) {
     }
     catch {
         signal.throwIfAborted();
-        throw invalid("audio download stopped; retrying the existing job");
+        throw downloadFailed("");
     }
     finally {
         await reader.cancel().catch(() => { });
         reader.releaseLock();
     }
     if (!heard)
-        throw invalid("answered with no audio");
+        throw providerError({ kind: "other", message: noAudio("Inworld") });
 }
-async function check(response, key) {
+async function check(response, key, voiceId) {
     if (response.ok)
         return;
     const detail = clean(await response.text().catch(() => ""), key);
@@ -138,13 +142,40 @@ async function check(response, key) {
                 : response.status === 400 || response.status === 404
                     ? "unsupported"
                     : "other",
-        message: `Inworld async answered ${response.status}: ${detail || response.statusText}`,
+        message: httpFailure({
+            provider: "Inworld",
+            status: response.status,
+            detail: detail || response.statusText,
+            subject: `narration request for voice "${voiceId}"`,
+            fix: voiceFix(voiceId),
+        }),
         ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
     });
 }
 function clean(message, key) {
     return redact(message.replaceAll(key, "[redacted]"));
 }
-function invalid(detail) {
-    return providerError({ kind: "other", message: `Inworld ${detail}.` });
+// Signed query parameters must not become a persisted error or log entry, so the link is
+// never quoted.
+function downloadFailed(status) {
+    return providerError({
+        kind: "other",
+        message: `Inworld made the narration, but Slopify could not download it${status}. Check your internet connection, then use Retry stage.`,
+    });
+}
+function unreadableAnswer() {
+    return providerError({ kind: "other", message: unreadable("Inworld") });
+}
+// Inworld's streamed and async errors carry a gRPC code instead of an HTTP status.
+export function streamFailure(code, detail, voiceId) {
+    const label = `code ${String(code)}`;
+    if (code === 16)
+        return httpFailure({ provider: "Inworld", status: 401, detail, label });
+    if (code === 7)
+        return httpFailure({ provider: "Inworld", status: 403, detail, label });
+    if (code === 8)
+        return httpFailure({ provider: "Inworld", status: 429, detail, label });
+    if (code === 3 || code === 5 || code === 9)
+        return providerSaid("Inworld", "could not narrate this text", detail, voiceFix(voiceId));
+    return providerSaid("Inworld", "stopped before the narration was finished", detail, "This is usually temporary: wait a few minutes, then use Retry stage.");
 }

package/dist/adapters/tts/inworld.js

@@ -1,8 +1,9 @@
 import { z } from "zod";
 import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
+import { httpFailure, missingKey, noAudio, unreadable, voiceFix } from "../explain.js";
 import { retryAfter } from "../retry-after.js";
-import { inworldAsync } from "./inworld-async.js";
+import { inworldAsync, streamFailure } from "./inworld-async.js";
 export const inworldModels = [
     { id: "inworld-tts-2", name: "Realtime TTS-2" },
     { id: "inworld-tts-2-flash", name: "Realtime TTS-2 Flash" },
@@ -22,7 +23,7 @@ export function inworldTts(deps) {
                 ?.trim()
                 .replace(/^Basic\s+/i, "");
             if (!key)
-                throw providerError({ kind: "missing_key", message: "No Inworld API key is stored." });
+                throw providerError({ kind: "missing_key", message: missingKey("Inworld") });
             const cancel = new AbortController();
             const signal = AbortSignal.any([request.signal, cancel.signal]);
             const iterator = synthesizeRequest(deps, { ...request, signal }, key);
@@ -56,7 +57,10 @@ async function* synthesizeRequest(deps, request, key) {
         return;
     }
     if (request.text.trim().length === 0)
-        throw providerError({ kind: "unsupported", message: "Inworld needs text to narrate." });
+        throw providerError({
+            kind: "unsupported",
+            message: "Inworld was sent an empty piece of narration. Check the article has text in the Article section of Edit project, then use Retry stage.",
+        });
     if ((request.model ?? "inworld-tts-2") === "inworld-tts-2" && request.text.length > 4000) {
         yield* inworldAsync(deps, request, key);
         return;
@@ -64,7 +68,7 @@ async function* synthesizeRequest(deps, request, key) {
     if (request.text.length > 4000)
         throw providerError({
             kind: "unsupported",
-            message: "Inworld streaming accepts up to 4,000 characters per physical request. Rebuild narration with a supported request limit.",
+            message: "This narration part is longer than the 4,000 characters Inworld's Flash model takes at once. In the Providers section of Edit project, set Chunking to Paragraph or a smaller character count, or switch to the Realtime TTS-2 model.",
         });
     request.signal.throwIfAborted();
     const response = await deps.fetch("https://api.inworld.ai/tts/v1/voice:stream", {
@@ -90,12 +94,18 @@ async function* synthesizeRequest(deps, request, key) {
                     : response.status === 400 || response.status === 404
                         ? "unsupported"
                         : "other",
-            message: clean(`Inworld answered ${response.status} for voice ${request.voiceId}: ${detail || response.statusText}`, key),
+            message: clean(httpFailure({
+                provider: "Inworld",
+                status: response.status,
+                detail: detail || response.statusText,
+                subject: `narration request for voice "${request.voiceId}"`,
+                fix: voiceFix(request.voiceId),
+            }), key),
             ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
         });
     }
     if (response.body === null)
-        throw invalid("answered with no audio");
+        throw providerError({ kind: "other", message: noAudio("Inworld") });
     let heard = false;
     for await (const line of lines(response.body)) {
         request.signal.throwIfAborted();
@@ -104,11 +114,11 @@ async function* synthesizeRequest(deps, request, key) {
             raw = JSON.parse(line);
         }
         catch {
-            throw invalid("sent an unreadable audio chunk");
+            throw unreadableAudio();
         }
         const parsed = envelope.safeParse(raw);
         if (!parsed.success || (!parsed.data.result && !parsed.data.error))
-            throw invalid("sent an unreadable audio chunk");
+            throw unreadableAudio();
         if (parsed.data.error) {
             const { code, message } = parsed.data.error;
             throw providerError({
@@ -119,14 +129,14 @@ async function* synthesizeRequest(deps, request, key) {
                         : code === 3 || code === 5
                             ? "unsupported"
                             : "other",
-                message: `Inworld stream failed: ${clean(message ?? "audio generation stopped", key)}`,
+                message: streamFailure(code, clean(message ?? "", key), request.voiceId),
             });
         }
         const encoded = parsed.data.result?.audioContent;
         if (!encoded)
             continue;
         if (!/^[A-Za-z0-9+/]*={0,2}$/.test(encoded) || encoded.length % 4 === 1)
-            throw invalid("sent invalid encoded audio");
+            throw unreadableAudio();
         const audio = Buffer.from(encoded, "base64");
         if (audio.length === 0)
             continue;
@@ -134,7 +144,7 @@ async function* synthesizeRequest(deps, request, key) {
         yield audio;
     }
     if (!heard)
-        throw invalid("answered with no audio");
+        throw providerError({ kind: "other", message: noAudio("Inworld") });
 }
 async function* lines(body) {
     const reader = body.getReader();
@@ -147,7 +157,7 @@ async function* lines(body) {
             let end = pending.indexOf("\n");
             while (end !== -1) {
                 if (end > 8 * 1024 * 1024)
-                    throw invalid("sent an oversized audio chunk");
+                    throw unreadableAudio();
                 const line = pending.slice(0, end).trim();
                 pending = pending.slice(end + 1);
                 if (line)
@@ -155,7 +165,7 @@ async function* lines(body) {
                 end = pending.indexOf("\n");
             }
             if (pending.length > 8 * 1024 * 1024)
-                throw invalid("sent an oversized audio chunk");
+                throw unreadableAudio();
             if (done)
                 break;
         }
@@ -170,6 +180,6 @@ async function* lines(body) {
 function clean(message, key) {
     return redact(message.replaceAll(key, "[redacted]"));
 }
-function invalid(detail) {
-    return providerError({ kind: "other", message: `Inworld ${detail}.` });
+function unreadableAudio() {
+    return providerError({ kind: "other", message: unreadable("Inworld") });
 }

package/dist/adapters/tts/openai.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
+import { httpFailure, missingKey, noAudio, refreshList, unreadable, voiceFix } from "../explain.js";
 import { retryAfter } from "../retry-after.js";
 // The HTTP gateway adapter for OpenAI's speech endpoint. `fetch` and nothing else; the response
 // body is already the stream the port asks for.
@@ -34,12 +35,12 @@ export function openAiTts(deps) {
                 signal: AbortSignal.timeout(10_000),
             });
             if (!response.ok)
-                throw await failure(response);
+                throw await failure(response, undefined, refreshList);
             const parsed = modelList.safeParse(safeJson(await response.text()));
             if (!parsed.success) {
                 throw providerError({
                     kind: "other",
-                    message: "OpenAI's model list was not in the shape this app can read",
+                    message: unreadable("OpenAI"),
                 });
             }
             return parsed.data.data
@@ -68,7 +69,7 @@ export function openAiTts(deps) {
                 throw await failure(response, req.voiceId);
             }
             if (response.body === null) {
-                throw providerError({ kind: "other", message: "OpenAI answered with no audio" });
+                throw providerError({ kind: "other", message: noAudio("OpenAI") });
             }
             return { audio: response.body, container: "mp3" };
         },
@@ -81,7 +82,7 @@ function keyOf(deps) {
     const key = deps.key();
     // An absent key is terminal, so it never becomes a request.
     if (key === undefined || key === "") {
-        throw providerError({ kind: "missing_key", message: "no OpenAI key is stored" });
+        throw providerError({ kind: "missing_key", message: missingKey("OpenAI") });
     }
     return key;
 }
@@ -96,7 +97,7 @@ function kindOf(status) {
     // port's error contract has no terminal kind for a request that cannot be repaired.
     return "other";
 }
-async function failure(response, voiceId) {
+async function failure(response, voiceId, next) {
     const text = await response.text().catch(() => "");
     const parsed = errorBody.safeParse(safeJson(text));
     // Verbatim, through the same redactor the wrapper uses: OpenAI's own 401 quotes the
@@ -107,7 +108,18 @@ async function failure(response, voiceId) {
         kind: kindOf(response.status),
         // The voice ID is named, so a rejected voice reads differently from
         // a rejected key.
-        message: `OpenAI answered ${response.status}${voiceId === undefined ? "" : ` for voice ${voiceId}`}: ${message}`,
+        message: httpFailure({
+            provider: "OpenAI",
+            status: response.status,
+            detail: message,
+            next,
+            ...(voiceId === undefined
+                ? {}
+                : {
+                    subject: `narration request for voice "${voiceId}"`,
+                    fix: voiceFix(voiceId),
+                }),
+        }),
         ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
     });
 }

package/dist/catalog/registry.js

@@ -7,7 +7,7 @@ export function curateRegistry(registry, catalogue) {
         if (!model)
             throw providerError({
                 kind: "unsupported",
-                message: `${provider}: this model is not enabled in the current catalogue. Choose a supported model in Run settings.`,
+                message: `The chosen ${provider} model is no longer in Slopify's model list. In the Edit tab, choose Edit project and change it under Providers, then use Resume.`,
             });
         return model;
     };
@@ -21,7 +21,10 @@ export function curateRegistry(registry, catalogue) {
                     models: () => port.models(),
                     complete: async function* (request) {
                         if (request.model.trim() === "")
-                            throw providerError({ kind: "unsupported", message: "Choose a model ID." });
+                            throw providerError({
+                                kind: "unsupported",
+                                message: "No model is chosen for this step. In the Edit tab, choose Edit project and change it under Providers, then use Resume.",
+                            });
                         let models;
                         try {
                             models = await port.models();
@@ -34,19 +37,19 @@ export function curateRegistry(registry, catalogue) {
                         if (models !== undefined && selected === undefined)
                             throw providerError({
                                 kind: "unsupported",
-                                message: "This model is not available in the installed CLI.",
+                                message: "The chosen model is not available in the AI command-line tool on your computer. Update the tool, or pick another model: in the Edit tab, choose Edit project and change it under Providers, then use Resume.",
                             });
                         if (request.thinking !== undefined &&
                             selected !== undefined &&
                             !selected.thinkingModes?.includes(request.thinking))
                             throw providerError({
                                 kind: "unsupported",
-                                message: "This model does not support the selected thinking setting.",
+                                message: "The chosen model does not support this thinking setting. In the Edit tab, choose Edit project and change it under Providers, then use Resume.",
                             });
                         if (request.webSearch && !port.capabilities.webSearch)
                             throw providerError({
                                 kind: "unsupported",
-                                message: "This CLI does not support research web search.",
+                                message: "This command-line tool cannot search the web for research. Choose another text provider or turn Research off in the Edit tab under Edit project, then use Resume.",
                             });
                         const thinkingConfig = id === "codex" && request.thinking !== undefined
                             ? { effort: request.thinking === "off" ? "none" : request.thinking }
@@ -75,13 +78,13 @@ export function curateRegistry(registry, catalogue) {
                     if (request.webSearch && !model.llm.webSearch)
                         throw providerError({
                             kind: "unsupported",
-                            message: "This model does not support research web search.",
+                            message: "The chosen model cannot search the web for research. Choose another model or turn Research off in the Edit tab under Edit project, then use Resume.",
                         });
                     const thinkingConfig = request.thinking === undefined ? undefined : model.llm.thinking?.[request.thinking];
                     if (request.thinking !== undefined && !thinkingConfig)
                         throw providerError({
                             kind: "unsupported",
-                            message: "This model does not support the selected thinking setting. Choose an available setting.",
+                            message: "The chosen model does not support this thinking setting. In the Edit tab, choose Edit project and change it under Providers, then use Resume.",
                         });
                     yield* port.complete({
                         ...request,
@@ -100,7 +103,7 @@ export function curateRegistry(registry, catalogue) {
                         if (!(await port.models()).some((model) => model.id === request.model))
                             throw providerError({
                                 kind: "unsupported",
-                                message: "The Codex image capability is unavailable.",
+                                message: "Image generation is not available in the Codex CLI on your computer. Update Codex CLI, or choose another image provider in the Edit tab under Edit project, then use Resume.",
                             });
                         return port.generate(request);
                     },
@@ -114,7 +117,7 @@ export function curateRegistry(registry, catalogue) {
                     if (!("image" in model) || !model.image.aspectRatios.includes(request.aspect))
                         throw providerError({
                             kind: "unsupported",
-                            message: "This model does not support the selected video shape.",
+                            message: "The chosen image model cannot make images in this video's shape. In the Edit tab, choose Edit project and change it under Providers, then use Resume.",
                         });
                     return port.generate(request);
                 },
@@ -135,7 +138,7 @@ export function curateRegistry(registry, catalogue) {
                     if (request.text.length > model.tts.maxCharacters)
                         throw providerError({
                             kind: "unsupported",
-                            message: `${id}: this physical narration request exceeds the current ${model.tts.maxCharacters}-character limit. Rebuild narration to split it using the new limit.`,
+                            message: `A piece of narration is longer than this voice model's ${model.tts.maxCharacters}-character limit. Use Re-run section on Audio so Slopify splits it into shorter pieces.`,
                         });
                     return port.synthesize({ ...request, model: model.id });
                 },

package/dist/catalog/store.js

@@ -40,7 +40,7 @@ export function createCatalogueStore(deps) {
         }
         catch {
             warning =
-                "Your models.yaml is unavailable or invalid. The last valid catalogue is still in use.";
+                "Your models.yaml file is missing or has a mistake, so Slopify is still using the last working model list. Fix the file, or use Refresh published catalogue in Settings → Models to replace it.";
         }
         return current;
     }

package/dist/catalog/validate.js

@@ -31,16 +31,25 @@ export function modelFields(draft, catalogue) {
             continue;
         const model = catalogue.models(choice.provider, family).find((m) => m.id === choice.model);
         if (!model)
-            fields.push({ field, message: "Choose an enabled model from the current catalogue." });
+            fields.push({
+                field,
+                message: "This model is no longer in Slopify's model list. Choose another model.",
+            });
         else if ("llm" in model && choice.thinking && !model.llm.thinking?.[choice.thinking])
-            fields.push({ field, message: "Choose a supported thinking setting for this model." });
+            fields.push({
+                field,
+                message: "This model does not support that thinking setting. Choose another.",
+            });
         else if ("llm" in model && draft.sources.research === "generate" && !model.llm.webSearch)
             fields.push({
                 field,
-                message: "This model cannot perform web research. Choose another or turn Research off.",
+                message: "This model cannot search the web for research. Choose another model or turn Research off.",
             });
         else if ("image" in model && !model.image.aspectRatios.includes(draft.format))
-            fields.push({ field, message: "This image model does not support the selected shape." });
+            fields.push({
+                field,
+                message: "This image model cannot make images in this video's shape. Choose another model.",
+            });
     }
     return fields;
 }