@gentbajko/slopify 2.0.1 → 2.0.3

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,14 +74,17 @@ 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);
-    const { paths, url, stop } = await boot(config);
+    const { paths, url, stop } = await boot(config, {
+        prefetchSubtitleModel: ["", "0", "false"].includes((process.env.SLOPIFY_NO_MODEL_PREFETCH ?? "").trim().toLowerCase()),
+        subtitleModelSeed: process.env.SLOPIFY_SUBTITLE_MODEL_SEED?.trim() || undefined,
+    });
     console.log(`Slopify is running at ${url}`);
     console.log(`Slopify data directory: ${paths.dataDir}`);
     console.log(`Database: ${paths.db}`);
@@ -100,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;
+}

package/dist/edge/docker-launch.js

@@ -15,7 +15,7 @@ async function main() {
     const gid = process.getgid?.();
     assertManagedDockerHost(process.platform, uid, gid);
     if (gid === undefined)
-        throw new Error("Missing host group.");
+        throw new Error("Could not read your user's group. Run the --docker launcher as your normal logged-in user.");
     const c = dockerConfig(process.env, homedir(), process.cwd(), uid, gid);
     await privateDirectory(c.root, uid);
     if (process.argv[2] !== "--locked") {
@@ -24,7 +24,7 @@ async function main() {
         try {
             const s = await fd.stat();
             if (!s.isFile() || s.nlink !== 1 || s.uid !== uid || (s.mode & 0o077) !== 0)
-                throw new Error("Unsafe Docker setup lock.");
+                throw new Error(`The launcher's lock file ${path} has the wrong owner or permissions. Delete it and run the launcher again.`);
             const child = spawn("flock", [
                 "--nonblock",
                 "--no-fork",
@@ -36,13 +36,13 @@ async function main() {
                 "--locked",
             ], { stdio: "inherit" });
             const code = await new Promise((resolve, reject) => {
-                child.once("error", () => reject(new Error("Install util-linux (flock) before using the managed Docker launcher.")));
+                child.once("error", () => reject(new Error("The --docker launcher needs the flock command, which isn't installed. Install util-linux (for example sudo apt install util-linux, or sudo pacman -S util-linux) and try again.")));
                 child.once("exit", (status, signal) => signal
-                    ? reject(new Error("Docker setup was interrupted; rerun to recover."))
+                    ? reject(new Error("Docker setup was interrupted before it finished. Run the same command again; Slopify will finish or undo the half-done step."))
                     : resolve(status ?? 1));
             });
             if (code === 73)
-                throw new Error("Another managed Docker installation is changing storage. Wait for it to finish and rerun.");
+                throw new Error("Another Slopify --docker launcher is already running and changing your installation. Wait for it to finish, then run the command again.");
             process.exitCode = code;
             return;
         }
@@ -51,7 +51,7 @@ async function main() {
         }
     }
     const controller = new AbortController();
-    const abort = () => controller.abort(new Error("Docker setup interrupted."));
+    const abort = () => controller.abort(new Error("Docker setup was stopped before it finished. Run the same command again; Slopify will finish or undo the half-done step."));
     process.once("SIGINT", abort);
     process.once("SIGTERM", abort);
     try {

package/dist/edge/docker-projects/engine.js

@@ -4,12 +4,27 @@ import { setTimeout as delay } from "node:timers/promises";
 import { z } from "zod";
 import { containerSchema, digestSchema, } from "./state.js";
 import { contains } from "./tree.js";
+// Docker's exit code alone says nothing, so its last error line decides the advice: the daemon
+// being stopped and the socket being off-limits are by far the most common first-run failures.
+export function dockerFailure(args, result) {
+    const detail = (result.stderr ?? "").trim();
+    if (/permission denied[^\n]*docker\.sock|docker\.sock[^\n]*permission denied/i.test(detail))
+        return "Your user isn't allowed to use Docker. Give it access with sudo usermod -aG docker $USER, then log out and back in (or run newgrp docker) and try again.";
+    if (/cannot connect to the docker daemon|is the docker daemon running|error during connect/i.test(detail))
+        return "Docker is installed but not running. Start it (sudo systemctl start docker, or systemctl --user start docker for rootless Docker) and try again.";
+    if (/port is already allocated|address already in use/i.test(detail))
+        return "The port Slopify wants is already in use by another program. Stop that program, or start Slopify on another port: npx @gentbajko/slopify --docker --port 7070";
+    if (/no space left on device/i.test(detail))
+        return "The disk Docker uses is full. Free up space (for example docker system prune) and try again.";
+    const last = detail.split("\n").at(-1)?.trim().slice(0, 300);
+    return `Docker command "docker ${args[0] ?? ""}" failed (exit code ${result.code}${last ? `: ${last}` : ""}). Check that Docker works (docker info) and run the launcher again. Nothing was deleted, and any backup Slopify made is kept.`;
+}
 export function dockerEngine(runner, signal, env) {
     const run = (args, localSignal = signal) => runner.exec("docker", args, localSignal);
     async function command(args, localSignal = signal) {
         const r = await run(args, localSignal);
         if (r.code !== 0)
-            throw new Error(`Docker ${args[0] ?? "command"} failed; recovery material is retained.`);
+            throw new Error(dockerFailure(args, r));
         return r.stdout.trim();
     }
     const mount = (type, source, target, readonly = false) => [
@@ -48,14 +63,14 @@ export function dockerEngine(runner, signal, env) {
             "{{.ID}}",
         ]);
         if (present.code !== 0)
-            throw new Error("Docker container inventory failed.");
+            throw new Error(dockerFailure(["container", "ls"], present));
         if (!present.stdout.trim() && !/^[a-f0-9]{12,64}$/.test(name))
             return null;
         const result = await run(["inspect", name]);
         if (result.code !== 0) {
             if (!present.stdout.trim())
                 return null;
-            throw new Error("Docker inspect failed.");
+            throw new Error(dockerFailure(["inspect", name], result));
         }
         const schema = z.array(z.object({
             Id: z.string(),
@@ -105,11 +120,11 @@ export function dockerEngine(runner, signal, env) {
         for (const id of ids) {
             const c = await inspect(id);
             if (!c)
-                throw new Error("Cannot verify volume claims; an inventoried container is missing.");
+                throw new Error("Cannot verify volume claims: a Docker container disappeared while Slopify was checking. Run the launcher again.");
             if (!permitted.includes(c.id) &&
                 !spared(c) &&
                 c.mounts.some((m) => m.type === "volume" && m.name === volume))
-                throw new Error(`Another container claims installation volume ${volume}: ${c.name}.`);
+                throw new Error(`The Docker volume ${volume} that holds Slopify's data is also used by the container ${c.name}. Remove that container if you no longer need it (docker rm ${c.name}), or give this Slopify its own volume with SLOPIFY_DOCKER_VOLUME=<name>, then try again.`);
         }
     }
     async function writers(volume, paths, permitted) {
@@ -122,7 +137,7 @@ export function dockerEngine(runner, signal, env) {
                 (m.name === volume ||
                     (m.type === "bind" &&
                         paths.some((p) => contains(p, m.source) || contains(m.source, p))))))
-                throw new Error(`Another running container writes installation storage: ${c.name}. Stop it before retrying.`);
+                throw new Error(`Another running container (${c.name}) is writing to Slopify's data or project folder. Stop it (docker stop ${c.name}) and try again.`);
         }
     }
     async function recoveryLabel(j) {
@@ -154,7 +169,13 @@ export function dockerEngine(runner, signal, env) {
                     .parse(raw)[0]?.Endpoints.docker.Host;
             }
             if (!endpoint?.startsWith("unix://"))
-                throw new Error("Managed folders require a local Linux Docker unix socket; remote daemons are unsupported.");
+                throw new Error(`The --docker launcher only works with Docker running on this machine, not a remote Docker (${endpoint ?? "unknown endpoint"}). Switch to the local one (unset DOCKER_HOST, or docker context use default) and try again.`);
+            const rawInfo = JSON.parse(await command(["info", "--format", "{{json .}}"]));
+            // Some Docker versions print the daemon's absence inside the JSON instead of failing.
+            const serverErrors = z.object({ ServerErrors: z.array(z.string()) }).safeParse(rawInfo)
+                .data?.ServerErrors;
+            if (serverErrors !== undefined && serverErrors.length > 0)
+                throw new Error(dockerFailure(["info"], { code: 1, stderr: serverErrors.join("\n") }));
             const info = z
                 .object({
                 ID: z.string(),
@@ -162,12 +183,12 @@ export function dockerEngine(runner, signal, env) {
                 OperatingSystem: z.string(),
                 SecurityOptions: z.array(z.string()),
             })
-                .parse(JSON.parse(await command(["info", "--format", "{{json .}}"])));
+                .parse(rawInfo);
             if (/docker desktop/i.test(info.OperatingSystem))
-                throw new Error("Docker Desktop is unsupported by managed project folders. Use a native Linux Docker daemon or native Slopify.");
+                throw new Error("Docker Desktop isn't supported by the --docker launcher because it can't give your project folder the right owner. Use Docker Engine on Linux (docker context use default), or run Slopify without Docker: npx @gentbajko/slopify");
             const rootless = info.SecurityOptions.includes("name=rootless");
             if (!rootless && info.SecurityOptions.some((s) => s.startsWith("name=userns")))
-                throw new Error("Docker userns-remap is unsupported by managed project folders. Use a supported rootless daemon or native Slopify; do not disable isolation.");
+                throw new Error("Your Docker uses userns-remap, which the --docker launcher doesn't support. Use rootless Docker or a standard Docker Engine setup, or run Slopify without Docker: npx @gentbajko/slopify. Don't turn off Docker's isolation to get around this.");
             return { daemon: info.ID, user: rootless ? "0:0" : `${uid}:${gid}` };
         },
         image: async (ref) => {
@@ -214,7 +235,7 @@ export function dockerEngine(runner, signal, env) {
             })
                 .parse(JSON.parse(await command(["volume", "inspect", "--format", "{{json .}}", name])));
             if (v.Name !== name || (v.Options && Object.keys(v.Options).length > 0))
-                throw new Error("Managed projects require an ordinary local named volume; remote/custom volume drivers are unsupported.");
+                throw new Error(`The Docker volume ${name} uses a custom driver or options, which Slopify doesn't support. Give Slopify a plain local volume with SLOPIFY_DOCKER_VOLUME=<new name> and try again.`);
             return JSON.stringify([v.Name, v.CreatedAt, v.Driver]);
         },
         probe: async (c, image, user, destination) => {
@@ -228,7 +249,7 @@ export function dockerEngine(runner, signal, env) {
                     s.gid !== c.gid ||
                     (s.mode & 0o077) !== 0 ||
                     (await readFile(join(probe, "container"), "utf8")) !== "slopify ownership probe")
-                    throw new Error("Docker cannot create private files as this host user; ownership mapping is unsupported.");
+                    throw new Error("Docker can't create files in your project folder as your user, so the files would end up with the wrong owner. Use a standard Docker Engine or rootless Docker setup, or run Slopify without Docker: npx @gentbajko/slopify");
                 await writeFile(join(probe, "container"), "host can write", { flag: "a" });
             }
             finally {
@@ -378,7 +399,7 @@ export function dockerEngine(runner, signal, env) {
                 }
                 await delay(Math.min(250, Math.max(0, deadline - Date.now())), undefined, { signal });
             }
-            throw new Error("Replacement did not become healthy within 120 seconds.");
+            throw new Error(`The new Slopify container did not start up within 2 minutes. See why with: docker logs ${id}`);
         },
     };
 }

package/dist/edge/docker-projects/install.js

@@ -17,10 +17,10 @@ export async function installProjects(c, e, recovery) {
     const currentVolume = await e.volume(c.volume);
     if ((receipt && receipt.volumeIdentity !== currentVolume) ||
         (previousJournal?.volumeIdentity && previousJournal.volumeIdentity !== currentVolume))
-        throw new Error("Remembered data volume is missing or was replaced; restore the original volume before retrying.");
+        throw new Error(`Remembered data volume ${c.volume} is missing or was replaced since Slopify was installed. Restore the original volume (see docker volume ls) and run the launcher again. Nothing was changed.`);
     if ((receipt && receipt.daemon !== context.daemon) ||
         (previousJournal && previousJournal.daemon !== context.daemon))
-        throw new Error("Docker daemon differs from saved installation; select the original daemon.");
+        throw new Error("This is not the Docker that Slopify was installed with (a different Docker context or DOCKER_HOST is active). Switch back to the original one (docker context use <name>, or unset DOCKER_HOST) and try again.");
     await assertVolumeClaims(c, e, context.daemon, currentVolume, await e.inspect(c.name));
     if (previousJournal && previousJournal.phase !== "rolled-back")
         previousJournal = await recoverInstallation(c, previousJournal, receipt, recovery());
@@ -42,7 +42,7 @@ export async function installProjects(c, e, recovery) {
             continue;
         const other = await readState(join(c.root, name, "receipt.json"), receiptSchema, c.uid);
         if (other?.daemon === context.daemon && other.volume === c.volume)
-            throw new Error(`Named volume belongs to installation ${other.name}; select a separate volume.`);
+            throw new Error(`The Docker volume ${c.volume} already belongs to another Slopify installation (${other.name}). Give this one its own volume with SLOPIFY_DOCKER_VOLUME=<name> and try again.`);
     }
     let reuse = null;
     if (previousJournal?.phase === "rolled-back" &&
@@ -66,7 +66,7 @@ export async function installProjects(c, e, recovery) {
     const image = await e.image(c.image);
     const expectedVersion = await e.version(image);
     if (expectedVersion !== readVersion())
-        throw new Error("Docker image and installed launcher versions differ. Refresh the default release image or select the matching custom image before retrying; the existing container is unchanged.");
+        throw new Error(`The Docker image is Slopify ${expectedVersion} but this launcher is ${readVersion()}. Run the latest of both (npx @gentbajko/slopify@latest --docker), or if you set SLOPIFY_DOCKER_IMAGE, point it at version ${readVersion()}. Your existing container was not changed.`);
     const signature = createHash("sha256")
         .update(JSON.stringify([image, c.volume, c.port, c.bridge, projects, context.user]))
         .digest("hex");
@@ -228,19 +228,19 @@ export async function installProjects(c, e, recovery) {
         await save({ phase: "committed" });
         const ready = await e.inspect(candidate);
         if (!ready?.port)
-            throw new Error("Committed container has no localhost port; rerun the launcher.");
+            throw new Error("Slopify started but Docker did not report which port it is on. Run the same command again to finish.");
         return { url: `http://${ready.port}`, projects, recovery: j.backup };
     }
     catch (cause) {
         const current = await readState(receiptPath, receiptSchema, c.uid);
         if (current?.transaction === j.id)
-            throw new Error(`Installation committed at ${projects}; rerun the launcher to finish activation. Recovery volume: ${j.backup}`, { cause });
+            throw new Error(`Slopify was installed (project files at ${projects}) but the last step did not finish. Run the same command again to complete it. Backup volume: ${j.backup}`, { cause });
         try {
             await recoverInstallation(c, j, current, recovery());
         }
         catch (failure) {
-            throw new Error(`Recovery incomplete. Leave container/data stopped; recovery volume ${j.backup}, journal ${journalPath}, project folder ${projects}. ${failure instanceof Error ? failure.message : "Recovery operation failed."}`, { cause });
+            throw new Error(`Recovery incomplete: the install failed and Slopify could not fully undo it. Leave the Slopify container stopped and don't delete anything: backup volume ${j.backup}, progress file ${journalPath}, project folder ${projects}. Fix the problem below, then run the same command again. ${failure instanceof Error ? failure.message : "The undo step failed."}`, { cause });
         }
-        throw new Error(`Previous installation restored${old?.running ? " and restarted" : " without starting it"}. Recovery: ${j.backup}; project copy: ${projects}. ${cause instanceof Error ? cause.message : "Installation failed."}`, { cause });
+        throw new Error(`Install failed. Previous installation restored${old?.running ? " and restarted" : " (not started)"}, so nothing was lost. Backup volume: ${j.backup}; project copy: ${projects}. Reason: ${cause instanceof Error ? cause.message : "Installation failed."}`, { cause });
     }
 }

package/dist/edge/docker-projects/state.js

@@ -112,7 +112,7 @@ export function dockerConfig(env, home, cwd, uid, gid) {
     const projectsOverride = raw === null ? null : resolve(cwd, raw.startsWith("~/") ? join(home, raw.slice(2)) : raw);
     const portText = env.SLOPIFY_DOCKER_HOST_PORT || "6969";
     if (!/^\d{1,5}$/.test(portText) || Number(portText) > 65535)
-        throw new Error("Docker host port must be from 0 to 65535.");
+        throw new Error(`Invalid port ${JSON.stringify(portText)}: use a whole number between 1 and 65535, for example --port 7070.`);
     return {
         home,
         uid,
@@ -144,11 +144,11 @@ export async function privateDirectory(path, uid) {
         if (!s.isDirectory() ||
             s.isSymbolicLink() ||
             ((s.mode & 0o022) !== 0 && (s.mode & 0o1000) === 0))
-            throw new Error("Unsafe private state ancestor.");
+            throw new Error(`${current} is not a normal folder, or other users can write to it, so Slopify won't keep its Docker settings under it. Fix its permissions (chmod go-w ${current}) or set XDG_DATA_HOME to another folder, then try again.`);
     }
     const s = await lstat(path);
     if (s.uid !== uid || (s.mode & 0o077) !== 0)
-        throw new Error("Installation state must be private and owned by the installing user.");
+        throw new Error(`${path} must belong to you and be private. Fix it with chmod 700 ${path} (and chown it to your user if needed), then try again.`);
 }
 export async function readState(path, schema, uid) {
     const s = await lstat(path).catch((error) => {
@@ -186,7 +186,7 @@ export async function selectProjects(c, receipt, old, retry = null) {
             throw new Error("Receipt selects a different installation or volume.");
         await safePath(receipt.projects, c.home, c.root, false);
         await assertIdentity(receipt.projects, receipt.directoryIdentity).catch((cause) => {
-            throw new Error(`Remembered project folder is missing or replaced: ${receipt.projects}`, {
+            throw new Error(`Remembered project folder ${receipt.projects} is missing or was replaced. Put the original folder back where it was and run the launcher again.`, {
                 cause,
             });
         });
@@ -202,7 +202,7 @@ export async function selectProjects(c, receipt, old, retry = null) {
     await safePath(chosen, c.home, c.root, true);
     const source = receipt?.projects ?? bind?.source;
     if (source && source !== chosen && (contains(source, chosen) || contains(chosen, source)))
-        throw new Error("Source and destination project folders cannot contain each other.");
+        throw new Error(`The new project folder ${chosen} and the current one ${source} are inside each other. Choose a separate folder with --projects-dir <folder>.`);
     if (chosen !== source) {
         const entries = await readdir(chosen).catch((error) => {
             if (isMissing(error))
@@ -211,7 +211,7 @@ export async function selectProjects(c, receipt, old, retry = null) {
         });
         if (entries.length > 0) {
             if (retry?.destination !== chosen || !retry.publishedIdentity || !retry.sourceDigest)
-                throw new Error(`Unrelated populated destination: ${chosen}`);
+                throw new Error(`The project folder ${chosen} already has files in it that Slopify didn't put there. Choose an empty or new folder with --projects-dir <folder>, or move those files away, then try again.`);
             await assertIdentity(chosen, retry.publishedIdentity);
             if ((await treeDigest(chosen)).hash !== retry.sourceDigest.hash)
                 throw new Error(`Published retry destination changed: ${chosen}`);

package/dist/edge/docker-projects/tree.js

@@ -19,7 +19,7 @@ export function contains(root, path) {
 }
 export async function safePath(path, home, stateRoot, createParents) {
     if (!isAbsolute(path) || resolve(path) !== path || /[\p{Cc},]/u.test(path))
-        throw new Error("Project directory must be a normal absolute path without commas/control characters.");
+        throw new Error(`The project folder ${JSON.stringify(path)} can't be used: give a full path without commas, for example --projects-dir ~/Slopify/Projects.`);
     const forbidden = [
         "/",
         "/home",
@@ -36,7 +36,7 @@ export async function safePath(path, home, stateRoot, createParents) {
         contains(stateRoot, path) ||
         contains(path, stateRoot) ||
         ["/proc", "/sys", "/dev", "/etc", "/usr", "/bin", "/sbin", "/lib", "/var/lib/docker"].some((p) => contains(p, path)))
-        throw new Error("Unsafe broad or private project directory.");
+        throw new Error(`${path} can't be the project folder because it is a system or shared folder (or holds Slopify's own settings). Choose a dedicated folder, for example --projects-dir ~/Slopify/Projects.`);
     const parts = path.split(sep).filter(Boolean);
     let current = sep;
     for (const [i, part] of parts.entries()) {
@@ -53,11 +53,11 @@ export async function safePath(path, home, stateRoot, createParents) {
         if (s === undefined)
             continue;
         if (!s.isDirectory() || s.isSymbolicLink())
-            throw new Error(`Unsafe path component: ${current}`);
+            throw new Error(`${current} is a file or a link, not a folder, so it can't be part of the project folder path. Choose another folder with --projects-dir <folder>.`);
         if (i === parts.length - 1 && (s.uid !== process.getuid?.() || (s.mode & 0o022) !== 0))
-            throw new Error("Project directory must belong to the installing user and must not be publicly writable.");
+            throw new Error(`The project folder ${path} must belong to you and must not be writable by other users. Fix it (chmod go-w ${path}) or choose another folder with --projects-dir <folder>.`);
         if (i < parts.length - 1 && (s.mode & 0o022) !== 0 && (s.mode & 0o1000) === 0)
-            throw new Error(`Writable project ancestor: ${current}`);
+            throw new Error(`Other users can write to ${current}, which contains the project folder. Choose a project folder inside your home folder with --projects-dir <folder>, or fix it with chmod go-w ${current}.`);
     }
 }
 export function isMissing(error) {
@@ -137,7 +137,7 @@ export async function assertWritableTree(root, uid) {
         (s.isFile() && s.nlink !== 1) ||
         s.uid !== uid ||
         (s.mode & (s.isDirectory() ? 0o700 : 0o600)) !== (s.isDirectory() ? 0o700 : 0o600))
-        throw new Error(`Existing project permissions are incompatible with this host user: ${root}`);
+        throw new Error(`${root} in your project files doesn't have permissions your user can fully use. Make it yours and writable (chown -R $USER ${root}; chmod -R u+rwX ${root}), then try again.`);
     if (s.isDirectory())
         for (const name of await readdir(root))
             await assertWritableTree(join(root, name), uid);

package/dist/edge/docker.js

@@ -5,13 +5,13 @@ import { z } from "zod";
 import { installHostPackage } from "../host-cli/install.js";
 import { ensureBridgeToken, hasCode, prepareHostPaths } from "../host-cli/paths.js";
 import { ensureHostService, privateRead, privateWrite } from "../host-cli/service.js";
-import { resolveHostCommand } from "../host-cli/status.js";
+import { hostCommandName, resolveHostCommand } from "../host-cli/status.js";
 import { hostCliProtocol, hostLlmIds } from "../kernel/ports/host-cli.js";
 export function assertManagedDockerHost(platform, uid, gid) {
     if (platform !== "linux")
-        throw new Error("The managed Docker launcher requires Linux. Native Slopify and plain API-only Docker remain available on other hosts.");
+        throw new Error("The --docker launcher only works on Linux. On this system, run Slopify without Docker (npx @gentbajko/slopify), or start the Slopify Docker image yourself with docker run.");
     if (uid === undefined || gid === undefined || uid === 0)
-        throw new Error("Run the managed Docker launcher as your logged-in user, not with sudo; grant that account access to Docker.");
+        throw new Error("Don't run the --docker launcher with sudo or as root. Run it as your normal user, and if Docker then says permission denied, give your user access: sudo usermod -aG docker $USER, then log out and back in.");
 }
 export async function prepareDockerHostCli(options) {
     if (options.disabled)
@@ -24,16 +24,16 @@ export async function prepareDockerHostCli(options) {
         }
         catch (error) {
             if (!hasCode(error, "ENOENT"))
-                throw new Error("Host CLI detection failed. No container was changed.");
+                throw new Error(`Could not check whether ${hostCommandName(id)} is installed on this machine (${error instanceof Error ? error.message : String(error)}). Nothing was changed. Fix the problem, or start with --host-cli=off to use API keys only.`);
         }
     }
     if (!installed)
         return {};
     if (process.platform !== "linux")
-        throw new Error("Managed host CLI setup requires Linux/systemd. Use --host-cli=off for API-only Docker.");
+        throw new Error("Using this machine's AI CLIs from Docker needs Linux with systemd. Start with --host-cli=off to use API keys only.");
     const uid = process.getuid?.();
     if (uid === undefined || uid === 0)
-        throw new Error("Run the Docker launcher as your logged-in user, not root; or use --host-cli=off.");
+        throw new Error("Don't run the --docker launcher with sudo or as root; run it as your normal user. Or start with --host-cli=off to use API keys only.");
     const receiptPath = join(options.root, "consent.json");
     const existing = await privateRead(receiptPath, uid);
     const receipt = z.object({ version: z.literal(1), automaticStartup: z.literal(true) }).strict();
@@ -43,15 +43,15 @@ export async function prepareDockerHostCli(options) {
             approved ||= receipt.safeParse(JSON.parse(existing)).success;
         }
         catch {
-            throw new Error("Invalid host helper consent receipt.");
+            throw new Error(`The saved answer to the host CLI question (${receiptPath}) is damaged. Delete that file and run the launcher again to be asked again.`);
         }
     }
     if (!approved) {
         if (!options.interactive)
-            throw new Error("Host CLI setup needs confirmation. Use --accept-host-cli to approve, or --host-cli=off for API-only Docker.");
+            throw new Error("Slopify needs your OK to use the Claude Code, Codex or Gemini CLI installed on this machine, but can't ask because this isn't an interactive terminal. Rerun with --accept-host-cli to allow it, or with --host-cli=off to use API keys only.");
         approved = await options.prompt("Allow Slopify to run your host Claude Code, Codex and Gemini CLIs using their existing logins? This installs a private helper and enables automatic startup. User lingering keeps your user services running after logout and at boot. Credentials stay on the host. [y/N] ");
         if (!approved)
-            throw new Error("Host CLI setup declined. The container is unchanged. Use --host-cli=off for API-only Docker.");
+            throw new Error("You declined, so Slopify did not set up your host AI CLIs and nothing was changed. Run the launcher again and answer y to allow it, or add --host-cli=off to start with API keys only.");
     }
     const inspect = () => options.runner.exec("docker", [
         "image",
@@ -64,14 +64,14 @@ export async function prepareDockerHostCli(options) {
     if (image.code !== 0 || image.stdout.trim() !== String(hostCliProtocol)) {
         const pulled = await options.runner.exec("docker", ["pull", options.image], options.signal);
         if (pulled.code !== 0)
-            throw new Error("Could not pull a compatible Docker image. No helper or container was changed.");
+            throw new Error(`Could not download the Slopify Docker image ${options.image}. Check your internet connection and that Docker is running (docker info), then try again. Nothing was changed.`);
         image = await inspect();
         if (image.code !== 0 || image.stdout.trim() !== String(hostCliProtocol))
-            throw new Error("This Docker image does not support the host helper. Update the image before retrying.");
+            throw new Error(`The Docker image ${options.image} is too old to use the AI CLIs on this machine. Use the latest image (unset SLOPIFY_DOCKER_IMAGE, or point it to a current release) and try again, or start with --host-cli=off.`);
     }
     const supported = await options.runner.exec("systemctl", ["--user", "list-units", "--no-legend", "--no-pager", "slopify-cli-bridge.service"], options.signal);
     if (supported.code !== 0)
-        throw new Error("The systemd user service is unavailable. Use a normal Slopify install or --host-cli=off for API-only Docker.");
+        throw new Error("Using this machine's AI CLIs from Docker needs systemd user services (systemctl --user), which aren't available here. Start with --host-cli=off to use API keys only, or run Slopify without Docker: npx @gentbajko/slopify.");
     const paths = await prepareHostPaths(options.root);
     const lock = join(paths.root, "setup.lock");
     const deadline = Date.now() + 30_000;
@@ -84,7 +84,7 @@ export async function prepareDockerHostCli(options) {
             if (!hasCode(error, "EEXIST"))
                 throw error;
             if (Date.now() >= deadline)
-                throw new Error("Another host helper setup holds setup.lock. Wait for it to finish; the container is unchanged.");
+                throw new Error(`Another Slopify launcher is setting up the host CLI helper right now. Wait for it to finish and try again. If no other launcher is running, delete the folder ${lock} and retry.`);
             await delay(100, undefined, { signal: options.signal });
         }
     }

package/dist/edge/http/actions.js

@@ -91,15 +91,15 @@ export function actionRoutes(deps) {
             "rebuild-required": 409,
         };
         const messages = {
-            "no-project": "No project has that id.",
-            running: "Pause the run and wait for its active calls to stop before changing providers.",
-            "not-editable": "Providers can be changed only while a project is paused or failed.",
-            "invalid-providers": "The provider choices need attention.",
-            "catalog-unavailable": "The provider model catalog could not be loaded. Try again.",
-            "revision-required": "Reload the project before using this control. A current revision and request ID are required.",
-            conflict: "The project changed. Reload it before using this control.",
-            "idempotency-conflict": "This request ID has already been used for a different action.",
-            "rebuild-required": "Review the affected outputs and cost before rebuilding this revision.",
+            "no-project": "This project no longer exists. Go back to Projects to pick another.",
+            running: "This project is still running. Pause it and wait for the current step to stop before changing providers.",
+            "not-editable": "Providers can be changed only while the project is paused or has failed. Pause it first, then try again.",
+            "invalid-providers": "Some provider choices are not valid. Fix the highlighted fields and try again.",
+            "catalog-unavailable": "Slopify could not load the list of available models. Wait a moment and try again; if it keeps failing, check Settings → Models.",
+            "revision-required": "This page is out of date. Reload the page, then try again.",
+            conflict: "This project changed since the page loaded. Reload the page to see the latest, then try again.",
+            "idempotency-conflict": "This action was already sent with different details. Reload the page, then try again.",
+            "rebuild-required": "This change needs some outputs to be made again. In the Edit tab, use Rebuild affected outputs to see what will be regenerated and what it costs.",
         };
         return problem(c, {
             status: codes[result.reason],
@@ -117,7 +117,7 @@ export function actionRoutes(deps) {
             return problem(c, {
                 status: 503,
                 title: titleOf(503),
-                detail: "Recovery is unavailable. Try again after restart.",
+                detail: "Resume and retry are not ready yet because Slopify is still starting. Wait a moment, reload the page and try again.",
             });
         const result = recoveryResultSchema.parse(await recoverProject(deps.rebuild, id, { ...input, action }));
         if (result.ok)
@@ -128,26 +128,28 @@ export function actionRoutes(deps) {
                 ? 400
                 : 409;
         const messages = {
-            "no-project": "This project no longer exists.",
-            "no-revision": "This revision no longer exists. Reload the project.",
-            conflict: "The saved project changed. Reload it and try Resume.",
-            "idempotency-conflict": "This request ID belongs to another action. Reload the project.",
-            "invalid-edit": "This section needs attention in Edit project before rerunning.",
-            "stale-preview": "The required work changed. Try Resume to check it again.",
-            "invalid-selection": "This section has no generated work to rerun. Use Edit project to change its source.",
-            "review-required": "Changed supplied content or manual captions need Edit project or optional Advanced rebuild review.",
-            "cost-ack-required": "Use optional Advanced rebuild review for this request.",
-            readiness: "Check the provider, model, voice or source files, then try Resume.",
-            running: "Wait for this section to finish, or Pause the project before rerunning it.",
-            "accepted-job": "This section cannot be rerun yet.",
-            "control-changed": "A newer control action took precedence. Check the project before using Resume.",
+            "no-project": "This project no longer exists. Go back to Projects to pick another.",
+            "no-revision": "The project's saved settings changed since the page loaded. Reload the page, then try again.",
+            conflict: "This project changed since the page loaded. Reload the page to see the latest, then use Resume again.",
+            "idempotency-conflict": "This action was already sent with different details. Reload the page, then try again.",
+            "invalid-edit": "This section has settings that need fixing first. Open the Edit tab, choose Edit project and correct this section, then try again.",
+            "stale-preview": "What needs to be made changed since the page loaded. Reload the page, then use Resume again.",
+            "invalid-selection": "This section has nothing generated to re-run because its content was supplied by you. To change it, open the Edit tab and choose Edit project.",
+            "review-required": "Content you supplied or captions you edited by hand would be replaced. Change them in the Edit tab with Edit project, or use Rebuild affected outputs to confirm the replacement.",
+            "cost-ack-required": "This re-run needs you to review its cost first. In the Edit tab, use Rebuild affected outputs.",
+            readiness: "Slopify cannot run this yet. Check the provider, model, voice and any files you supplied, then use Resume.",
+            running: "This section is still running. Wait for it to finish, or Pause the project, before re-running it.",
+            "accepted-job": "This section has a finished provider job that Slopify has not collected yet.",
+            "control-changed": "Another action on this project (such as Pause or Cancel) happened at the same time. Reload the page to see its current state, then try again.",
         };
         const detail = [
             messages[result.reason],
             ...(result.fields ?? []).map((row) => row.message),
             ...(result.intentRevisionId === undefined
                 ? []
-                : ["The rerun revision was saved. Use Resume to continue it; do not rerun again."]),
+                : [
+                    "Your re-run request was saved. Use Resume to continue it instead of re-running again.",
+                ]),
         ].join(" ");
         return problem(c, {
             status,
@@ -218,7 +220,7 @@ function revisionRequired(c) {
     return problem(c, {
         status: 409,
         title: titleOf(409),
-        detail: "Open Edit project to save changes, then review the affected rebuild.",
+        detail: "This change is now made from the Edit tab. Choose Edit project, save your change, then use Rebuild affected outputs.",
         extensions: { reason: "revision-required" },
     });
 }