@gentbajko/slopify 2.0.2 → 2.0.3

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

package/dist/edge/cli.js

@@ -23,17 +23,18 @@ const { values } = parseArgs({
         "accept-host-cli": { type: "boolean" },
     },
 });
+let config;
 try {
     if (values["projects-dir"] !== undefined && !values.docker)
-        throw new Error("--projects-dir requires --docker; native installs use --data-dir.");
+        throw new Error("--projects-dir only works together with --docker. Without Docker, choose where Slopify keeps its files with --data-dir <folder>.");
     if ((values["host-cli"] !== undefined || values["accept-host-cli"] !== undefined) &&
         !values.docker)
-        throw new Error("Host CLI options require --docker.");
+        throw new Error("--host-cli and --accept-host-cli only work together with --docker. Add --docker, or remove those options.");
     if (values["host-cli"] !== undefined && values["host-cli"] !== "off")
-        throw new Error("The --host-cli override supports only off (API-only Docker).");
+        throw new Error(`--host-cli=${values["host-cli"]} is not supported. The only value is --host-cli=off, which starts Docker using API keys only; leave the option out to use the AI CLIs installed on this machine.`);
     if (values.docker) {
         if (values.host !== undefined || values["data-dir"] !== undefined)
-            throw new Error("Docker keeps private data in its named volume and binds to localhost. Use --projects-dir for project files and --port for the port.");
+            throw new Error("--host and --data-dir can't be used with --docker: the Docker version always listens on localhost and keeps its data in a Docker volume. Use --projects-dir <folder> for project files and --port <number> for the port.");
         const docker = await import("./docker.js");
         docker.assertManagedDockerHost(process.platform, process.getuid?.(), process.getgid?.());
         const { prepareDockerHostCli } = docker;
@@ -73,10 +74,10 @@ try {
             },
         });
         if (result.error)
-            throw result.error;
+            throw new Error(`Could not start the Docker launcher script (${result.error.message}). Make sure bash is installed and on your PATH, then try again.`);
         process.exit(result.status ?? 1);
     }
-    const config = configFrom(values, process.env);
+    config = configFrom(values, process.env);
     const forwarded = await forwardManagedUpdate(config.dataDir, readVersion(), process.argv.slice(2));
     if (forwarded !== undefined)
         process.exit(forwarded);
@@ -103,6 +104,31 @@ try {
     });
 }
 catch (error) {
-    console.error(error instanceof Error ? error.message : String(error));
+    console.error(explainStartupError(error, config));
     process.exit(1);
 }
+// Node's own wording for a failed listen or file operation ("listen EADDRINUSE: address already
+// in use") names the symptom but not the fix, so the common startup failures are restated here.
+function explainStartupError(error, config) {
+    if (!(error instanceof Error))
+        return String(error);
+    const code = "code" in error && typeof error.code === "string" ? error.code : undefined;
+    const syscall = "syscall" in error && typeof error.syscall === "string" ? error.syscall : "";
+    if (config !== undefined && syscall === "listen") {
+        const other = config.port === 7070 ? 7071 : 7070;
+        if (code === "EADDRINUSE")
+            return `Port ${config.port} is already in use by another program (maybe another Slopify). Stop that program, or start Slopify on another port: npx @gentbajko/slopify --port ${other}`;
+        if (code === "EACCES" || code === "EPERM")
+            return `Slopify is not allowed to use port ${config.port}${config.port < 1024 ? " (ports below 1024 need administrator rights)" : ""}. Start it on another port: npx @gentbajko/slopify --port ${other}`;
+        if (code === "EADDRNOTAVAIL" || code === "ENOTFOUND" || code === "EAI_AGAIN")
+            return `Slopify can't listen on ${config.host} because that address doesn't belong to this machine. Leave out --host (and SLOPIFY_HOST) to use 127.0.0.1, or use an address this machine owns.`;
+    }
+    const path = "path" in error && typeof error.path === "string" ? error.path : undefined;
+    if (config !== undefined &&
+        path?.startsWith(config.dataDir) &&
+        (code === "EACCES" || code === "EPERM" || code === "EROFS"))
+        return `Slopify can't write to its data folder ${config.dataDir} (${error.message}). Make sure your user owns that folder and can write to it, or choose another one: npx @gentbajko/slopify --data-dir <folder>`;
+    if (code === "ENOSPC")
+        return `The disk is full (${error.message}). Free up some space and start Slopify again.`;
+    return error.message;
+}