@gentbajko/slopify 2.5.0 → 3.0.1

package/dist/slices/youtube/chapters.js

@@ -0,0 +1,126 @@
+// Chapters as YouTube takes them. YouTube turns the timestamps of a description into chapters
+// only when the first is at 0:00, there are at least three, each lasts at least ten seconds and
+// they go up in time; otherwise it ignores the whole list. The step's answer is checked against
+// those rules when it is written (`answer.ts`), but a hand edit, or a video cut again to another
+// length after the description was written, can break them. So the chapters are fitted when the
+// description is shown or copied, never stored: the generated file, the user's edit and every
+// fingerprint stay as they were, and the page says what was changed. Pure and browser-safe.
+import { minChapterSeconds, minChapters } from "./model.js";
+import { parseTimestamp, youtubeTimestamp } from "./timestamps.js";
+// "M:SS Title": a time YouTube reads, then a title.
+function chapterLine(line) {
+    const trimmed = line.trim();
+    const match = /^(\S+)\s+(.+)$/u.exec(trimmed);
+    if (match === null)
+        return undefined;
+    const start = parseTimestamp(match[1] ?? "");
+    const title = (match[2] ?? "").trim();
+    return start === undefined || title === "" ? undefined : { start, title };
+}
+// Fits one chapters field (one "M:SS Title" per line) to YouTube's rules, in this order:
+// 1. chapters out of time order are put in order, and of two at the same time the one listed
+//    first stays;
+// 2. with the video's length known, a chapter starting at or after its end is removed;
+// 3. the first chapter moves to 0:00;
+// 4. the first chapter shorter than ten seconds is merged into its neighbour, again until none
+//    is: into the one before it (whose title stays), or, for the first chapter, into the one
+//    after it, which then starts at 0:00. The last chapter's length is only known with the
+//    video's length;
+// 5. with fewer than three chapters left, the list is dropped, since YouTube would ignore it.
+// Other lines in the field (a note the user typed) stay where they were. When anything changed,
+// the chapter lines are rewritten in YouTube's M:SS form.
+export function fitChapters(text, durationSeconds) {
+    const lines = text.replace(/\r\n?/gu, "\n").split("\n");
+    const slots = [];
+    const found = [];
+    for (const [index, line] of lines.entries()) {
+        const chapter = chapterLine(line);
+        if (chapter === undefined)
+            continue;
+        slots.push(index);
+        found.push(chapter);
+    }
+    if (found.length === 0)
+        return { text, adjustments: [] };
+    const adjustments = [];
+    const quoted = (chapter) => `"${chapter.title}"`;
+    let chapters = [...found].sort((a, b) => a.start - b.start);
+    if (chapters.some((chapter, index) => chapter !== found[index]))
+        adjustments.push("put the chapters in time order");
+    // Two chapters at the same time: the one listed first keeps it.
+    const distinct = [];
+    for (const chapter of chapters) {
+        const previous = distinct.at(-1);
+        if (previous !== undefined && previous.start === chapter.start)
+            adjustments.push(`merged ${quoted(chapter)} (0 s) into ${quoted(previous)}`);
+        else
+            distinct.push(chapter);
+    }
+    chapters = distinct;
+    const end = durationSeconds !== undefined && Number.isFinite(durationSeconds) && durationSeconds > 0
+        ? durationSeconds
+        : undefined;
+    if (end !== undefined) {
+        const after = chapters.filter((chapter, index) => index > 0 && chapter.start >= end);
+        for (const chapter of after)
+            adjustments.push(`removed ${quoted(chapter)} (${youtubeTimestamp(chapter.start)}), which starts after the video ends at ${youtubeTimestamp(end)}`);
+        chapters = chapters.filter((chapter) => !after.includes(chapter));
+    }
+    const first = chapters[0];
+    if (first !== undefined && first.start !== 0) {
+        adjustments.push(`moved the first, ${quoted(first)}, from ${youtubeTimestamp(first.start)} to 0:00`);
+        chapters = [{ start: 0, title: first.title }, ...chapters.slice(1)];
+    }
+    const length = (index) => {
+        const next = chapters[index + 1];
+        const start = chapters[index]?.start ?? 0;
+        if (next !== undefined)
+            return next.start - start;
+        return end === undefined ? Number.POSITIVE_INFINITY : end - start;
+    };
+    const seconds = (value) => `${String(Math.max(0, Math.floor(value)))} s`;
+    while (chapters.length > 1) {
+        const short = chapters.findIndex((_, index) => length(index) < minChapterSeconds);
+        if (short === -1)
+            break;
+        const chapter = chapters[short];
+        if (chapter === undefined)
+            break;
+        const lasted = seconds(length(short));
+        if (short === 0) {
+            const next = chapters[1];
+            if (next === undefined)
+                break;
+            adjustments.push(`merged ${quoted(chapter)} (${lasted}) into ${quoted(next)}`);
+            chapters = [{ start: 0, title: next.title }, ...chapters.slice(2)];
+        }
+        else {
+            const previous = chapters[short - 1];
+            if (previous === undefined)
+                break;
+            adjustments.push(`merged ${quoted(chapter)} (${lasted}) into ${quoted(previous)}`);
+            chapters = chapters.filter((_, index) => index !== short);
+        }
+    }
+    if (chapters.length < minChapters) {
+        adjustments.push(`left the chapter list out, since YouTube needs at least ${String(minChapters)} chapters of ${String(minChapterSeconds)} s or more and only ${String(chapters.length)} ${chapters.length === 1 ? "is" : "are"} left`);
+        chapters = [];
+    }
+    if (adjustments.length === 0)
+        return { text, adjustments };
+    // The chapters go back into the first slots in order; the slots left over are removed.
+    const bySlot = new Map(slots.map((slot, index) => [slot, chapters[index]]));
+    const rewritten = lines.flatMap((line, index) => {
+        if (!bySlot.has(index))
+            return [line];
+        const chapter = bySlot.get(index);
+        return chapter === undefined ? [] : [`${youtubeTimestamp(chapter.start)} ${chapter.title}`];
+    });
+    return { text: rewritten.join("\n").trim(), adjustments };
+}
+// The sentence shown beside the description; undefined when nothing was changed.
+export function chapterNotice(adjustments) {
+    return adjustments.length === 0
+        ? undefined
+        : `Chapters adjusted for YouTube: ${adjustments.join("; ")}.`;
+}

