@gentbajko/slopify 3.16.0 → 3.18.0

package/dist/slices/storage/consequences.js

@@ -0,0 +1,27 @@
+// What a storage action removes and what it costs later, in the words its confirm dialog
+// uses: shared by the web page (Settings → Backup & storage, a project's Free up space) and
+// the agent's tool, so both state the same count and size.
+// "512 B", "3.4 MB", "12 GB": binary units, one decimal under ten.
+export function fileSize(bytes) {
+    if (bytes < 1024)
+        return `${String(bytes)} B`;
+    const units = ["KB", "MB", "GB", "TB"];
+    let value = bytes;
+    let unit = units[0];
+    for (const candidate of units) {
+        value /= 1024;
+        unit = candidate;
+        if (value < 1024 || candidate === units.at(-1))
+            break;
+    }
+    return `${value >= 10 ? value.toFixed(0) : value.toFixed(1).replace(/\.0$/, "")} ${unit}`;
+}
+// What Delete old versions removes and what it costs later; without the numbers when they
+// can't be read. `scope` is whose History it empties: every project's, or one project's.
+export function oldVersionsConsequence(size, scope = "projects") {
+    const what = size === undefined
+        ? "the older versions"
+        : `${String(size.files)} file(s) of older versions and frees ${fileSize(size.bytes)}`;
+    const where = scope === "project" ? "this project's History folder" : "the projects' History folders";
+    return `This deletes ${what}: what is in ${where} (earlier renders, narration before a change). The current video, shorts, thumbnails and everything in Upload stay, and so does anything you uploaded or put there yourself. Going back to one of those older versions makes its files again, which takes time and uses provider credits.`;
+}

package/dist/slices/storage/portable.js

@@ -8,6 +8,7 @@ import { transact } from "../../kernel/db/tx.js";
 import { liveProject } from "../admission/repo.js";
 import { silenceGapSecondsMax } from "../admission/rules.js";
 import { detectSlots } from "../admission/substitute.js";
+import { agentConnectionKey } from "../agents/connection.js";
 import { fontMaxBytes } from "../fonts/model.js";
 import { readFontMetadata } from "../fonts/sfnt.js";
 import { lintEntry, lintPrompt } from "../library/lint.js";
