@gentbajko/slopify 2.0.2 → 2.0.3

package/dist/adapters/image/models.js

@@ -64,9 +64,15 @@ export async function discoverGoogleImages(deps) {
 function requireKey(deps) {
     const key = deps.key();
     if (key === undefined || key === "")
-        throw providerError({ kind: "missing_key", message: "Save an API key to load models." });
+        throw providerError({
+            kind: "missing_key",
+            message: "Save this provider's API key in Settings → Providers to load its models.",
+        });
     return key;
 }
 function unavailable() {
-    return providerError({ kind: "other", message: "The provider model list could not be loaded." });
+    return providerError({
+        kind: "other",
+        message: "Slopify could not load this provider's model list. Check the API key in Settings → Providers and your internet connection, then refresh the list.",
+    });
 }

package/dist/adapters/image/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, noImage, refusedImage, unreadable } from "../explain.js";
 import { retryAfter } from "../retry-after.js";
 import { describeBytes, sniffImage } from "./bytes.js";
 import { discoverOpenAiImages } from "./models.js";
@@ -72,7 +73,7 @@ export function openAiImage(deps) {
             }
             const first = parse(await response.text()).data[0]?.b64_json;
             if (first === undefined || first === null || first === "") {
-                throw providerError({ kind: "other", message: "OpenAI answered with no image" });
+                throw providerError({ kind: "other", message: noImage("OpenAI") });
             }
             return decode(first);
         },