package/dist/slices/youtube/edits-repo.js

@@ -0,0 +1,84 @@
+// Where the hand edits and the channel links are kept: the edits per project in
+// `youtube_description_edits`, each channel's links in its brand kit, and the older Settings list
+// of links (read as the default channel's until its Brand tab saves its own) as one `settings` row.
+import { z } from "zod";
+import { defaultChannelId } from "../channels/model.js";
+import { channelById, projectChannelId } from "../channels/repo.js";
+import { readSetting, writeSetting } from "../settings/repo.js";
+import { chapterNotice, fitChapters } from "./chapters.js";
+import { composeDescription, descriptionFields, resolveFields, shownFields, splitDescription, } from "./edits.js";
+import { fillPlaceholders, mergeLinks } from "./placeholders.js";
+export const channelLinksKey = "channel_links";
+const fieldEdit = z.object({ base: z.string(), text: z.string() }).strict();
+const editsSchema = z
+    .object(Object.fromEntries(descriptionFields.map((field) => [field, fieldEdit.optional()])))
+    .strict();
+const linksSchema = z.array(z.object({ name: z.string(), url: z.string() }).strict());
+const none = { fields: {}, links: [] };
+export function readDescriptionEdits(db, projectId) {
+    const row = db
+        .prepare("SELECT fields_json,links_json FROM youtube_description_edits WHERE project_id=?")
+        .get(projectId);
+    if (row === undefined)
+        return none;
+    const parsed = z.object({ fields_json: z.string(), links_json: z.string() }).parse(row);
+    return {
+        fields: editsSchema.parse(JSON.parse(parsed.fields_json)),
+        links: linksSchema.parse(JSON.parse(parsed.links_json)),
+    };
+}
+export function writeDescriptionEdits(db, projectId, edits, updatedAt) {
+    if (Object.keys(edits.fields).length === 0 && edits.links.length === 0) {
+        db.prepare("DELETE FROM youtube_description_edits WHERE project_id=?").run(projectId);
+        return;
+    }
+    db.prepare(`INSERT INTO youtube_description_edits (project_id,fields_json,links_json,updated_at) VALUES (?,?,?,?)
+     ON CONFLICT(project_id) DO UPDATE SET fields_json=excluded.fields_json,links_json=excluded.links_json,updated_at=excluded.updated_at`).run(projectId, JSON.stringify(edits.fields), JSON.stringify(edits.links), updatedAt);
+}
+export function readChannelLinks(db) {
+    const value = readSetting(db, channelLinksKey);
+    if (value === undefined)
+        return [];
+    // A hand-edited row that no longer parses reads as no links rather than breaking the page;
+    // saving the list in Settings writes a good one again.
+    try {
+        const parsed = linksSchema.safeParse(JSON.parse(value));
+        return parsed.success ? parsed.data : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function writeChannelLinks(db, links) {
+    writeSetting(db, channelLinksKey, JSON.stringify(links.map((link) => ({ name: link.name.trim(), url: link.url.trim() }))));
+}
+// A channel's links: the ones its Brand tab saved. The default channel, until its Brand tab
+// saves a list of its own (even an empty one), reads the older Settings list, so links saved
+// before channels had their own keep filling. A channel that is gone has none.
+export function readChannelLinksFor(db, channelId) {
+    const channel = channelById(db, channelId);
+    if (channel === undefined)
+        return [];
+    if (channel.brand.links !== undefined)
+        return channel.brand.links;
+    return channel.id === defaultChannelId ? readChannelLinks(db) : [];
+}
+// The description and tags as the project page shows and copies them: the user's edits over
+// the generated text, the chapters fitted to YouTube's rules (`chapters.ts`; the last one's
+// length only checked when the video's length is given), placeholders filled from the
+// project's and its channel's links (one with no link stays as typed). For anything that hands
+// the description on, such as Prepare upload and the downloads. `chapterNotice` says what the
+// fitting changed.
+export function effectiveDescription(db, projectId, generated) {
+    const edits = readDescriptionEdits(db, projectId);
+    const shown = shownFields(resolveFields(splitDescription(generated.description, generated.tags), edits.fields));
+    const fitted = fitChapters(shown.chapters, generated.durationSeconds);
+    const notice = chapterNotice(fitted.adjustments);
+    const links = mergeLinks(readChannelLinksFor(db, projectChannelId(db, projectId)), edits.links);
+    return {
+        description: fillPlaceholders(composeDescription({ ...shown, chapters: fitted.text }), links)
+            .text,
+        tags: fillPlaceholders(shown.tags, links).text,
+        ...(notice === undefined ? {} : { chapterNotice: notice }),
+    };
+}

package/dist/slices/youtube/edits.js

@@ -0,0 +1,89 @@
+// Hand edits to the YouTube description. The project page lets the user edit the summary,
+// the chapters, the hashtags and the tags in place; each edit is saved with the generated
+// text it was made from (`base`), so when the description is written again the page can tell
+// a field the user changed from one they left alone. Browser-safe: the project page applies
+// these rules to what it shows, and the server only stores the edits.
+import { parseTimestamp } from "./timestamps.js";
+export const descriptionFields = ["summary", "chapters", "hashtags", "tags"];
+// Splits a written description back into its three parts. `assembleDescription` (answer.ts) lays it out as
+// the summary, a blank line, one chapter per line, a blank line and the hashtags; reading it
+// from the end keeps a summary with blank lines of its own whole.
+export function splitDescription(description, tags) {
+    const lines = description.replace(/\r\n?/gu, "\n").split("\n");
+    while (lines.length > 0 && lines.at(-1)?.trim() === "")
+        lines.pop();
+    let hashtags = "";
+    const last = lines.at(-1)?.trim() ?? "";
+    if (last !== "" && last.split(/\s+/u).every((word) => /^#[\p{L}\p{N}_]+$/u.test(word))) {
+        hashtags = last;
+        lines.pop();
+    }
+    while (lines.length > 0 && lines.at(-1)?.trim() === "")
+        lines.pop();
+    const chapters = [];
+    while (lines.length > 0 && isChapterLine(lines.at(-1) ?? "")) {
+        chapters.unshift((lines.pop() ?? "").trim());
+    }
+    return {
+        summary: lines.join("\n").trim(),
+        chapters: chapters.join("\n"),
+        hashtags,
+        tags: tags.trim(),
+    };
+}
+function isChapterLine(line) {
+    const [time = "", ...title] = line.trim().split(/\s+/u);
+    return parseTimestamp(time) !== undefined && title.length > 0;
+}
+// The description as YouTube takes it, from the fields as shown: the same layout
+// `assembleDescription` writes, leaving out a part the user emptied.
+export function composeDescription(fields) {
+    return [fields.summary.trim(), fields.chapters.trim(), fields.hashtags.trim()]
+        .filter((part) => part !== "")
+        .join("\n\n");
+}
+// The rules for one field:
+// - never edited: the generated text;
+// - edited, and the generated text is still the one the edit started from: the user's text;
+// - edited, and the generated text changed since: the user's text, with the new generated text
+//   pending for the user to take or dismiss - unless the two now agree, and then there is
+//   nothing to choose;
+// - not written yet: the user's text if there is one, otherwise nothing.
+export function resolveField(generated, edit) {
+    if (edit === undefined)
+        return { text: generated ?? "", edited: false };
+    if (generated === undefined || edit.base === generated)
+        return { text: edit.text, edited: true };
+    if (edit.text === generated)
+        return { text: generated, edited: false };
+    return { text: edit.text, edited: true, pending: generated };
+}
+export function resolveFields(generated, edits) {
+    const one = (field) => resolveField(generated?.[field], edits[field]);
+    return {
+        summary: one("summary"),
+        chapters: one("chapters"),
+        hashtags: one("hashtags"),
+        tags: one("tags"),
+    };
+}
+export function shownFields(resolved) {
+    return {
+        summary: resolved.summary.text,
+        chapters: resolved.chapters.text,
+        hashtags: resolved.hashtags.text,
+        tags: resolved.tags.text,
+    };
+}
+// Saving an edit: text equal to the generated text is no edit at all, so the field follows the
+// next regeneration again.
+export function withEdit(edits, field, text, generated) {
+    if (text === generated)
+        return withoutEdit(edits, field);
+    return { ...edits, [field]: { base: generated, text } };
+}
+// "Use it": the field follows the generated text again.
+export function withoutEdit(edits, field) {
+    const { [field]: _dropped, ...rest } = edits;
+    return rest;
+}

package/dist/slices/youtube/placeholders.js

@@ -0,0 +1,98 @@
+// Channel links and the placeholders that use them. A description (the generated one, the
+// user's edit, or what a Description prompt told the model to write) can hold `{{Patreon}}` or
+// `{{Previous video}}`; they are filled from the saved links when the description is shown or
+// copied, never when it is written, so changing a link changes every description at once.
+// A placeholder with no link of that name stays in the text as typed and is marked, never
+// silently dropped. Browser-safe.
+// The link YouTube descriptions most often point at, and the one that changes per project:
+// the project page offers it by name, and a project's own value wins over its channel's list.
+export const previousVideoLink = "Previous video";
+export const channelLinkNameMax = 60;
+export const channelLinkUrlMax = 2000;
+export const channelLinksMax = 50;
+const placeholder = /\{\{([^{}\n]{1,80})\}\}/gu;
+// Names match without regard to case or repeated spaces: `{{previous  video}}` is the
+// "Previous video" link.
+export function linkKey(name) {
+    return name.trim().replace(/\s+/gu, " ").toLowerCase();
+}
+// The project's own links first, so one of the same name replaces the Settings one.
+export function mergeLinks(settings, project) {
+    const seen = new Set();
+    const merged = [];
+    for (const link of [...project, ...settings]) {
+        const key = linkKey(link.name);
+        if (seen.has(key) || link.url.trim() === "")
+            continue;
+        seen.add(key);
+        merged.push(link);
+    }
+    return merged;
+}
+export function placeholderParts(text, links) {
+    const byName = new Map(links.map((link) => [linkKey(link.name), link.url]));
+    const parts = [];
+    let at = 0;
+    for (const match of text.matchAll(placeholder)) {
+        const index = match.index;
+        if (index > at)
+            parts.push({ kind: "text", text: text.slice(at, index) });
+        const name = (match[1] ?? "").trim();
+        parts.push({ kind: "placeholder", raw: match[0], name, url: byName.get(linkKey(name)) });
+        at = index + match[0].length;
+    }
+    if (at < text.length)
+        parts.push({ kind: "text", text: text.slice(at) });
+    return parts;
+}
+export function fillPlaceholders(text, links) {
+    const unknown = [];
+    const filled = placeholderParts(text, links)
+        .map((part) => {
+        if (part.kind === "text")
+            return part.text;
+        if (part.url !== undefined)
+            return part.url;
+        if (!unknown.some((name) => linkKey(name) === linkKey(part.name)))
+            unknown.push(part.name);
+        return part.raw;
+    })
+        .join("");
+    return { text: filled, unknown };
+}
+// Why a list of links cannot be saved, in the words Settings shows; undefined when it can.
+export function channelLinksProblem(links) {
+    if (links.length > channelLinksMax)
+        return `Keep at most ${String(channelLinksMax)} links. Remove some.`;
+    const seen = new Set();
+    for (const [index, link] of links.entries()) {
+        const row = `Link ${String(index + 1)}`;
+        const name = link.name.trim();
+        if (name === "")
+            return `${row} has no name. Give it one, such as Patreon.`;
+        if (name.length > channelLinkNameMax)
+            return `${row}'s name is over ${String(channelLinkNameMax)} characters. Shorten it.`;
+        if (/[{}]/u.test(name))
+            return `${row}'s name contains { or }. Use the name alone; the description writes it as {{${name.replace(/[{}]/gu, "")}}}.`;
+        if (seen.has(linkKey(name)))
+            return `Two links are named "${name}". Rename one, since {{${name}}} can only fill with one.`;
+        seen.add(linkKey(name));
+        const url = link.url.trim();
+        if (url.length > channelLinkUrlMax)
+            return `The "${name}" link is over ${String(channelLinkUrlMax)} characters. Use a shorter address.`;
+        if (url === "")
+            return `The "${name}" link has no address. Paste it, starting with https://.`;
+        if (!isWebAddress(url))
+            return `The "${name}" link is not a web address. Paste the full address, starting with https://.`;
+    }
+    return undefined;
+}
+function isWebAddress(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === "https:" || parsed.protocol === "http:";
+    }
+    catch {
+        return false;
+    }
+}

package/dist/slices/youtube/transcript.js

@@ -51,7 +51,9 @@ const sentenceLongestSeconds = 30;
 // The narration as numbered sentences, for the Shorts step: the model picks clips by
 // sentence number and Slopify cuts at the sentences' own word times, so a clip never starts
 // or ends mid-word. A sentence closes at its full stop, question or exclamation mark, at a
-// pause of 1.5 s (the gap between intro, body and outro), or after 30 s.
+// pause of 1.5 s (the gap between intro, body and outro), or after 30 s. On a multi-voice run
+// it also closes where one speaker's turn ends, so a clip always starts and ends on a turn's
+// sentence and never cuts a speaker off mid-line.
 export function transcriptSentences(words) {
     const sentences = [];
     let first = -1;
@@ -73,6 +75,7 @@ export function transcriptSentences(words) {
                 text,
                 firstWord: first,
                 lastWord: last,
+                ...(opening.speaker === undefined ? {} : { speaker: opening.speaker }),
             });
         first = -1;
     };
@@ -82,6 +85,7 @@ export function transcriptSentences(words) {
         if (opening !== undefined &&
             previous !== undefined &&
             (word.start - previous.end >= pauseSeconds ||
+                word.turn !== previous.turn ||
                 word.end - opening.start > sentenceLongestSeconds))
             flush(index - 1);
         if (first < 0)
@@ -93,9 +97,12 @@ export function transcriptSentences(words) {
     return sentences;
 }
 // One sentence per line, led by its number and its span in the video, which is what the
-// model picks from.
-export function sentencesText(sentences) {
+// model picks from; on a multi-voice run, with the speaker's name before the words.
+export function sentencesText(sentences, names) {
     return sentences
-        .map((sentence) => `[${String(sentence.number)}] (${youtubeTimestamp(sentence.start)}-${youtubeTimestamp(sentence.end)}) ${sentence.text}`)
+        .map((sentence) => {
+        const name = sentence.speaker === undefined ? undefined : names?.[sentence.speaker];
+        return `[${String(sentence.number)}] (${youtubeTimestamp(sentence.start)}-${youtubeTimestamp(sentence.end)}) ${name === undefined ? "" : `${name}: `}${sentence.text}`;
+    })
         .join("\n");
 }

package/dist/tutorials/AI-CLIs.md

@@ -0,0 +1,146 @@
+# AI CLIs
+
+Slopify can write the text with the Claude Code, Codex or Gemini command-line tools, and draw the images with Codex, using the sign-in you already have. You need no API key for those steps, and their calls count toward your plan's limits instead of costing per call.
+
+**Where to find it:** Settings → Providers → the **Text** list (Claude Code CLI, Codex CLI, Gemini CLI) and the **Images** list (Codex CLI).
+
+## What each tool does
+
+| Tool | Command | Used for | Signs in with | Calls at once |
+|---|---|---|---|---|
+| **Claude Code CLI** | `claude` | Text: research, script, article, titles, descriptions, reviews | Your Claude account | 3 |
+| **Codex CLI** | `codex` | Text | Your ChatGPT account | 3 |
+| **Gemini CLI** | `gemini` | Text | Your Google account | 3 |
+| **Codex CLI** (Images) | `codex` | Images and thumbnails | Your ChatGPT account (the same sign-in and path as Codex text) | 4 |
+
+Codex text and Codex images share one sign-in, one executable path and one plan allowance.
+
+Codex CLI must be version 0.149.1 or newer. An older Codex shows **Needs attention** and says to update it.
+
+## Set up a CLI
+
+1. Install the tool on the computer that runs Slopify, following the tool's own instructions.
+2. Sign in once in a terminal:
+   - Claude Code: `claude auth login`
+   - Codex: `codex login`
+   - Gemini: run `gemini` and follow its login steps.
+3. Open **Settings → Providers** (reload the page if it was already open).
+4. Pick the tool in the **Text** or **Images** list. Its row should say **Ready**, and its setup shows **Installed, version …** and the **Command** Slopify runs.
+5. Choose **Check all** to confirm it is signed in.
+
+On the very first launch, before any key is saved, Slopify looks for all three tools. If it finds any, it says so and picks one for text on new Play drafts, preferring Claude Code, then Codex, then Gemini, and Codex for images when found. The CLIs can't speak, but the narration needs no key either: without a voice key, the [System voice](Providers-and-Keys#the-system-voice) reads it with your computer's own speech. See [First-Launch-and-Welcome](First-Launch-and-Welcome).
+
+## Row states
+
+| State | Meaning |
+|---|---|
+| **Ready** | Found, new enough and not reporting a sign-in problem. |
+| **Needs attention** | Found, but something is wrong (for example an old Codex version). The detail says what. |
+| **Not found** | Not on PATH, or not at the saved path. |
+
+## Set the executable path
+
+Slopify finds each tool on PATH, the list of folders your terminal searches. Set a path when the tool is installed somewhere else, or you have more than one copy.
+
+1. Pick the tool in **Settings → Providers**.
+2. Choose **Change path**.
+3. In **Executable path**, type the absolute path to the program file, without quotes or arguments. Leave it blank to go back to finding it on PATH.
+4. Choose **Save path**. Slopify checks the tool answers before saving; a folder or a missing file is refused with the reason.
+5. Choose **Close path** to fold the field away.
+
+| Option | What it does | Default |
+|---|---|---|
+| **Executable path** | Where the tool is on this computer. | Blank (found on PATH) |
+
+## Check the sign-in
+
+**Check all** (Settings → Providers) asks each tool:
+
+- **Installed**: found, with its version.
+- **Signed in**: Slopify asks Claude Code and Codex directly. If one is signed out, the line tells you the command to run (`claude auth login` or `codex login`). For Gemini CLI, Slopify reads the sign-in from its own files in `~/.gemini`, without starting it: the method saved in `settings.json`, then a Google sign-in in `oauth_creds.json` or a `GEMINI_API_KEY`. When the files don't say, it asks you to run `gemini` in a terminal once to confirm.
+- **Chosen models**: every model your templates, schedules, drafts and unfinished projects pick is still offered by the tool.
+
+Each tool's row has **Check again**, to check that tool alone after you fix something.
+
+If a run fails because a tool's sign-in expired, the project offers **Copy sign-in command** and **Check again**: run the copied command in a terminal on the computer running the tool and sign in, then press **Check again**. Once the tool answers that it is signed in, the step runs again by itself. See [Recovery and Retries](Recovery-and-Retries#sign-a-cli-in-again).
+
+## Pick a model and thinking level
+
+A CLI's model list comes from the tool installed on your computer, not from the model catalogue. On Play:
+
+1. Pick the tool as the text provider (or Codex CLI for images).
+2. Pick a **Text model** from the list. The refresh button beside it (**Refresh models**) asks the tool for its current list; **Custom ID** lets you type a model the list does not show.
+3. If the model offers it, pick **Thinking** (text) or **Effort** (images). **Model default** leaves it to the tool. The levels come from the model: for example Low, Medium, High and Xhigh. Higher levels can write or draw more carefully, but take longer and use more of your plan.
+
+If a model is missing when a run reaches it, the run stops with "The chosen model is not available in the AI command-line tool on your computer." Update the tool, or pick another model in **Edit project** under Providers, then **Continue the run**. A thinking level the model does not support stops the same way.
+
+## Codex images
+
+Codex draws each image as its own job.
+
+- **Codex default** runs with the tool's own defaults: no model and no effort on the command line.
+- Any other model is one of Codex's own models (the same list the Codex text provider shows), run with the **Effort** you pick. With a chosen model or effort, or a reference picture to match, the agent may look at its work and redraw it.
+- Each image may take several minutes; the time limit for one image is 30 minutes.
+- Up to 4 images are drawn at once.
+
+Codex images count toward your Codex plan. There is no API price for agent-drawn images, so the cost pages show them as $0 on your plan with no API figure.
+
+## Plan limits and waiting them out
+
+The CLIs bill your subscription, which gives a share of a 5-hour and a weekly allowance rather than a bill. Slopify shows what the tools report:
+
+- **Claude Code** reports its 5-hour and 7-day windows during each call.
+- **Codex** is asked before and after each call. It reports whole percents, so a short run can show "under 1%".
+- **Gemini** reports none.
+
+You see these on a project's **Run cost** tab, in the run's **Cost so far** panel, and on Home under **This week**. See [Costs-and-Run-Cost](Costs-and-Run-Cost).
+
+When a tool says its allowance is used up, the run does not fail:
+
+1. Slopify stores the reset time the tool gave (per tool, not per project).
+2. Every call to that tool, from any project, waits until 2 minutes after the reset. Without a stated time, it checks again every 30 minutes.
+3. The project's status reads **Waiting for limits**, with a line such as "Waiting for Codex limits (resets at 14:00)." The same words show on Home's Running now, the Projects row and the Calendar.
+4. When the reset passes, the run continues by itself.
+
+Other providers are not held up: a project whose narration uses a key carries on while its Codex images wait. The wait survives a restart; a project that was waiting when Slopify stopped resumes on the next start and waits again. A project you paused or cancelled meanwhile is left alone.
+
+Gemini's daily quota is handled the same way ("Slopify waits and tries again later by itself").
+
+## In Docker: the host helper
+
+A container cannot use the CLIs installed on your computer directly. On Linux, the Docker installer offers a small helper that runs the tools on your computer, outside the container, with the sign-ins they already have.
+
+1. Install and sign in to the CLIs on your computer first.
+2. Run the Docker installer (`npx @gentbajko/slopify@latest --docker`). If a CLI is found, it asks once whether to set up the helper. `--accept-host-cli` approves without asking; `--host-cli=off` skips it.
+3. In Settings → Providers the tools show **Managed on host**. Their path cannot be changed there.
+
+What to know:
+
+- The helper runs as you, as the user service `slopify-cli-bridge.service`, and talks to the container over a private socket. No network port is opened and no sign-in is copied into Docker.
+- After you install, update or remove a CLI, run the Docker installer again so Slopify sees the change.
+- Run cost and plan-limit shares work the same as without Docker. An older helper may not pass them through, and the cost page then says the share is not known.
+- With the helper off, Settings shows the CLIs as unavailable. API-key providers still work.
+
+Check or turn off the helper:
+
+```sh
+systemctl --user status slopify-cli-bridge.service
+systemctl --user disable --now slopify-cli-bridge.service
+```
+
+Turning it off leaves Docker, your API providers, your data and your host sign-ins as they are. See [Docker](Docker).
+
+## Tips
+
+- A CLI step on Play's estimate reads "$0 on your plan · ~$X via API": what the same tokens would cost with a key.
+- If your plan runs out often, split the work: keep text on a CLI and put images on a keyed provider, or the other way round.
+- Use **Check all** after updating a CLI; a newer tool can drop a model your template still names.
+
+## Related pages
+
+- [Providers-and-Keys](Providers-and-Keys)
+- [Models](Models)
+- [Costs-and-Run-Cost](Costs-and-Run-Cost)
+- [Docker](Docker)
+- [Recovery-and-Retries](Recovery-and-Retries)
+- [Troubleshooting](Troubleshooting)