@@ -373,9 +374,11 @@ function portableSettings(settings) {
         // So does the Studio extension's pairing: its token reads every project's upload pack.
         // Which "What's new" tour and which patch notes this install has closed are about this
         // install, not the data.
+        // When an agent last connected is this install's own fact.
         if (key === "tutorial.session" ||
             // Whether this install showed its first-run welcome belongs to this install.
             key === "first-run.done" ||
+            key === agentConnectionKey ||
             key === notificationUrlKey ||
             key === studioPairingKey ||
             // What waits to be filled in Studio belongs to this install's pairing.

package/dist/slices/storage/project-files.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { desiredPlaces } from "./arrange.js";
+import { assetOf } from "./asset-name.js";
+import { outputPath } from "./layout.js";
+import { outputsOf, projectTitle } from "./repo.js";
+// A project's files as its folder is arranged (`arrange.ts`): Upload (what is published),
+// Working (what it was made from) and History (older versions). The place is where the file
+// belongs even before the folder is arranged; `path` is where it is now and can move, so the
+// `/files` URL is the handle to keep.
+export const fileGroups = ["Upload", "Working", "History"];
+export function groupOf(place) {
+    const first = place.split("/", 1)[0];
+    return first === "Upload" || first === "History" ? first : "Working";
+}
+const recordRow = z.object({
+    path: z.string(),
+    revision_id: z.string(),
+    id: z.string(),
+    role: z.string().nullable(),
+});
+// The newest version record of each stored path, for its `/files/:id/revisions/...` URL.
+function revisionRecords(db, projectId) {
+    const records = new Map();
+    for (const row of db
+        .prepare(`SELECT a.path, o.revision_id, o.id, json_extract(o.descriptor,'$.role') AS role, o.created_at
+       FROM revision_outputs o JOIN project_assets a ON a.id=o.asset_id AND a.project_id=o.project_id
+       WHERE o.project_id=?
+       UNION ALL
+       SELECT a.path, p.revision_id, p.id, 'piece:'||COALESCE(json_extract(p.descriptor,'$.kind'),'other'), p.created_at
+       FROM revision_pieces p JOIN project_assets a ON a.id=p.asset_id AND a.project_id=p.project_id
+       WHERE p.project_id=?
+       ORDER BY 5`)
+        .all(projectId, projectId)) {
+        const record = recordRow.parse(row);
+        records.set(record.path, record);
+    }
+    return records;
+}
+export function projectFiles(deps, projectId) {
+    if (projectTitle(deps.db, projectId) === undefined)
+        return undefined;
+    const current = new Map(outputsOf(deps.db, projectId).map((output) => [output.path, output]));
+    const records = revisionRecords(deps.db, projectId);
+    return [...desiredPlaces(deps.db, projectId)]
+        .flatMap(([stored, place]) => {
+        const output = place.startsWith("History/") ? undefined : current.get(stored);
+        const record = records.get(stored);
+        const url = output !== undefined
+            ? `/files/${projectId}/${assetOf(output)}`
+            : record === undefined
+                ? undefined
+                : `/files/${projectId}/revisions/${record.revision_id}/${record.id}`;
+        if (url === undefined)
+            return [];
+        return [
+            {
+                group: groupOf(place),
+                place,
+                role: output?.role ?? record?.role ?? "other",
+                path: outputPath(deps.paths, projectId, stored),
+                url,
+            },
+        ];
+    })
+        .toSorted((a, b) => fileGroups.indexOf(a.group) - fileGroups.indexOf(b.group) || a.place.localeCompare(b.place));
+}

package/dist/slices/studio/settings.js

@@ -242,38 +242,3 @@ export function studioRequestAllowed(db, token, origin) {
         return true;
     return pairing.origin !== null && origin === pairing.origin;
 }
-// Each channel's Studio Analytics view (Advanced mode's Explore link with its chosen columns),
-// which the extension opens every day to export into Channels → YouTube. The start stays as
-// saved; the extension moves the end to today.
-export const studioExportViewPrefix = "studio.exportView.";
-export function exportViewProblem(url) {
-    let parsed;
-    try {
-        parsed = new URL(url.trim());
-    }
-    catch {
-        return "That isn't a link. In YouTube Studio, open Analytics → Advanced mode, set it up, and copy the address from the browser's address bar.";
-    }
-    if (parsed.origin !== "https://studio.youtube.com" ||
-        !/^\/channel\/UC[A-Za-z0-9_-]+\/analytics\/.+\/explore$/.test(parsed.pathname))
-        return "That isn't a Studio Analytics Advanced mode link. In YouTube Studio, open Analytics → Advanced mode, set it up, and copy the address from the browser's address bar.";
-    if (!parsed.searchParams.has("time_period"))
-        return "That link has no date range. In Advanced mode, pick the dates (the start stays as you set it; the end follows today), then copy the address again.";
-    return undefined;
-}
-export function readExportView(db, channelId) {
-    return readSetting(db, `${studioExportViewPrefix}${channelId}`) ?? null;
-}
-export function saveExportView(db, channelId, url) {
-    const key = `${studioExportViewPrefix}${channelId}`;
-    if (url === null || url.trim() === "")
-        db.prepare("DELETE FROM settings WHERE key = ?").run(key);
-    else
-        writeSetting(db, key, url.trim());
-}
-export function exportViews(db) {
-    const prefix = studioExportViewPrefix;
-    return db
-        .prepare("SELECT key, value FROM settings WHERE substr(key, 1, ?) = ? ORDER BY key")
-        .all(prefix.length, prefix).map((row) => ({ channelId: row.key.slice(prefix.length), url: row.value }));
-}

package/dist/slices/studio/stats.js

@@ -1,4 +1,6 @@
 import { z } from "zod";
+// Finished A/B tests as Studio shows them, read by the extension from the video's Analytics.
+// Slopify never asks YouTube's API: these are what Studio showed when the extension last looked.
 export const abVariantSchema = z.object({
     title: z.string().max(200).nullable(),
     // Which thumbnail (1-3) the variant showed, when Studio says.
@@ -8,40 +10,6 @@ export const abVariantSchema = z.object({
     winner: z.boolean(),
 });
 const slot = (short) => short ?? 0;
-const num = (value) => (typeof value === "number" ? value : null);
-export function saveStats(db, stats) {
-    db.prepare(`INSERT INTO video_stats(project_id,short,video_id,read_at,impressions,ctr,views,average_view_seconds,watch_hours)
-     VALUES (?,?,?,?,?,?,?,?,?) ON CONFLICT(project_id,short) DO UPDATE SET video_id=excluded.video_id,
-     read_at=excluded.read_at, impressions=excluded.impressions, ctr=excluded.ctr, views=excluded.views,
-     average_view_seconds=excluded.average_view_seconds, watch_hours=excluded.watch_hours`).run(stats.projectId, slot(stats.short), stats.videoId, stats.readAt, stats.impressions, stats.ctr, stats.views, stats.averageViewSeconds, stats.watchHours);
-}
-function statsOf(row) {
-    const short = Number(row.short);
-    return {
-        projectId: String(row.project_id),
-        short: short === 0 ? null : short,
-        videoId: String(row.video_id),
-        readAt: String(row.read_at),
-        impressions: num(row.impressions),
-        ctr: num(row.ctr),
-        views: num(row.views),
-        averageViewSeconds: num(row.average_view_seconds),
-        watchHours: num(row.watch_hours),
-    };
-}
-export function projectStats(db, projectId) {
-    return db
-        .prepare("SELECT * FROM video_stats WHERE project_id=? ORDER BY short")
-        .all(projectId)
-        .map(statsOf);
-}
-// Each project's long video's numbers, for the Projects list.
-export function longVideoStats(db) {
-    return new Map(db
-        .prepare("SELECT * FROM video_stats WHERE short=0")
-        .all()
-        .map((row) => [String(row.project_id), statsOf(row)]));
-}
 export function saveAbResult(db, result) {
     db.prepare(`INSERT INTO ab_results(project_id,short,video_id,read_at,variants) VALUES (?,?,?,?,?)
      ON CONFLICT(project_id,short) DO UPDATE SET video_id=excluded.video_id, read_at=excluded.read_at,

package/dist/slices/subtitles/prepare.js

@@ -4,7 +4,8 @@ import { join, relative, sep } from "node:path";
 import { z } from "zod";
 import { subtitleModelDir } from "../../kernel/paths.js";
 import { projectLanguage } from "../../kernel/ports/languages.js";
-import { projectById, setStageProgress } from "../admission/repo.js";
+import { projectById } from "../admission/repo.js";
+import { setStageProgress } from "../admission/stage-writes.js";
 import { captionFont, captionFontDeps } from "../fonts/coverage.js";
 import { resolveFont } from "../fonts/index.js";
 import { outputPath, projectDir } from "../storage/layout.js";

package/dist/slices/uploads/repo.js

@@ -1,3 +1,5 @@
+import { admittedUnfinished } from "../admission/admitted-work.js";
+import { oneProject } from "../admission/repo.js";
 export function markUploaded(db, projectId, uploaded, at) {
     if (db.prepare("SELECT 1 FROM projects WHERE id=?").get(projectId) === undefined)
         return { ok: false, reason: "not-found" };
@@ -18,15 +20,19 @@ export function uploadedProjects(db) {
         .all()
         .map((row) => [String(row.project_id), String(row.uploaded_at)]));
 }
-// Uploaded projects with nothing admitted still to run: their leftover steps (a placeholder
-// from an edit after the upload, a pause from a bulk Pause) are not work the person is
-// waiting for, so the listing calls them done rather than "Paused" or "Waiting".
-export function uploadedAndSettled(db) {
+// Uploaded projects with nothing left to run read done, not "Paused" or "Waiting": a step still
+// allowed to run, or a held one admitted for the current version (`admittedUnfinished`, as
+// `reviews/holds.ts` heldBesideReviews reads it), keeps one unsettled. What is left otherwise
+// - a placeholder from an edit after the upload, a pause from a bulk Pause - is not work the
+// person waits for. One project's alone when `projectId` is given.
+export function uploadedAndSettled(db, projectId) {
+    const one = oneProject("u", projectId);
     return new Set(db
         .prepare(`SELECT u.project_id FROM project_uploads u WHERE NOT EXISTS(
            SELECT 1 FROM revision_work w WHERE w.project_id=u.project_id
-             AND w.state IN ('pending','running') AND w.dispatch_state!='held')`)
-        .all()
+             AND w.state IN ('pending','running')
+             AND (w.dispatch_state!='held' OR ${admittedUnfinished("w")}))${one.sql}`)
+        .all(...one.params)
         .map((row) => String(row.project_id)));
 }
 // "Keep as is": a waiting run the person leaves as it is, until the project's next edit. Set on

package/dist/slices/uploads/rules.js

@@ -0,0 +1,5 @@
+// An uploaded, settled project (`uploadedAndSettled`) reads done where its run would read paused
+// or pending: the Projects list, a project's page and the calendar.
+export function settledStatus(status, settled) {
+    return settled && (status === "paused" || status === "pending") ? "done" : status;
+}

package/dist/slices/video/write-export.js

@@ -1,7 +1,7 @@
 import { copyFileSync, existsSync, mkdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { dirname } from "node:path";
 import { transact } from "../../kernel/db/tx.js";
-import { setStageProgress } from "../admission/repo.js";
+import { setStageProgress } from "../admission/stage-writes.js";
 import { outputPath } from "../storage/layout.js";
 import { deleteOutput, insertOutput, outputsOf } from "../storage/repo.js";
 import { subtitleRoles } from "../subtitles/prepare.js";

package/dist/slices/video/write-subtitles.js

@@ -1,6 +1,6 @@
 import { rmSync, statSync } from "node:fs";
 import { transact } from "../../kernel/db/tx.js";
-import { setStageProgress } from "../admission/repo.js";
+import { setStageProgress } from "../admission/stage-writes.js";
 import { outputPath } from "../storage/layout.js";
 import { deleteOutput, insertOutput, outputsOf } from "../storage/repo.js";
 import { subtitleRoles } from "../subtitles/prepare.js";

package/dist/tutorials/Agents-MCP.md

@@ -0,0 +1,168 @@
+# Agents (MCP)
+
+Slopify has a built-in MCP server, so an AI agent on your computer (Claude Code, Codex, or any other client that speaks MCP over HTTP) can run Slopify for you. It can start and fix runs, edit the Library and your setup, answer reviews and approve checkpoints, with the same checks, costs and refusals as the buttons in the web page. Run on a schedule, an agent can clear everything that would otherwise wait for you, right up to **Ready to upload**. Uploading stays yours.
+
+**Where to find it:** **Settings → Connections → Agents (MCP)**.
+
+## What the Agents tab shows
+
+| Part | What it is |
+| --- | --- |
+| **MCP address** | The address agents connect to: this install's address with `/mcp` after it, for example `http://127.0.0.1:6969/mcp`. It uses the address in your browser's address bar, so it matches your port and Docker's published port. |
+| **Claude Code** | The command that adds Slopify to Claude Code, with **Copy**. Run it once in a terminal. |
+| **Codex** | The lines that add Slopify to Codex, with **Copy**. Add them to `~/.codex/config.toml`. |
+| Last connected | When an agent last connected, or "No agent has connected yet." |
+| **What agents did** | The latest 20 changes made by agents, newest first: what was done, the project or schedule it was done to, and when. Changes outside a project (a Library prompt, a schedule, a setting) are listed here too. "No agent has changed anything yet." when there are none. |
+
+If the browser blocks the clipboard, **Copy** says so; select the line and copy it yourself.
+
+## Connect an agent
+
+Slopify must be running. The address in these examples is the default (`127.0.0.1`, port `6969`); copy the real lines from the Agents tab.
+
+### Claude Code
+
+1. Open **Settings → Connections → Agents (MCP)** and press **Copy** next to **Claude Code**.
+2. Paste it in a terminal and run it:
+
+   ```
+   claude mcp add --transport http slopify http://127.0.0.1:6969/mcp
+   ```
+
+3. Start Claude Code. `/mcp` there should list `slopify` as connected, and the Agents tab now shows when it last connected.
+
+### Codex
+
+1. Press **Copy** next to **Codex**.
+2. Add the lines to `~/.codex/config.toml`:
+
+   ```
+   [mcp_servers.slopify]
+   url = "http://127.0.0.1:6969/mcp"
+   ```
+
+3. Start Codex again so it reads the file.
+
+### Other agents
+
+Any MCP client that connects by URL over Streamable HTTP takes the same **MCP address**. Slopify keeps no session: every request is a plain `POST`.
+
+### Docker
+
+Nothing changes: the agent runs on your computer and connects to the port Docker publishes, the same address you open Slopify at. Copy the lines from the Agents tab in that Slopify. See [Docker](Docker).
+
+## No token, and what keeps web pages out
+
+There is no key or token to set up, the same as the web page itself: Slopify has no login, and it listens on `127.0.0.1` so only your own computer reaches it.
+
+Web pages are kept out by one check. A request that comes from a web page at another address (a browser always says where a request came from) is refused with "Slopify refused this MCP request because it came from a web page at another address." Agents on the command line send no such address and are let in. Pages on this computer's own addresses (`localhost`, `127.0.0.1`) are let in too.
+
+If you start Slopify with `--host 0.0.0.0` (or another address other computers can reach), anyone who reaches the port can drive it through `/mcp`, just as they can through the web page. Keep it on `127.0.0.1` unless you mean that. See [Install](Install).
+
+## What agents can do
+
+Anything you can do in the web page, except the few things listed under [What agents cannot do](#what-agents-cannot-do). That includes:
+
+- **Projects:** make projects from Play drafts and templates (after the same review and estimate you see), read them, edit them, pause, continue and cancel runs, **Keep as is**, move projects to another channel, delete and restore them.
+- **Fixing runs:** **Try ... again**, **Soften and retry**, remake a step or one item, regenerate a narration chunk, and **Choose what to remake**, with its estimate.
+- **Reviews:** answer reviews set to **External agent (MCP)**, **Overrule** or **Redo** flagged items, and approve review checkpoints.
+- **Planning:** release times, the posting plan, **Mark uploaded**, **Deleted on YouTube**, and **Prepare upload** up to **Ready to upload**.
+- **Schedules:** schedules, their topic lists, approving or turning down held topics, and **Prepare**.
+- **Library and setup:** prompts (with history), templates, channels and cast, Library import and export, and settings other than those below.
+- **Reading:** Home's work list, the calendar, costs and estimates, a project's files (pictures come back as pictures; audio and video as their address in Slopify), and the material a review looks at.
+- **Storage:** **Delete old versions** for one project.
+
+Agents never start paid work you could not see: before a remake they get the same **Choose what to remake** list with its estimate, and they must accept it, as you do. There is no extra budget or limit for agents; the costs are the same as yours. Actions with a consequence (deleting, for example) need the agent to confirm them, as a dialog asks you.
+
+Agents and their tools use the same state words as the page: **Queued**, **Running**, **Paused**, **Waiting for your review**, **Waiting for the agent**, **Prepared**, **Stopped**, **Kept as is**, **Failed**, **Done**.
+
+## What agents cannot do
+
+| Not for agents | Why |
+| --- | --- |
+| Upload to YouTube, or send a video to the Studio extension (**Fill in YouTube Studio**, **Upload**) | Agents stop at **Ready to upload**. Uploading is yours; Slopify never makes a video public. See [Publishing to YouTube](Publishing-to-YouTube). |
+| The extension's automatic pinned comment setting | It posts comments in your name. |
+| Read or change provider keys, or make the extension's pairing token | They are credentials. Agents see each provider only as configured or missing. |
+| Read the **Notification URL** | It can hold a secret (a private ntfy topic). Agents see only whether one is configured or missing, though they may set a new one. |
+| Backups: export, import, restore, and the daily backup settings | They are yours, in Settings → Backup & storage. |
+| Update Slopify, start at login, CLI paths, the extension's download | They are yours. |
+| **Delete all old versions** and **Clean up everything** (all projects) | They are yours, in Settings → Backup & storage. **Delete old versions** for one project is allowed. |
+| Open a folder on your desktop | Agents read files through Slopify instead. |
+
+A request for any of these is refused with a sentence that says it is yours and where to do it.
+
+## Shown as "by agent"
+
+Everything an agent changes is marked, so you can always tell its work from yours:
+
+| Where | What you see |
+| --- | --- |
+| Project page → **Project history** | Versions an agent saved end in **· by agent**, and **Done by agents** lists what agents did to the project (approvals, retries, verdicts and so on). |
+| Review badges | **Passed by agent**, **Flagged by agent**, **Redone after agent review**, **Accepted by agent** (an agent pressed Overrule), **Made again by agent** (an agent pressed Redo). |
+| Notifications | A run an agent started ends its notices with **· started by agent** ("Started: *title* · by agent" in the browser); a flag from an agent's review ends with **· by agent**. |
+| Settings → Agents (MCP) | **What agents did**: the latest 20 changes of every kind. |
+
+## The External agent reviewer
+
+Instead of paying a reviewer model, you can let your agent do the [automatic reviews](Reviews-and-Checkpoints#automatic-reviews).
+
+1. On Play, open the **Reviews** row (or Edit project → **Reviews** on a project).
+2. Set **Who reviews** to **External agent (MCP)**. **Reviewer** and **Reviewer model** are greyed: the agent needs neither.
+3. Pick **Flag only** or **Flag and redo** for each stage, as usual. Picture stages (images, the thumbnail, shorts) work too: the agent is shown the pictures.
+
+Reviews by the agent cost nothing and add nothing to the estimate. Redos it asks for cost what the item cost, as always.
+
+### What happens during the run
+
+1. When an item is made, its review waits for the agent. What depends on it waits too; other work carries on.
+2. If nothing else holds the run, the project reads **Waiting for the agent** everywhere: its header, Projects, Home's **Running now** and the calendar. The project page says "An agent is reviewing what was made." with nothing to press. It is not in **Needs you**, no "Waiting for you" notice goes out and there is no **Continue the run** to press: it goes on by itself.
+3. The agent reads the item and answers **pass** or **fail**. A fail needs at least one reason; at most 10 reasons, each up to 500 characters. The answer goes through the stage's mode, exactly like a model's verdict: a pass lets the work go on, a fail is flagged or made again.
+4. **The first answer wins.** If two agents answer the same review, the first one saved is kept and the second is refused ("This review was already answered"). The same goes for you: once an agent has pressed Overrule or Redo on a flagged item, or approved a checkpoint, pressing it yourself changes nothing and says it was already decided.
+
+### If no agent answers
+
+A review nobody answers **passes by itself 2 hours** after it began waiting. Its badge reads **Passed without review** ("No agent answered within 2 hours, so it went ahead without review."), the work goes on, and you get a notification: **Passed without review: no agent answered in 2 h**, naming the project and the item. The two hours are saved with the review, so a restart neither resets nor loses them.
+
+- **Paused project:** the review still passes at its two hours, but nothing runs until the run is continued.
+- **Canceled run:** its waiting reviews stop and never pass. If you (or an agent) take the step up again, the review asks again and waits a fresh two hours.
+- **Item made again meanwhile** (an edit or a remake): the old review is dropped and the new item gets its own.
+
+## Paused and stopped runs
+
+An agent may **continue any paused run**, whoever paused it, once nothing else on the project still needs fixing. It may also press **Continue the run** on a run a restart left **Stopped**. If you want a run to stay put while an agent routine is running, cancel it instead of pausing it: canceled runs are not on the agent's list.
+
+## needs_attention and the attend routine
+
+Slopify cannot wake an agent; the agent looks. Its work list is the `needs_attention` tool: Home's **Needs you**, as an agent reads it, oldest first.
+
+| Entry | What the agent does |
+| --- | --- |
+| An external review waiting for a verdict | Reads the item and answers. |
+| A flagged verdict nobody acted on | **Overrule** or **Redo**. |
+| A review checkpoint waiting for approval | Checks the work before it and approves. A checkpoint from the template's own **Before Video** is listed; a schedule's **Prepared** hold is not, since that one waits for its day. |
+| A failed step | Does what the error's own sentence says: for example regenerates narration chunk 5, accepts the **Choose what to remake** estimate, then continues the run. |
+| A paused run, or a run a restart **Stopped** | Continues it once nothing on the project still needs fixing. |
+| Topics a schedule holds for approval | Approves the ones that fit and turns down the rest. |
+| A video marked **Late · upload now** | Reports it. It cannot upload. |
+| A finishing touch the Studio extension failed (captions, end screen, pinned comment) | Reports it. Fixing it is the extension's or yours. |
+
+Projects that are **Kept as is** are not listed. Each entry says whether Slopify is already retrying or redoing it by itself (the agent leaves those alone and looks again later) and whether the agent can act on it at all.
+
+The steps above are the **attend routine**. Slopify hands it to every agent that connects, and offers it as the MCP prompt **attend**: in Claude Code, `/mcp__slopify__attend` runs it. To have it run unattended, schedule it in your agent, for example as a Claude Code scheduled task or a Codex automation every hour. An hourly routine answers external reviews well inside their two hours.
+
+## Tips
+
+- Pair the External agent reviewer with an hourly attend routine, and a [Notification URL](Notifications#get-notifications-on-your-phone-notification-url) so you hear when a review passed without an answer: that usually means the routine stopped running.
+- Check **What agents did** in the Agents tab now and then; each project's **Project history** has the full story for that project.
+- If an agent's request is refused because the project changed meanwhile, it reads the project again and retries once; you do not need to do anything.
+
+## Related pages
+
+- [Reviews and Checkpoints](Reviews-and-Checkpoints)
+- [Notifications](Notifications)
+- [Recovery and Retries](Recovery-and-Retries)
+- [Home and Projects](Home-and-Projects)
+- [Schedules](Schedules)
+- [Publishing to YouTube](Publishing-to-YouTube)
+- [Settings Reference](Settings-Reference)
+- [AI CLIs](AI-CLIs)

package/dist/tutorials/Calendar.md

@@ -10,7 +10,7 @@ The calendar starts on this week's Monday and shows four weeks, Monday to Sunday
 
 - **Scheduled runs**, each with the project title it will make. A run shows **Queued** when a topic is lined up, **Needs a topic** when its topic is still waiting for your approval or for generation, and **Paused** when its schedule is paused.
 - **Needs you**, above the weeks: every project that is waiting on you or ready to upload (see below).
-- **Projects** running or finished on their day, with their state: **Running**, **Paused**, **Queued**, **Failed**, **Done with problems**, **Done** or **Canceled**. A project waiting for a CLI plan says so, for example **Waiting for Codex limits (resets at 14:00)**.
+- **Projects** running or finished on their day, with their state: **Running**, **Waiting for the agent**, **Paused**, **Queued**, **Waiting for your review**, **Prepared**, **Stopped**, **Kept as is**, **Failed**, **Done with problems**, **Done** or **Canceled**. A project waiting for a CLI plan says so, for example **Waiting for Codex limits (resets at 14:00)**.
 - **Batch queue**: projects waiting to start (see below).
 - **Suggested topics**, beside the weeks, for schedules that hold generated topics for approval.
 
@@ -26,6 +26,7 @@ Above the weeks, **Needs you** lists what cannot move on without you, then what
 | --- | --- | --- |
 | A failed project | **Failed** | **Open to fix** |
 | A project you paused | **Paused** | **Open to continue** |
+| A project a restart stopped before it finished | **Stopped** | **Open to continue** |
 | A project held at a review checkpoint, or with an automatic review that flagged an item and waits for **Overrule** or **Redo** | **Waiting for your review** | **Open to review** |
 | A finished video not marked uploaded | **Ready to upload** | **Prepare upload** |
 

package/dist/tutorials/First-Launch-and-Welcome.md

@@ -140,6 +140,7 @@ Settings → **Providers** shows a short welcome on a fresh install that names t
 - Try a sample before you add any keys: every screen works on it, and nothing costs anything.
 - You can come back to the first-run screen at `/welcome` until you skip it or make a real project.
 - After an update to a new major version, a **What's new** tour opens instead. See [Updating and Patch Notes](Updating-and-Patch-Notes).
+- Already use Claude Code or Codex? Settings → Connections → **Agents (MCP)** has one line that lets it run Slopify for you: start and fix runs, answer reviews, everything up to Ready to upload. See [Agents (MCP)](Agents-MCP).
 
 ## Related pages
 

package/dist/tutorials/Home-and-Projects.md

@@ -53,19 +53,22 @@ One work list: the things that don't move on until you act, then the finished vi
 
 | Item | Status | Button |
 | --- | --- | --- |
-| A run held at a review before a step | **Waiting for you · review before the narration** (or the images, or the video) | **Approve the article and record**, **Approve and draw the images** or **Approve and render**. Approving here lets the run continue. Open the project to look first. |
-| A run whose next step is held another way | **Waiting for you** | **Open to continue** |
-| A run you paused | **Paused** | **Open to continue** |
+| A run held at a review before a step | **Waiting for your review · before the narration** (or the images, or the video) | **Approve the article and record**, **Approve and draw the images** or **Approve and render**. Approving here lets the run continue. Open the project to look first. |
+| A run whose next step is held another way | **Waiting for your review** | **Open to continue** |
+| A run a restart stopped before it finished | **Stopped** | **Continue the run**, or **Keep as is** to leave the rest unmade |
+| A run you (or an agent) paused | **Paused** | **Open to continue** |
 | Topics a schedule suggested | **N new topics** | **Review topics**, on the calendar: queue the ones you want and reject the rest. |
 | A failed run | **Failed · <step>**, with a short reason | The fix to try: a button to Settings → Providers or Backup & storage when that is the fix, otherwise **Open to retry**. |
 | A run that failed because a CLI is signed out | **Failed · <step>** | **Copy sign-in command** copies the command (`claude auth login`, `codex login` or `gemini`). Run it in a terminal on the computer running Slopify, then **Open to retry** and press **Check again** on the project. |
 | A finished video you have not marked uploaded | **Ready to upload** | **Prepare upload** lists everything YouTube Studio asks for, with Copy buttons (Slopify never uploads for you; see [Publishing to YouTube](Publishing-to-YouTube)). **Mark uploaded** takes it off the list, with **Undo** in the notice; Projects still has it. |
 
+A held run also offers **Keep as is**, which takes it off Needs you and leaves the rest unmade (with **Undo**); editing the project brings it back. A run waiting for an [agent's review](Agents-MCP#the-external-agent-reviewer) is not here: it goes on by itself, so it shows under Running now. A step that failed while the run waits on something else shows here as a failed item.
+
 Up to 4 failed runs and 4 videos ready to upload show here; **See all N ready to upload** opens Projects filtered to them. The bundled samples never show as ready to upload. Only the first item's button is lime; the rest are plain buttons. The heading says how many decisions are waiting and how many videos are ready to upload. With nothing waiting and nothing running, Home says **Nothing needs you and nothing is running**. See [Reviews and Checkpoints](Reviews-and-Checkpoints), [Schedules](Schedules) and [Recovery and Retries](Recovery-and-Retries).
 
 ### Running now
 
-Videos being made or paused, up to 3. Each shows the step it is on, how long each step has taken, the running step's time left (for example `2 of 8 · about 4 min left`), the last few images as they land (with a tile for the one being drawn) and **Images N of M** while drawing. A run waiting for a CLI plan says so instead of the step, for example **Waiting for Codex limits (resets at 14:00)**. Open one to follow it live, pause it or cancel it. With nothing running it says **Start the next video**.
+Videos being made, and runs **Waiting for the agent** (an External agent reviews what they made; they carry on once it answers or after 2 hours), up to 3. Paused runs are under Needs you. Each shows the step it is on, how long each step has taken, the running step's time left (for example `2 of 8 · about 4 min left`), the last few images as they land (with a tile for the one being drawn) and **Images N of M** while drawing. A run waiting for a CLI plan says so instead of the step, for example **Waiting for Codex limits (resets at 14:00)**. Open one to follow it live, pause it or cancel it. With nothing running it says **Start the next video**.
 
 - With more than three running, **See all N running** opens Projects filtered to running.
 - Queued runs show as one line under them, for example "Queued, waiting to start (2): Hypatia, Cleopatra", with **See queued** (Projects filtered to queued).
@@ -102,11 +105,11 @@ Every run ever started, newest first unless you pick another order, for the chan
 | Filter | Shows |
 | --- | --- |
 | **All** | Everything. |
-| **Running** | Running and paused projects. |
+| **Running** | Projects running, and those **Waiting for the agent**: the same runs Home's **See all N running** counts. |
 | **Queued** | Projects waiting for their turn in the video queue. |
-| **Needs you** | Projects waiting at a review or held step. |
+| **Needs you** | Projects waiting for you: at a review or held step, paused, or **Stopped**. |
 | **Ready to upload** | Finished videos not marked uploaded. |
-| **Failed** | Failed projects and those **Done with problems**. |
+| **Failed** | Failed projects, those **Done with problems**, and runs with a failed step that still wait on something else. |
 
 3. Pick an order beside the filter: **Newest first**, **Recently changed**, **Name (A–Z)** or **Status** (waiting for you first, then running, queued, failed and finished).
 
@@ -128,9 +131,13 @@ If nothing matches, the list says **No project matches. Clear the search or pick
 | State | Meaning |
 | --- | --- |
 | **Running** | A step is being made. A run waiting for a CLI plan says **Waiting for Codex limits (resets at 14:00)** instead. |
-| **Paused** | Paused by you; nothing runs until you resume. |
+| **Paused** | Paused by you or an agent; nothing runs until it is continued. |
 | **Queued** | Waiting for its turn in the video queue. |
-| **Waiting for you** | Held at a review or checkpoint. |
+| **Waiting for your review** | Held at a review or checkpoint. |
+| **Waiting for the agent** | An External agent is reviewing what it made; it goes on by itself. |
+| **Prepared** | Made ahead by its schedule; only the video is left, for its day. |
+| **Stopped** | Stopped before it finished, for example by a restart. Open it and press **Continue the run**. |
+| **Kept as is** | What is left was set aside with **Keep as is**. |
 | **Done** | Finished. |
 | **Done with problems** | Finished, but part of it failed. |
 | **Failed** | Stopped with an error. |

package/dist/tutorials/Home.md

@@ -87,6 +87,7 @@ These pages cover Slopify 3.0: every screen, every setting and every workflow, s
 | [Schedules](Schedules) | Videos on a cadence, topic lists and self-filling topics |
 | [Calendar](Calendar) | What needs you, what is coming up, the video queue |
 | [Notifications](Notifications) | Browser and phone (ntfy) notifications |
+| [Agents (MCP)](Agents-MCP) | Letting Claude Code, Codex or another agent run Slopify, the External agent reviewer and the attend routine |
 | [Backups](Backups) | Automatic backups, export and import |
 
 ### Channels

package/dist/tutorials/Notifications.md

@@ -8,13 +8,30 @@ Runs can take a while, so Slopify can tell you when one needs you: in the browse
 
 | Event | Message |
 |---|---|
-| A run **finishes** | "Video ready", or "Run finished" for a run that makes audio only |
-| A run **fails** | The project title and the first line of the reason |
-| A run **stops to wait for you** | A review checkpoint is holding the next step, or the work left is waiting for Resume |
+| A run **finishes** | "Video ready: *title*", or "Run finished: *title*" for a run that makes audio only |
+| A run **finishes with problems** | "Video ready with problems: *title* — *reason*": the video was made but another step failed |
+| A run **fails** | "Run failed: *title* — *reason*", with the first line of the reason |
+| A step **fails while the run waits on something else** | "Step failed: *title* — *reason*". Only when another step is waiting: an agent's review, your checkpoint, or a prepared run's day. See [Step failed](#step-failed). |
+| A run **stops to wait for you** | "Waiting for you: *title*": a review checkpoint is holding the next step, or the work left is waiting for **Continue the run** |
+| An agent's review **passed without an answer** | "Passed without review: no agent answered in 2 h", naming the project and the item. See [Agents (MCP)](Agents-MCP#if-no-agent-answers). |
 | An automatic review **needs a decision** | "Review needs a decision: <title>", when an automatic review flags an item and keeps it (its redos ran out, or the stage only flags). It says what was flagged and to press **Overrule** or **Redo** on the project. Sent once per verdict. |
 | A schedule has **new topics waiting** for approval | For example "5 new topics are waiting for you" |
 
-Pausing or cancelling a run yourself sends nothing, and neither does a project that was already finished when the page loaded. A message holds the project title and what happened, never your keys, prompts or files.
+Pausing or cancelling a run yourself sends nothing, and neither does a project that was already finished when the page loaded. A run waiting for an [agent's review](Agents-MCP#the-external-agent-reviewer), or a prepared run waiting for its day, sends no "Waiting for you": nobody needs to act. A message holds the project title and what happened, never your keys, prompts or files.
+
+A run an [agent](Agents-MCP) started ends its messages with **· started by agent**, and a flag from an agent's review ends with **· by agent**.
+
+### Step failed
+
+An ordinary run tells you once, at its end: "Run failed" or "Video ready with problems", with the end chime. A step that fails on the way is named there, not in a message of its own.
+
+"Step failed" is for the other case: a step fails while another step of the run is waiting (for an agent's review, your checkpoint, or a prepared run's day). The run is not over and may wait for hours, so Slopify tells you right away instead of at the end. The project still reads by what it waits for, and the failed step shows on its page with its fix.
+
+Each failure is told once. A restart neither repeats a message already sent nor loses one: what was told is saved. A step that fails again after **Try again** is a new failure and is told again. If the run later ends **Failed** on failures already told, no second "Run failed" goes out.
+
+### While you were away
+
+When you come back to a Slopify tab after more than two minutes away (or open one after closing it), one notice sums up what happened meanwhile, for example "While you were away: 2 runs finished, 1 step failed beside a wait, 1 run waits for you.", with **Open Home**. It counts runs that finished, runs that failed, steps that failed beside a wait, and runs that started waiting for you. Runs waiting for an agent or for their day are not counted as waiting for you. It works from this browser's own memory of what it last saw, with no setting.
 
 ## Turn on browser notifications
 
@@ -44,7 +61,7 @@ Some browsers only allow notifications from installed apps. If the test says so,
 
 ## Run sounds
 
-**Settings → Notifications → Run sounds** (on by default) plays a chime when a run starts and a different, longer one when it finishes, fails or stops to wait for you, like a message arriving on a phone. **Play start** and **Play end** let you hear them.
+**Settings → Notifications → Run sounds** (on by default) plays a chime when a run starts and a different, longer one when it finishes, fails or stops to wait for you, like a message arriving on a phone. A "Step failed" plays the end chime too. **Play start** and **Play end** let you hear them.
 
 - Works while any Slopify tab is open; only one tab plays each chime.
 - Needs no permission, but browsers keep a page silent until it has been clicked once, so click anywhere in Slopify after opening it.
@@ -53,7 +70,7 @@ Some browsers only allow notifications from installed apps. If the test says so,
 
 ## Get notifications on your phone (Notification URL)
 
-A Notification URL works with no Slopify tab open. When a run finishes, fails or waits, or a review needs a decision, Slopify sends that address one `POST` with a short plain-text body. Its last line is the project's link, so you can open it straight from the message, for example:
+A Notification URL works with no Slopify tab open. When a run finishes, fails or waits, a step fails beside a wait, a review needs a decision or passes without an agent's answer, Slopify sends that address one `POST` with a short plain-text body. Its last line is the project's link, so you can open it straight from the message, for example:
 
 ```
 Video ready: Black holes explained
@@ -79,6 +96,7 @@ To turn it off, clear the field and press **Save**.
 - Any address that accepts a `POST` works, not just ntfy.
 - Each message is sent once, with a 5-second timeout, and is never retried. A failure is written to the log and does not affect the run.
 - The address stays on this machine: backups leave it out.
+- [Agents](Agents-MCP) never see the address, only whether one is configured. They may set a new one.
 - In [Docker](Docker) the request goes out from the container, so the address must be reachable from there. `localhost` means the container itself.
 
 ## Tips
@@ -92,4 +110,5 @@ To turn it off, clear the field and press **Save**.
 - [Schedules](Schedules)
 - [Calendar](Calendar)
 - [Reviews and checkpoints](Reviews-and-Checkpoints)
+- [Agents (MCP)](Agents-MCP)
 - [Troubleshooting](Troubleshooting)