@@ -87,7 +88,7 @@ function decode(b64) {
     if (mime === undefined) {
         throw providerError({
             kind: "other",
-            message: `OpenAI's image decoded to ${describeBytes(bytes)} rather than a PNG or a JPEG`,
+            message: `OpenAI sent back something that is not a PNG or JPEG image (${describeBytes(bytes)}). Use Retry stage; if it keeps happening, choose another image model in the Providers section of Edit project.`,
         });
     }
     return { bytes, mime };
@@ -96,7 +97,7 @@ function keyOf(deps) {
     // `missing_key`, not `auth`, because that rule makes it terminal.
     const key = deps.key();
     if (key === undefined || key === "") {
-        throw providerError({ kind: "missing_key", message: "no OpenAI image key is stored" });
+        throw providerError({ kind: "missing_key", message: missingKey("OpenAI") });
     }
     return key;
 }
@@ -122,9 +123,17 @@ async function failure(response) {
     // The provider's own words, through the redactor - an error body may quote the key back.
     const message = redact(parsed.success ? parsed.data.error.message : text.trim() || response.statusText);
     const retryAfterMs = retryAfter(response.headers.get("retry-after"));
+    const kind = kindOf(response.status, parsed.success ? parsed.data.error.code : undefined);
     return providerError({
-        kind: kindOf(response.status, parsed.success ? parsed.data.error.code : undefined),
-        message: `OpenAI answered ${String(response.status)}: ${message}`,
+        kind,
+        message: kind === "refusal"
+            ? refusedImage("OpenAI", message)
+            : httpFailure({
+                provider: "OpenAI",
+                status: response.status,
+                detail: message,
+                subject: "image request",
+            }),
         ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
     });
 }
@@ -133,7 +142,7 @@ function parse(text) {
     if (!parsed.success) {
         throw providerError({
             kind: "other",
-            message: "OpenAI's answer was not in the shape this app can read",
+            message: unreadable("OpenAI"),
         });
     }
     return parsed.data;

package/dist/adapters/image/replicate.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, noImage, providerSaid, refusedImage, unreadable, } from "../explain.js";
 import { retryAfter } from "../retry-after.js";
 import { downloadImage } from "./bytes.js";
 // The HTTP gateway adapter for Replicate: `fetch`, the injected clock and the downloader
@@ -81,7 +82,7 @@ async function settle(deps, first, signal) {
         if (next === undefined) {
             throw providerError({
                 kind: "other",
-                message: `Replicate left the prediction ${current.status} and named no address to read it from`,
+                message: unreadable("Replicate"),
             });
         }
         await deps.clock.sleep(replicatePollMs, signal);
@@ -100,7 +101,7 @@ function outputOf(current) {
     const output = current.output;
     const url = typeof output === "string" ? output : output?.[0];
     if (url === undefined || url === "") {
-        throw providerError({ kind: "other", message: "Replicate succeeded with no image" });
+        throw providerError({ kind: "other", message: noImage("Replicate") });
     }
     return url;
 }
@@ -114,16 +115,19 @@ function declined(current) {
     // ceiling: read off the sentence, because a failed prediction carries no machine-readable
     // reason. A phrase the list does not know costs the user three more images; the upgrade
     // is a structured field, when Replicate ships one.
+    const refusal = refusalWords.test(message);
     return providerError({
-        kind: refusalWords.test(message) ? "refusal" : "other",
-        message: `Replicate answered: ${message}`,
+        kind: refusal ? "refusal" : "other",
+        message: refusal
+            ? refusedImage("Replicate", message)
+            : providerSaid("Replicate", "could not make the image", message, "Use Retry stage; if it keeps happening, reword the image prompt in the Images section of Edit project or choose another image model in its Providers section."),
     });
 }
 function auth(deps) {
     // `missing_key`, not `auth`, because that rule makes it terminal.
     const key = deps.key();
     if (key === undefined || key === "") {
-        throw providerError({ kind: "missing_key", message: "no Replicate key is stored" });
+        throw providerError({ kind: "missing_key", message: missingKey("Replicate") });
     }
     return { Authorization: `Bearer ${key}` };
 }
@@ -149,7 +153,12 @@ async function failure(response) {
     const retryAfterMs = retryAfter(response.headers.get("retry-after"));
     return providerError({
         kind: kindOf(response.status),
-        message: `Replicate answered ${String(response.status)}: ${message || response.statusText}`,
+        message: httpFailure({
+            provider: "Replicate",
+            status: response.status,
+            detail: message || response.statusText,
+            subject: "image request",
+        }),
         ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
     });
 }
@@ -158,7 +167,7 @@ function parse(text) {
     if (!parsed.success) {
         throw providerError({
             kind: "other",
-            message: "Replicate's answer was not in the shape this app can read",
+            message: unreadable("Replicate"),
         });
     }
     return parsed.data;

package/dist/adapters/llm/claude-code-models.js

@@ -38,7 +38,7 @@ const responseSchema = z.object({
 });
 const supportedEfforts = ["low", "medium", "high", "xhigh"];
 function unavailable() {
-    return new Error("Claude Code model discovery is unavailable. Refresh the list or enter an exact model ID.");
+    return new Error("Slopify could not get the model list from the Claude Code CLI. Check the CLI is installed and signed in (Settings → Providers), then refresh the list, or type an exact model ID.");
 }
 function discoveryEnv() {
     const names = [

package/dist/adapters/llm/claude-code.js

@@ -1,10 +1,11 @@
 import { z } from "zod";
 import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
+import { cliCheck, cliReported, commandOf } from "../explain.js";
 import { nodeClaudeCodeModels } from "./claude-code-models.js";
 import { cliLoginError } from "./cli-login-error.js";
 import { documentToolName, documentWorkspace, } from "./document-workspace.js";
-import { cliEvent, cliInput, cliShaped, endedWithout, promptOf, stopCliRun } from "./run-cli.js";
+import { cliEvent, cliInput, cliShaped, endedWithout, promptOf, stopCliRun, stuckCli, } from "./run-cli.js";
 import { lines } from "./sse-lines.js";
 // The local-agent adapter for Claude Code: spawned non-interactively, authenticated by the
 // CLI's own login, no key anywhere in this file. Readiness is not computed here - `adapters/**`
@@ -142,7 +143,7 @@ export function claudeCodeLlm(deps) {
                 catch {
                     throw providerError({
                         kind: "unavailable",
-                        message: "The full prompt could not be delivered to Claude Code. Review before retrying.",
+                        message: "Slopify could not hand the whole prompt to the Claude Code CLI, so it cannot tell what the CLI worked on (it may already have used your quota). Use Retry stage to run it again.",
                     });
                 }
                 if (result.is_error === true || result.subtype !== "success") {
@@ -151,7 +152,7 @@ export function claudeCodeLlm(deps) {
                         throw login;
                     throw providerError({
                         kind: kindOf(result.api_error_status ?? null),
-                        message: redact(result.result ?? result.subtype),
+                        message: cliReported(binary, redact(result.result ?? result.subtype), nextStep(binary, result.api_error_status ?? null)),
                     });
                 }
                 documents?.verifyRead();
@@ -188,15 +189,13 @@ export function claudeCodeLlm(deps) {
         req.signal.throwIfAborted();
         // The stream ended with no result event at all.
         if (!run)
-            throw new Error("Claude Code could not be started.");
+            throw new Error("The Claude Code CLI could not be started. Check it is installed and set up in Settings → Providers, then use Retry stage.");
         const login = cliLoginError("claude-code", run.stderr());
         if (login)
             throw login;
         throw providerError({
             kind: "other",
-            message: ended === undefined
-                ? `the ${binary} CLI did not stop after forced termination`
-                : endedWithout(binary, ended, run.stderr()),
+            message: ended === undefined ? stuckCli(binary) : endedWithout(binary, ended, run.stderr()),
         });
     }
     return {
@@ -218,6 +217,16 @@ function kindOf(status) {
     }
     return "other";
 }
+// What most often fixes the upstream status the CLI passed on.
+function nextStep(binary, status) {
+    if (status === 401 || status === 403)
+        return `Run "${commandOf(binary)} auth login" in a terminal to sign in again, then use Retry stage.`;
+    if (status === 429)
+        return "Your Claude usage limit may be used up: wait until it resets, then use Retry stage.";
+    if (status === 404)
+        return "The chosen model may not exist or not be available to your account: choose another in the Providers section of Edit project, then use Retry stage.";
+    return cliCheck(binary);
+}
 // `modelUsage` is keyed by model id and a run may touch more than one - a fallback model,
 // a sub-agent - so the counts are summed. An empty object means the CLI reported none.
 function usageOf(usage) {

package/dist/adapters/llm/cli-login-error.js

@@ -1,4 +1,5 @@
 import { providerError } from "../../kernel/ports/model.js";
+import { cliName } from "../explain.js";
 export function cliLoginError(provider, text) {
     if (/invalid api key/i.test(text))
         return undefined;
@@ -11,6 +12,6 @@ export function cliLoginError(provider, text) {
             : "codex login";
     return providerError({
         kind: "missing_key",
-        message: `${provider}: sign in on the machine running the CLI with ${command}, then review the affected rebuild.`,
+        message: `The ${cliName(provider)} is not signed in, or its sign-in has expired. Open a terminal on the computer running the CLI, run "${command}" and sign in, then use Retry stage.`,
     });
 }

package/dist/adapters/llm/codex-models.js

@@ -58,7 +58,7 @@ export async function nodeCodexModels(env = process.env, binary = "codex", timeo
         }
         catch {
             // Do not expose cache contents, home paths or raw JSON errors to the browser.
-            throw new Error("Codex model metadata is unavailable. Check the CLI and refresh, or enter a custom model ID.");
+            throw new Error("Slopify could not get the model list from the Codex CLI. Check the CLI is installed and signed in (Settings → Providers), then refresh the list, or type an exact model ID.");
         }
     }
 }

package/dist/adapters/llm/codex.js

@@ -4,10 +4,11 @@ import { join } from "node:path";
 import { z } from "zod";
 import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
+import { cliCheck, cliReported } from "../explain.js";
 import { cliLoginError } from "./cli-login-error.js";
 import { nodeCodexModels } from "./codex-models.js";
 import { documentServerName, documentTool, documentWorkspace, } from "./document-workspace.js";
-import { cliEvent, cliInput, cliShaped, deliveredInput, endedWithout, promptOf, stopCliRun, } from "./run-cli.js";
+import { cliEvent, cliInput, cliShaped, deliveredInput, endedWithout, promptOf, stopCliRun, stuckCli, } from "./run-cli.js";
 import { lines } from "./sse-lines.js";
 // The local-agent adapter for the Codex CLI. Same shape as Claude Code's and a different
 // vocabulary: Codex writes a JSONL thread of `thread.started`, `item.*` and `turn.*`
@@ -164,7 +165,7 @@ export function codexLlm(deps) {
                         throw login;
                     throw providerError({
                         kind: "other",
-                        message: redact(cliShaped(binary, turnFailed, event.value).error.message),
+                        message: cliReported(binary, redact(cliShaped(binary, turnFailed, event.value).error.message), cliCheck(binary)),
                     });
                 }
                 if (event.type === "error") {
@@ -173,7 +174,7 @@ export function codexLlm(deps) {
                         throw login;
                     throw providerError({
                         kind: "other",
-                        message: redact(cliShaped(binary, errorEvent, event.value).message),
+                        message: cliReported(binary, redact(cliShaped(binary, errorEvent, event.value).message), cliCheck(binary)),
                     });
                 }
             }
@@ -202,9 +203,7 @@ export function codexLlm(deps) {
             throw login;
         throw providerError({
             kind: "other",
-            message: ended === undefined
-                ? `the ${binary} CLI did not stop after forced termination`
-                : endedWithout(binary, ended, run.stderr()),
+            message: ended === undefined ? stuckCli(binary) : endedWithout(binary, ended, run.stderr()),
         });
     }
     return {

package/dist/adapters/llm/document-workspace.js

@@ -16,7 +16,7 @@ export function documentWorkspace(input) {
     if (!parsed.success)
         throw providerError({
             kind: "unsupported",
-            message: "Research documents are invalid or exceed the supported request size. No document was truncated.",
+            message: "The research notes are too large, or not in a form the AI model can be given, so nothing was sent. Make the inputs shorter in Edit project, then use Retry stage; if it keeps happening, use Download diagnostics in Settings and report it.",
         });
     const documents = parsed.data;
     const directory = mkdtempSync(join(tmpdir(), "slopify-documents-"));
@@ -82,6 +82,6 @@ export function documentWorkspace(input) {
 function unread() {
     return providerError({
         kind: "unavailable",
-        message: "The CLI did not read every research document in full. Review the work before retrying; the provider may have charged for this attempt.",
+        message: "The AI model did not read all of the research notes, so its answer was not used (the attempt may still have used your quota). Use Retry stage; if it keeps happening, choose another model in the Providers section of Edit project.",
     });
 }

package/dist/adapters/llm/gemini-models.js

@@ -38,7 +38,7 @@ export async function nodeGeminiModels(binary) {
         throw new Error("No installed model metadata");
     }
     catch {
-        throw new Error("Gemini CLI model metadata is unavailable. Use a documented CLI alias or enter a custom model ID.");
+        throw new Error("Slopify could not get the model list from the Gemini CLI. Check the CLI is installed (Settings → Providers), then refresh the list, or type a model name the Gemini CLI accepts.");
     }
 }
 async function bundledModels(entry) {

package/dist/adapters/llm/gemini-workspace.js

@@ -33,7 +33,7 @@ export function geminiWorkspace(webSearch, request, documents, env = process.env
             catch {
                 throw providerError({
                     kind: "unavailable",
-                    message: "Gemini CLI login settings could not be read. Check its settings.json before retrying.",
+                    message: "Slopify could not read the Gemini CLI's settings file (settings.json in the .gemini folder of your home directory), which says how it signs in. Fix or remove that file, run gemini in a terminal to sign in again, then use Retry stage.",
                 });
             }
         const oauth = join(originalState, "oauth_creds.json");

package/dist/adapters/llm/gemini.js

@@ -1,10 +1,11 @@
 import { z } from "zod";
 import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
+import { cliCheck, cliName, cliReported } from "../explain.js";
 import { documentWorkspace } from "./document-workspace.js";
 import { nodeGeminiModels } from "./gemini-models.js";
 import { geminiWorkspace } from "./gemini-workspace.js";
-import { cliEvent, cliInput, cliShaped, deliveredInput, endedWithout, promptOf, stopCliRun, } from "./run-cli.js";
+import { cliEvent, cliInput, cliShaped, deliveredInput, endedWithout, promptOf, stopCliRun, stuckCli, } from "./run-cli.js";
 import { lines } from "./sse-lines.js";
 export const geminiBinary = "gemini";
 // Verified against installed Gemini CLI 0.16.0's config/nonInteractiveCli sources.
@@ -65,12 +66,12 @@ export function geminiLlm(deps) {
                 else if (event.type === "error") {
                     const error = cliShaped(binary, errorSchema, event.value);
                     if (error.severity !== "warning")
-                        throw failure(error.message);
+                        throw failure(binary, error.message);
                 }
                 else if (event.type === "result") {
                     const result = cliShaped(binary, resultSchema, event.value);
                     if (result.status !== "success")
-                        throw failure(result.error?.message ?? result.status);
+                        throw failure(binary, result.error?.message ?? result.status);
                     await deliveredInput(run);
                     documents?.verifyRead();
                     yield {
@@ -103,12 +104,10 @@ export function geminiLlm(deps) {
         }
         req.signal.throwIfAborted();
         if (run === undefined)
-            throw failure(`the ${binary} CLI could not be started`);
+            throw failure(binary, "", `The ${cliName(binary)} could not be started. Check it is installed and set up in Settings → Providers, then use Retry stage.`);
         if (authRequired(run.stderr()))
             throw authFailure();
-        throw failure(ended === undefined
-            ? `the ${binary} CLI did not stop after forced termination`
-            : endedWithout(binary, ended, run.stderr()));
+        throw failure(binary, run.stderr(), ended === undefined ? stuckCli(binary) : endedWithout(binary, ended, run.stderr()));
     }
     return {
         id: "gemini",
@@ -117,16 +116,21 @@ export function geminiLlm(deps) {
         complete,
     };
 }
-function failure(message) {
+// `message` is what the CLI said, read for the two failures that need the user's hand;
+// `sentence` replaces the default wording when Slopify already knows what happened.
+function failure(binary, message, sentence) {
     if (/(?:#?3501\b|do not have a valid licen[cs]e of this product)/i.test(message)) {
         return providerError({
             kind: "unsupported",
-            message: "Gemini CLI access was denied by Google's license check (#3501). Update Gemini CLI and sign in again. For a managed account, contact your administrator to request a license.",
+            message: "Google refused the Gemini CLI because the signed-in account has no licence for it (#3501). Update the Gemini CLI, run gemini in a terminal to sign in again, then use Retry stage; for a work or school account, ask your administrator for a Gemini licence.",
         });
     }
     return authRequired(message)
         ? authFailure()
-        : providerError({ kind: "other", message: redact(message) });
+        : providerError({
+            kind: "other",
+            message: sentence ?? cliReported(binary, redact(message), cliCheck(binary)),
+        });
 }
 function authRequired(message) {
     return /Code Assist login required|authorize the application|authorization code|Please set an Auth method|re-authenticate|reauthenticate/i.test(message);
@@ -134,7 +138,7 @@ function authRequired(message) {
 function authFailure() {
     return providerError({
         kind: "missing_key",
-        message: "Gemini CLI needs sign-in. Run gemini in your terminal, complete login, then retry in Slopify.",
+        message: 'The Gemini CLI is not signed in, or its sign-in has expired. Open a terminal on the computer running the CLI, run "gemini" and sign in, then use Retry stage.',
     });
 }
 async function* authChecked(source) {

package/dist/adapters/llm/openrouter.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { redact } from "../../kernel/log.js";
 import { documentMessages } from "../../kernel/ports/llm-documents.js";
 import { providerError } from "../../kernel/ports/model.js";
+import { droppedStream, httpFailure, missingKey, providerSaid, refreshList, unreadable, } from "../explain.js";
 import { retryAfter } from "../retry-after.js";
 import { sseData } from "./sse-lines.js";
 // The HTTP gateway adapter: the platform's own `fetch` plus the line reader beside this
@@ -62,7 +63,7 @@ export function openRouterLlm(deps) {
             throw await failure(response);
         }
         if (response.body === null) {
-            throw providerError({ kind: "other", message: "OpenRouter answered with no body" });
+            throw providerError({ kind: "other", message: droppedStream("OpenRouter") });
         }
         let usage = null;
         let finishReason = null;
@@ -81,7 +82,7 @@ export function openRouterLlm(deps) {
                 // frame; without this the stage would store half an article as a success.
                 throw providerError({
                     kind: kindOf(statusOf(chunk.error.code)),
-                    message: redact(chunk.error.message),
+                    message: streamFailure(statusOf(chunk.error.code), redact(chunk.error.message)),
                 });
             }
             const choice = chunk.choices?.[0];
@@ -108,7 +109,7 @@ export function openRouterLlm(deps) {
             // Saying so is what stops a truncated answer being stored as a whole one.
             throw providerError({
                 kind: "other",
-                message: "OpenRouter's stream ended before the response was complete",
+                message: droppedStream("OpenRouter"),
             });
         }
         yield { type: "done", usage, finishReason };
@@ -122,13 +123,13 @@ export function openRouterLlm(deps) {
                 headers: headers(deps.key()),
             });
             if (!response.ok) {
-                throw await failure(response);
+                throw await failure(response, refreshList);
             }
             const parsed = modelList.safeParse(await response.json());
             if (!parsed.success) {
                 throw providerError({
                     kind: "other",
-                    message: "OpenRouter's model list was not in the shape this app can read",
+                    message: unreadable("OpenRouter"),
                 });
             }
             // /models defaults to text output. Also reject an explicit non-text row
@@ -146,7 +147,7 @@ function headers(key) {
     // rather than `auth` because the same rule makes it terminal: there is nothing to
     // retry until the user saves a key, and the wrapper is where that is decided.
     if (key === undefined || key === "") {
-        throw providerError({ kind: "missing_key", message: "no OpenRouter key is stored" });
+        throw providerError({ kind: "missing_key", message: missingKey("OpenRouter") });
     }
     return { Authorization: `Bearer ${key}`, ...appHeaders };
 }
@@ -163,7 +164,7 @@ function kindOf(status) {
     // error contract first, which is not this adapter's to widen.
     return "other";
 }
-async function failure(response) {
+async function failure(response, next) {
     const text = await response.text().catch(() => "");
     const parsed = errorBody.safeParse(safeJson(text));
     // The provider's own words, through the redactor - an error body may quote the key back.
@@ -171,10 +172,21 @@ async function failure(response) {
     const retryAfterMs = retryAfter(response.headers.get("retry-after"));
     return providerError({
         kind: kindOf(response.status),
-        message: `OpenRouter answered ${response.status}: ${message}`,
+        message: httpFailure({
+            provider: "OpenRouter",
+            status: response.status,
+            detail: message,
+            next,
+        }),
         ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
     });
 }
+// A mid-stream error carries an HTTP-like code; with none, the provider's words are all there is.
+function streamFailure(status, detail) {
+    return status >= 400
+        ? httpFailure({ provider: "OpenRouter", status, detail })
+        : providerSaid("OpenRouter", "stopped part-way through the answer", detail, "Use Retry stage; if it keeps happening, choose another model in the Providers section of Edit project.");
+}
 function statusOf(code) {
     return typeof code === "number" ? code : Number(code ?? 0);
 }
@@ -186,7 +198,7 @@ function parseChunk(data) {
         // a half-written frame is noise, and the wrapper stores whatever is thrown.
         throw providerError({
             kind: "other",
-            message: "OpenRouter sent a stream frame this app could not read",
+            message: unreadable("OpenRouter"),
         });
     }
     return parsed.data;

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 }),
     });
 }