@gentbajko/slopify 3.13.2 → 3.14.1

package/dist/kernel/db/migrations/0054-project-places.sql

@@ -0,0 +1,27 @@
+-- Readable project folders (3.14.0). A project's folder was its id and its files sat under
+-- assets/<asset id>/, which nobody could find their way around. Each project now gets a
+-- folder named after its title, and each file a place in it: Upload/ (the current version's
+-- publishable files), Working/ (what they were made from) and History/<date>/ (older
+-- versions). Every stored path (`assets/<id>/video.mp4`) stays as it is in every table and
+-- archive; these two tables say where it is on disk (`slices/storage/places.ts`).
+--
+-- `state` is 'moving' between recording a move and finishing it, so a crash in between is
+-- settled at the next start from what is on disk (`recoverPlaces`). `previous` is where the
+-- file or folder was before, for that check.
+CREATE TABLE project_folders (
+  project_id TEXT PRIMARY KEY REFERENCES projects(id) ON DELETE CASCADE,
+  folder TEXT NOT NULL CHECK(length(folder) > 0),
+  previous TEXT,
+  state TEXT NOT NULL DEFAULT 'placed' CHECK(state IN ('moving','placed')),
+  arranged TEXT
+);
+CREATE UNIQUE INDEX project_folders_folder ON project_folders(folder COLLATE NOCASE);
+CREATE TABLE file_places (
+  project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  path TEXT NOT NULL,
+  place TEXT NOT NULL,
+  previous TEXT,
+  state TEXT NOT NULL DEFAULT 'placed' CHECK(state IN ('moving','placed')),
+  PRIMARY KEY(project_id, path)
+);
+CREATE UNIQUE INDEX file_places_place ON file_places(project_id, place COLLATE NOCASE);

package/dist/kernel/paths.js

@@ -14,6 +14,10 @@ export function layout(dataDir, files) {
         lock: join(root, ".lock"),
     };
 }
+// Gives a running install's Paths the places of moved project folders and files.
+export function attachPlaces(paths, places) {
+    Object.assign(paths, { places });
+}
 // Points a running install's Paths at moved files. The one object every slice was handed is
 // changed in place, so the next file each one reads or writes is in the new place.
 export function repoint(paths, files) {

package/dist/main.js

@@ -29,7 +29,7 @@ import { causedBy } from "./kernel/errors.js";
 import { ulidIds } from "./kernel/ids.js";
 import { acquireInstanceLock } from "./kernel/lock.js";
 import { openLog } from "./kernel/log.js";
-import { ensureDataDirs, ensureDirs, layout, repoint, subtitleModelDir } from "./kernel/paths.js";
+import { attachPlaces, ensureDataDirs, ensureDirs, layout, repoint, subtitleModelDir, } from "./kernel/paths.js";
 import { stageKinds } from "./kernel/pipeline.js";
 import { sqliteAttempts } from "./kernel/runner/attempt-repo.js";
 import { auditionVoice } from "./kernel/runner/audition.js";
@@ -71,9 +71,12 @@ import { createScheduleRunner } from "./slices/schedules/scheduler.js";
 import { nodeCliProbe } from "./slices/settings/cli-status.js";
 import { isLocalCliProvider, localCliConcurrency } from "./slices/settings/model.js";
 import { providerStatuses } from "./slices/settings/readiness.js";
+import { readSetting } from "./slices/settings/repo.js";
+import { arrangeChanged } from "./slices/storage/arrange.js";
 import { busyProjects } from "./slices/storage/backup-export.js";
 import { documentsDir, nodeDocumentsHost } from "./slices/storage/documents.js";
-import { createFilesService, ensureFilesFolders, filesLayoutOf, settleFilesLocation, } from "./slices/storage/files-location.js";
+import { createFilesService, ensureFilesFolders, filesLayoutOf, filesMoveKey, settleFilesLocation, } from "./slices/storage/files-location.js";
+import { createPlaces, recoverPlaces } from "./slices/storage/places.js";
 import { reconcileStorage } from "./slices/storage/reconcile.js";
 import { previewPictures } from "./slices/style-preview/images.js";
 import { ffmpegStylePreview } from "./slices/style-preview/render.js";
@@ -183,6 +186,11 @@ export async function boot(config, options = {}) {
             ensureDirs(paths, { mode: 0o700 });
         else
             await ensureFilesFolders(files);
+        // Readable project folders (`slices/storage/places.ts`): settle a move a crash cut short,
+        // then every file is looked up where it is, before anything reads one.
+        recoverPlaces(db, paths);
+        const places = createPlaces(db);
+        attachPlaces(paths, places);
         const runtimeDb = db;
         const interrupted = markInterruptedStages(db, clock);
         recoverCheckpointWork(db);
@@ -298,6 +306,9 @@ export async function boot(config, options = {}) {
             throw new Error("The server is not ready.");
         };
         let listeningPort = config.port;
+        // Folders are renamed only by a version that is committed: an update on trial can still be
+        // rolled back to a version that knows only id-named folders.
+        let arrangeAllowed = !pendingActivation;
         const updater = createUpdater({
             ...(isUpdateToken(candidateToken)
                 ? {
@@ -308,6 +319,7 @@ export async function boot(config, options = {}) {
                             ? updateCommitted(paths.dataDir, version, candidateToken)
                             : dockerActivationCommitted(dockerState, candidateToken),
                         settle: () => {
+                            arrangeAllowed = true;
                             try {
                                 const settled = reconcileStorage(updateDb, paths);
                                 log.write("info", "update", {
@@ -623,6 +635,26 @@ export async function boot(config, options = {}) {
         };
         purgeTrash();
         const trashTimer = setInterval(purgeTrash, 60 * 60_000);
+        // Each project whose title, version or files changed is arranged into its readable folder
+        // (`slices/storage/arrange.ts`) once nothing of it runs: a quarter second of it at a time,
+        // so the server keeps answering, and never while files move or an update installs.
+        const arrange = () => {
+            if (!arrangeAllowed || readSetting(updateDb, filesMoveKey) !== undefined)
+                return;
+            const release = updater.beginMutation();
+            if (!release)
+                return;
+            try {
+                arrangeChanged({ db: updateDb, paths, places, now: () => clock.now() }, 250);
+            }
+            catch (error) {
+                log.write("error", "storage.arrange", { detail: causedBy(error) });
+            }
+            finally {
+                release();
+            }
+        };
+        const arrangeTimer = setInterval(arrange, 5_000);
         listeningPort = portOf(server) ?? config.port;
         // Whatever last run left queued goes out at start. Nothing waits for
         // it, and an unreachable collector costs one refused socket.
@@ -651,6 +683,7 @@ export async function boot(config, options = {}) {
                 clearInterval(retryTimer);
                 clearInterval(backupTimer);
                 clearInterval(trashTimer);
+                clearInterval(arrangeTimer);
                 clearInterval(modelTimer);
                 const mutationDrain = mutations.stop();
                 const scheduleDrain = scheduleTicks.stop();

package/dist/patch-notes/3.14.0.md

@@ -0,0 +1,12 @@
+# Slopify 3.14.0
+
+Released 9 October 2026.
+
+- **Project folders you can find your way around.** Each project's folder is now named after its title instead of a code, and its files are sorted the way you look for them:
+  - `Upload/`: the current version, ready to publish: the video, thumbnails, subtitles, description, tags, titles, pinned comment, PDF, article, and `Shorts/1 - <title>.mp4`.
+  - `Working/`: what that version was made from: images, each narration chunk, research, subtitle timing, render settings.
+  - `History/<date>/`: older versions (an earlier render, the narration before a voice change). Delete a day's folder, or all of History, to get the space back; going back to that version makes its files again.
+
+  Slopify sorts your existing projects in the background after the update, a few at a time, without stopping the app; a project is sorted once nothing of it is running. Nothing is copied, so it takes no extra disk space, and your backups work in every version as before. Files you add to these folders yourself are never removed, and a folder in Projects that Slopify didn't make is left alone. See [Where Your Files Live](https://github.com/gentbajko/slopify/wiki/Where-Your-Files-Live#inside-a-project-folder).
+
+  **Don't go back to a version older than 3.14 after this update:** older versions only know folders named by project code and would remove the readable ones when they start.

package/dist/patch-notes/3.14.1.md

@@ -0,0 +1,5 @@
+# Slopify 3.14.1
+
+Released 9 October 2026.
+
+- **Videos finish sooner.** After rendering a video, Slopify checks how loud it came out. That check decoded the whole picture just to read the sound, which took 20 minutes or more for a two-hour video and slowed down any other render running at the same time. It now reads only the sound, so a video is done a few minutes after its render reaches 100%.

package/dist/patch-notes/index.json

@@ -1,4 +1,16 @@
 [
+  {
+    "id": "3.14.1",
+    "title": "Slopify 3.14.1",
+    "version": "3.14.1",
+    "date": "2026-10-09"
+  },
+  {
+    "id": "3.14.0",
+    "title": "Slopify 3.14.0",
+    "version": "3.14.0",
+    "date": "2026-10-09"
+  },
   {
     "id": "3.13.2",
     "title": "Slopify 3.13.2",

package/dist/slices/loudness/loudnorm.js

@@ -25,6 +25,11 @@ export function measureArgs(input, goal, chain = "") {
         "info",
         "-nostats",
         ...input,
+        // Only the sound is measured: a finished video's picture was decoded too, 20 minutes and
+        // more of a CPU's time for a two-hour export, while the next render waited for it.
+        "-vn",
+        "-sn",
+        "-dn",
         "-af",
         `${chain === "" ? "" : `${chain},`}${measureFilter(goal)}`,
         "-f",

package/dist/slices/onboarding/copy.js

@@ -4,6 +4,7 @@ import { transact } from "../../kernel/db/tx.js";
 import { executionPlan } from "../rebuild/runtime-plan.js";
 import { currentRevisionId } from "../revisions/repo.js";
 import { getRevisionView } from "../revisions/view.js";
+import { projectMarker } from "../storage/arrange.js";
 import { projectRows } from "../storage/backup-export.js";
 import { projectTables } from "../storage/backup-format.js";
 import { projectDir } from "../storage/layout.js";
@@ -34,7 +35,11 @@ export function copyProject(deps, sourceId, title) {
     const at = deps.clock.now().toISOString();
     try {
         for (const file of listFiles(source)) {
-            const to = join(target, remap(file));
+            if (file === projectMarker)
+                continue;
+            // The copy is a new project, laid out by its stored paths until it is arranged.
+            const stored = deps.paths.places?.storedAt(sourceId, file) ?? file;
+            const to = join(target, remap(stored));
             mkdirSync(dirname(to), { recursive: true, mode: 0o700 });
             copyFileSync(join(source, file), to);
         }

package/dist/slices/storage/arrange.js

@@ -0,0 +1,456 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, statSync, writeFileSync, } from "node:fs";
+import { basename, dirname, extname, join } from "node:path";
+import { pickedShortsOf } from "../shorts/clips.js";
+import { backupsFolderName, projectDir, renderCacheFolder } from "./layout.js";
+// The file in each project folder that says which project it is, for when the database and
+// the folders disagree (a restored database, a folder renamed by hand). Reconcile keeps it.
+export const projectMarker = ".slopify-project";
+// What makes a project's arrangement current: its title, head version and files. A project
+// whose key is unchanged since it was last arranged is left alone.
+export function arrangeKeys(db) {
+    const keys = new Map();
+    for (const row of db
+        .prepare(`SELECT p.id, p.title, h.revision_id,
+        (SELECT count(*)||':'||COALESCE(max(a.id),'') FROM project_assets a WHERE a.project_id=p.id) AS assets,
+        (SELECT count(*)||':'||COALESCE(max(o.id),'') FROM outputs o WHERE o.project_id=p.id) AS legacy,
+        (SELECT count(*)||':'||COALESCE(max(r.id),'') FROM revision_outputs r WHERE r.project_id=p.id AND r.selected=1 AND r.revision_id=h.revision_id) AS current
+       FROM projects p LEFT JOIN project_heads h ON h.project_id=p.id`)
+        .all())
+        keys.set(String(row.id), [row.title, row.revision_id, row.assets, row.legacy, row.current].map(String).join("|"));
+    return keys;
+}
+// Whether anything of the project runs or may start: its files stay where they are until then.
+export function projectSettled(db, projectId) {
+    const busy = db
+        .prepare(`SELECT 1 FROM revision_work WHERE project_id=? AND (state='running' OR (state='pending' AND dispatch_state!='held'))
+       UNION ALL SELECT 1 FROM stages WHERE project_id=? AND state='running'
+       UNION ALL SELECT 1 FROM project_trash WHERE project_id=? LIMIT 1`)
+        .get(projectId, projectId, projectId);
+    return busy === undefined;
+}
+export function arrangeProject(deps, projectId) {
+    const { db, paths, places } = deps;
+    if (!projectSettled(db, projectId))
+        return { folder: places.folderOf(projectId), moved: 0, skipped: "busy" };
+    const project = db.prepare("SELECT title FROM projects WHERE id=?").get(projectId);
+    if (project === undefined)
+        return { folder: undefined, moved: 0, skipped: "missing" };
+    const current = projectDir(paths, projectId);
+    if (!existsSync(current))
+        return { folder: undefined, moved: 0, skipped: "no folder" };
+    // 1. The folder, named after the title.
+    const have = places.folderOf(projectId) ?? projectId;
+    const want = folderName(String(project.title), (name) => taken(db, paths, projectId, have, name));
+    if (want !== have && want.toLowerCase() !== have.toLowerCase()) {
+        places.moves.folder(projectId, want, places.folderOf(projectId));
+        try {
+            renameSync(current, join(paths.projects, want));
+            places.moves.folderDone(projectId);
+        }
+        catch {
+            places.moves.folderUndone(projectId);
+            return { folder: have, moved: 0, skipped: "folder in use" };
+        }
+    }
+    else if (places.folderOf(projectId) === undefined) {
+        // Already readable (or the same name): still recorded, so cleanup knows it is ours.
+        places.moves.folder(projectId, have, undefined);
+        places.moves.folderDone(projectId);
+    }
+    const root = projectDir(paths, projectId);
+    // 2. Each file to its place. Files leaving for History go first, so the new version takes
+    // the names they free ("video.mp4", not "video (2).mp4").
+    const desired = [...desiredPlaces(db, projectId)].toSorted(([, a], [, b]) => Number(!a.startsWith("History/")) - Number(!b.startsWith("History/")));
+    const placed = places.placesOf(projectId);
+    let moved = 0;
+    for (const [path, base] of desired) {
+        const at = placed.get(path) ?? path;
+        if (sameBase(at, base) || !existsSync(join(root, at)))
+            continue;
+        const to = freeName(base, (name) => existsSync(join(root, name)));
+        places.moves.file(projectId, path, to, placed.get(path));
+        try {
+            mkdirSync(dirname(join(root, to)), { recursive: true });
+            renameSync(join(root, at), join(root, to));
+            places.moves.fileDone(projectId, path);
+            moved += 1;
+        }
+        catch {
+            // In use (a player or download on Windows): it stays and is tried again next time.
+            places.moves.fileUndone(projectId, path);
+        }
+    }
+    removeEmptyFolders(root);
+    writeMarker(root, projectId, places.placesOf(projectId));
+    return { folder: places.folderOf(projectId), moved, skipped: undefined };
+}
+// Every project whose title, version or files changed since it was last arranged.
+// Stops once `budgetMs` has passed, so a pass on the server's thread stays short; the next
+// pass carries on where it stopped.
+export function arrangeChanged(deps, budgetMs = Number.POSITIVE_INFINITY) {
+    const started = performance.now();
+    const done = [];
+    for (const [projectId, key] of arrangeKeys(deps.db)) {
+        if (performance.now() - started > budgetMs)
+            break;
+        if (deps.places.moves.arrangedKey(projectId) === key)
+            continue;
+        const result = arrangeProject(deps, projectId);
+        if (result.skipped === undefined) {
+            deps.places.moves.arranged(projectId, key);
+            done.push(projectId);
+        }
+    }
+    return done;
+}
+// ----- names -------------------------------------------------------------------------------
+const reserved = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])$/iu;
+// A folder name every system accepts, from the project's title: "Lolth | D&D Lore To Sleep
+// To" becomes "Lolth - D&D Lore To Sleep To".
+export function folderName(title, isTaken) {
+    let name = title
+        .replace(/\s*[|/\\:]\s*/gu, " - ")
+        .replace(/[*?"<>\p{Cc}]/gu, "")
+        .replace(/\s+/gu, " ")
+        .trim()
+        .replace(/[. ]+$/u, "");
+    if (name.length > 90)
+        name = name.slice(0, 90).replace(/[. ]+$/u, "");
+    if (name === "" || name.startsWith("."))
+        name = `Project ${name.replace(/^\.+/u, "")}`.trim();
+    if (reserved.test(name) || name.toLowerCase() === backupsFolderName.toLowerCase())
+        name = `${name} (project)`;
+    return freeName(name, isTaken);
+}
+function taken(db, paths, projectId, own, name) {
+    if (name.toLowerCase() === own.toLowerCase())
+        return false;
+    if (name.toLowerCase() === renderCacheFolder)
+        return true;
+    const row = db
+        .prepare("SELECT 1 FROM project_folders WHERE folder=? COLLATE NOCASE AND project_id!=?")
+        .get(name, projectId);
+    return row !== undefined || existsSync(join(paths.projects, name)) || isId(db, name);
+}
+function isId(db, name) {
+    return db.prepare("SELECT 1 FROM projects WHERE id=?").get(name) !== undefined;
+}
+// "video.mp4", then "video (2).mp4", "video (3).mp4"…
+function freeName(name, isTaken) {
+    if (!isTaken(name))
+        return name;
+    const extension = name.includes("/") ? extname(basename(name)) : extname(name);
+    const stem = extension === "" ? name : name.slice(0, -extension.length);
+    for (let n = 2;; n++) {
+        const next = `${stem} (${String(n)})${extension}`;
+        if (!isTaken(next))
+            return next;
+    }
+}
+function sameBase(at, base) {
+    if (at.toLowerCase() === base.toLowerCase())
+        return true;
+    const extension = extname(base);
+    const stem = extension === "" ? base : base.slice(0, -extension.length);
+    const pattern = new RegExp(`^${literal(stem)} \\([0-9]+\\)${literal(extension)}$`, "iu");
+    return pattern.test(at);
+}
+function literal(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+function clean(text) {
+    return text
+        .replace(/[|/\\:*?"<>\p{Cc}]/gu, " ")
+        .replace(/\s+/gu, " ")
+        .trim()
+        .replace(/[. ]+$/u, "")
+        .slice(0, 80);
+}
+const pad = (n, width = 3) => String(n).padStart(width, "0");
+// Stored path → its place (before any " (2)" for a clash).
+export function desiredPlaces(db, projectId) {
+    const head = db
+        .prepare("SELECT revision_id FROM project_heads WHERE project_id=?")
+        .get(projectId);
+    const headId = head === undefined ? undefined : String(head.revision_id);
+    const content = headId === undefined
+        ? undefined
+        : db.prepare("SELECT content FROM project_revisions WHERE id=?").get(headId);
+    const order = imageOrder(content?.content);
+    const titles = shortTitles(db, headId);
+    const references = new Map();
+    const add = (reference) => {
+        const old = references.get(reference.path);
+        // The current version's use names a file; otherwise its latest use.
+        if (old === undefined ||
+            (reference.current && !old.current) ||
+            (reference.current === old.current && reference.createdAt > old.createdAt))
+            references.set(reference.path, reference);
+    };
+    for (const row of db
+        .prepare(`SELECT a.path, o.slot, o.descriptor, o.created_at, (o.revision_id=? AND o.selected=1) AS current
+       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=?`)
+        .all(headId ?? null, projectId)) {
+        const descriptor = parse(row.descriptor);
+        const meta = descriptor?.meta;
+        add({
+            path: String(row.path),
+            role: typeof descriptor?.role === "string" ? descriptor.role : "other",
+            slot: String(row.slot),
+            index: undefined,
+            short: typeof meta?.short === "number" ? meta.short : undefined,
+            createdAt: String(row.created_at),
+            current: row.current === 1,
+        });
+    }
+    for (const row of db
+        .prepare(`SELECT a.path, p.piece_key, p.descriptor, p.created_at, (p.revision_id=? AND p.selected=1) AS current
+       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=?`)
+        .all(headId ?? null, projectId)) {
+        const descriptor = parse(row.descriptor);
+        add({
+            path: String(row.path),
+            role: `piece:${typeof descriptor?.kind === "string" ? descriptor.kind : "other"}`,
+            slot: String(row.piece_key),
+            index: typeof descriptor?.idx === "number" ? descriptor.idx : undefined,
+            short: undefined,
+            createdAt: String(row.created_at),
+            current: row.current === 1,
+        });
+    }
+    // A project from before versions: its outputs rows are its files, all current.
+    for (const row of db
+        .prepare("SELECT path, role, created_at FROM outputs WHERE project_id=?")
+        .all(projectId))
+        add({
+            path: String(row.path),
+            role: String(row.role),
+            slot: String(row.role),
+            index: undefined,
+            short: undefined,
+            createdAt: String(row.created_at),
+            current: headId === undefined,
+        });
+    const out = new Map();
+    for (const reference of references.values()) {
+        const place = placeFor(reference, order, titles);
+        out.set(reference.path, reference.current
+            ? place
+            : `History/${day(reference.createdAt)}/${place.replace(/^Upload\//u, "")}`);
+    }
+    return out;
+}
+function placeFor(reference, order, titles) {
+    const file = basename(reference.path);
+    const extension = extname(file);
+    const slot = reference.slot;
+    const segment = /^(?:audio|level|narration:files):(body|intro|outro)/u.exec(slot)?.[1];
+    switch (reference.role) {
+        case "video":
+            return `Upload/video${extension}`;
+        case "thumbnail": {
+            const n = /^thumbnail:image:([0-9]+)$/u.exec(slot)?.[1];
+            return `Upload/thumbnail${n === undefined ? "" : ` ${n}`}${extension}`;
+        }
+        case "subtitles_srt":
+        case "subtitles_vtt":
+            return `Upload/subtitles${extension}`;
+        case "youtube_description":
+            return "Upload/description.txt";
+        case "youtube_tags":
+            return "Upload/tags.txt";
+        case "youtube_titles":
+            return "Upload/titles.txt";
+        case "youtube_pinned_comment":
+            return "Upload/pinned comment.txt";
+        case "document_pdf":
+            return `Upload/document${extension}`;
+        case "article_md":
+            return `Upload/article${extension}`;
+        case "audio_export":
+            return `Upload/audio${extension}`;
+        case "short_video": {
+            const n = reference.short ?? Number(/^shorts:([0-9]+):/u.exec(slot)?.[1] ?? Number.NaN);
+            if (Number.isNaN(n))
+                return `Upload/Shorts/${file}`;
+            const title = titles.get(n);
+            return `Upload/Shorts/${String(n)}${title === undefined || title === "" ? "" : ` - ${clean(title)}`}${extension}`;
+        }
+        case "image":
+        case "animated_image": {
+            const key = /^image:(.+)$/u.exec(slot)?.[1];
+            const at = key === undefined ? undefined : order.get(key);
+            return at === undefined
+                ? `Working/Images/${file}`
+                : `Working/Images/${pad(at + 1)}${extension}`;
+        }
+        case "short_image": {
+            const match = /^shorts:([0-9]+):image:([0-9]+)$/u.exec(slot);
+            return match === null
+                ? `Working/Shorts/${file}`
+                : `Working/Shorts/Short ${match[1]}/image ${match[2]}${extension}`;
+        }
+        case "figure_card":
+            return `Working/Cards/${file}`;
+        case "audio_body":
+        case "audio_intro":
+        case "audio_outro":
+            return `Working/Narration/${segment ?? reference.role.slice(6)}${extension}`;
+        case "audio_levelled":
+            return `Working/Narration/${segment ?? "narration"} levelled${extension}`;
+        case "narration_txt":
+            return `Working/Narration/${segment ?? "narration"} text${extension}`;
+        case "tts_script":
+            return `Working/Narration/${segment ?? "narration"} voice script${extension}`;
+        case "piece:chunk":
+        case "piece:segment":
+            return `Working/Narration/Chunks/${segment ?? "body"} ${pad((reference.index ?? 0) + 1)}${extension}`;
+        case "notes":
+            return `Working/Research/notes${extension}`;
+        case "piece:chapter": {
+            const n = /:([0-9]+)$/u.exec(slot)?.[1];
+            return `Working/Research/chapter ${n ?? file}${n === undefined ? "" : extension}`;
+        }
+        case "article_txt":
+        case "sources":
+        case "glossary":
+            return `Working/Article/${reference.role === "article_txt" ? "article" : reference.role}${extension}`;
+        case "piece:article_written":
+            // The joined narration's parts (audio:body:concat), or an article's written parts.
+            return segment === undefined
+                ? `Working/Article/Parts/${file}`
+                : `Working/Narration/Joined/${segment} ${file}`;
+        case "instructions": {
+            const stage = /^([a-z]+):instructions$/u.exec(slot)?.[1];
+            return `Working/Instructions/${stage ?? basename(file, extension)}${extension}`;
+        }
+        case "subtitle_words":
+        case "subtitle_ass":
+        case "subtitle_font":
+            return `Working/Subtitles/${file}`;
+        case "render_params":
+        case "shorts":
+            return `Working/Render/${file}`;
+        default:
+            return `Working/Other/${file}`;
+    }
+}
+function imageOrder(content) {
+    const parsed = parse(content);
+    const order = Array.isArray(parsed?.imageOrder) ? parsed.imageOrder : [];
+    return new Map(order.map((key, at) => [String(key), at]));
+}
+function shortTitles(db, headId) {
+    if (headId === undefined)
+        return new Map();
+    const row = db
+        .prepare("SELECT descriptor FROM revision_pieces WHERE revision_id=? AND piece_key='shorts:pick' AND selected=1")
+        .get(headId);
+    const payload = parse(row?.descriptor)?.payload;
+    const picked = pickedShortsOf(typeof payload === "string" ? payload : undefined);
+    return new Map((picked?.shorts ?? []).map((short) => [short.number, short.title]));
+}
+function day(createdAt) {
+    const at = new Date(createdAt);
+    if (Number.isNaN(at.getTime()))
+        return "undated";
+    return `${String(at.getFullYear())}-${pad(at.getMonth() + 1, 2)}-${pad(at.getDate(), 2)}`;
+}
+function parse(value) {
+    if (typeof value !== "string")
+        return undefined;
+    try {
+        const parsed = JSON.parse(value);
+        return typeof parsed === "object" && parsed !== null
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// ----- the folder itself ---------------------------------------------------------------------
+// The marker names the project and lists where each of its files went, so a folder can be
+// matched back to its project and its files found again even by a database restored from
+// before it was arranged (`adoptMarked`). Written whole, then renamed into place.
+function writeMarker(root, projectId, files) {
+    const path = join(root, projectMarker);
+    const part = `${path}.part`;
+    writeFileSync(part, `${JSON.stringify({
+        project: projectId,
+        note: "Slopify keeps this file to know which project this folder holds and where its files are. Leave it here.",
+        files: Object.fromEntries([...files].toSorted(([a], [b]) => a.localeCompare(b))),
+    }, null, 2)}\n`, { mode: 0o600 });
+    renameSync(part, path);
+}
+function readMarker(dir) {
+    const path = join(dir, projectMarker);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const parsed = parse(readFileSync(path, "utf8"));
+        if (typeof parsed?.project !== "string")
+            return undefined;
+        const files = {};
+        if (typeof parsed.files === "object" && parsed.files !== null)
+            for (const [stored, place] of Object.entries(parsed.files))
+                if (typeof place === "string")
+                    files[stored] = place;
+        return { project: parsed.project, files };
+    }
+    catch {
+        return undefined;
+    }
+}
+// The project a folder's marker names, if it has one.
+export function markerProject(dir) {
+    return readMarker(dir)?.project;
+}
+// Records a marked folder, and the places of its files that are still there, for a project
+// the database has no folder for.
+export function adoptMarked(db, paths, projectId, folder, dir) {
+    const places = paths.places;
+    if (places === undefined || !("moves" in places))
+        return;
+    const moves = places.moves;
+    if (db.prepare("SELECT 1 FROM project_folders WHERE folder=? COLLATE NOCASE").get(folder))
+        return;
+    moves.folder(projectId, folder, undefined);
+    moves.folderDone(projectId);
+    for (const [stored, place] of Object.entries(readMarker(dir)?.files ?? {})) {
+        if (places.placeOf(projectId, stored) !== undefined)
+            continue;
+        if (!existsSync(join(dir, place)))
+            continue;
+        moves.file(projectId, stored, place, undefined);
+        moves.fileDone(projectId, stored);
+    }
+}
+// The empty folders moves leave behind (assets/<id>/), deepest first. The folder itself stays.
+function removeEmptyFolders(root) {
+    const walk = (dir) => {
+        let empty = true;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (walk(path)) {
+                    try {
+                        rmdirSync(path);
+                    }
+                    catch {
+                        empty = false;
+                    }
+                }
+                else
+                    empty = false;
+            }
+            else
+                empty = false;
+        }
+        return empty;
+    };
+    if (existsSync(root) && statSync(root).isDirectory())
+        walk(root);
+}

package/dist/slices/storage/backup-export.js

@@ -3,8 +3,9 @@ import { constants, lstatSync, readdirSync } from "node:fs";
 import { open } from "node:fs/promises";
 import { join } from "node:path";
 import { transact } from "../../kernel/db/tx.js";
+import { projectMarker } from "./arrange.js";
 import { backupFormat, backupSchemaVersion, checksumsMember, fontMember, imageMember, libraryMember, manifestMember, projectFileMember, projectMember, projectTables, safeRelativePath, stagedMember, usageMember, } from "./backup-format.js";
-import { projectDir, stagingPath } from "./layout.js";
+import { outputPath, projectDir, stagingPath } from "./layout.js";
 import { exportableSettings, installedUploadedFontFiles } from "./portable.js";
 import { tarEnd, tarHeader, tarMemberBytes, tarPadding } from "./tar.js";
 // A project that is being made has half-written files and rows that say "running"; copied
@@ -70,7 +71,7 @@ export function planBackup(deps) {
             files.push({
                 name: projectFileMember(project.part.id, file.path),
                 kind: "file",
-                path: join(projectDir(deps.paths, project.part.id), file.path),
+                path: outputPath(deps.paths, project.part.id, file.path),
                 size: file.bytes,
             });
     for (const font of snapshot.library.part.fonts)
@@ -217,7 +218,13 @@ function projectSnapshot(deps, id, title) {
         if (rows.length > 0)
             tables[table] = rows;
     }
-    return { title, part: { id, tables, files: projectFiles(projectDir(deps.paths, id)) } };
+    // Files go in by their stored paths, as every version before readable folders wrote them:
+    // a moved file (`places.ts`) is named by the path its rows hold, and the import puts it
+    // there for its own arranging to move. The marker names this install's places; it stays.
+    const files = projectFiles(projectDir(deps.paths, id))
+        .filter((file) => file.path !== projectMarker)
+        .map((file) => ({ ...file, path: deps.paths.places?.storedAt(id, file.path) ?? file.path }));
+    return { title, part: { id, tables, files } };
 }
 // Every plain file under the project's folder, symlinks and all else left out. Not only the
 // rows' files: audio chunks a retry would reuse and the files a revision history keeps are

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

@@ -31,6 +31,9 @@ export function deleteProject(deps, projectId) {
     // ON DELETE CASCADE on the project, and the connection runs with foreign keys on
     // (kernel/db/index.ts). A deleted project leaves no files and no rows.
     deps.db.prepare("DELETE FROM projects WHERE id = ?").run(projectId);
+    const places = deps.paths.places;
+    if (places !== undefined && "forget" in places)
+        places.forget(projectId);
     return { ok: true };
 }
 function messageOf(error) {

package/dist/slices/storage/layout.js

@@ -1,6 +1,7 @@
 import { extname, isAbsolute, relative, resolve } from "node:path";
+// A project's folder: its readable name once it has one (`places.ts`), its id until then.
 export function projectDir(paths, projectId) {
-    return contained(paths.projects, projectId);
+    return contained(paths.projects, paths.places?.folderOf(projectId) ?? projectId);
 }
 // The clips of each project's last render (`slices/video/clip-cache.ts`). Hidden, so
 // reconcile, backups and the user's file browser leave it alone; disposable, so moving the
@@ -9,8 +10,9 @@ export const renderCacheFolder = ".render-cache";
 export function renderCacheDir(paths, projectId) {
     return contained(paths.projects, `${renderCacheFolder}/${projectId}`);
 }
+// A stored path on disk: where it was moved to (`places.ts`), or the stored path itself.
 export function outputPath(paths, projectId, relativePath) {
-    return contained(projectDir(paths, projectId), relativePath);
+    return contained(projectDir(paths, projectId), paths.places?.placeOf(projectId, relativePath) ?? relativePath);
 }
 // Scheduled backups (slices/backups) land in paths.backups unless the user picks another
 // folder. Installs from before 3.0 keep it inside the projects root, since that is the one

package/dist/slices/storage/places.js

@@ -0,0 +1,171 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+export function createPlaces(db) {
+    const folders = new Map();
+    const files = new Map();
+    const stored = new Map();
+    for (const row of db.prepare("SELECT * FROM project_folders").all())
+        folders.set(String(row.project_id), {
+            folder: String(row.folder),
+            previous: row.previous === null ? undefined : String(row.previous),
+            state: row.state === "moving" ? "moving" : "placed",
+            arranged: row.arranged === null ? undefined : String(row.arranged),
+        });
+    for (const row of db.prepare("SELECT * FROM file_places").all())
+        setFile(String(row.project_id), String(row.path), {
+            place: String(row.place),
+            previous: row.previous === null ? undefined : String(row.previous),
+            state: row.state === "moving" ? "moving" : "placed",
+        });
+    function setFile(projectId, path, place) {
+        let own = files.get(projectId);
+        let back = stored.get(projectId);
+        const old = own?.get(path);
+        if (old !== undefined)
+            back?.delete(old.place.toLowerCase());
+        if (place === undefined) {
+            own?.delete(path);
+            return;
+        }
+        if (own === undefined) {
+            own = new Map();
+            files.set(projectId, own);
+        }
+        if (back === undefined) {
+            back = new Map();
+            stored.set(projectId, back);
+        }
+        own.set(path, place);
+        back.set(place.place.toLowerCase(), path);
+    }
+    const moves = {
+        folder(projectId, folder, previous) {
+            db.prepare(`INSERT INTO project_folders(project_id,folder,previous,state) VALUES (?,?,?,'moving')
+         ON CONFLICT(project_id) DO UPDATE SET folder=excluded.folder,previous=excluded.previous,state='moving'`).run(projectId, folder, previous ?? null);
+            folders.set(projectId, {
+                folder,
+                previous,
+                state: "moving",
+                arranged: folders.get(projectId)?.arranged,
+            });
+        },
+        folderDone(projectId) {
+            db.prepare("UPDATE project_folders SET state='placed',previous=NULL WHERE project_id=?").run(projectId);
+            const row = folders.get(projectId);
+            if (row !== undefined)
+                folders.set(projectId, { ...row, state: "placed", previous: undefined });
+        },
+        folderUndone(projectId) {
+            const row = folders.get(projectId);
+            if (row?.previous === undefined) {
+                db.prepare("DELETE FROM project_folders WHERE project_id=?").run(projectId);
+                folders.delete(projectId);
+                return;
+            }
+            db.prepare("UPDATE project_folders SET folder=previous,previous=NULL,state='placed' WHERE project_id=?").run(projectId);
+            folders.set(projectId, {
+                ...row,
+                folder: row.previous,
+                previous: undefined,
+                state: "placed",
+            });
+        },
+        file(projectId, path, place, previous) {
+            db.prepare(`INSERT INTO file_places(project_id,path,place,previous,state) VALUES (?,?,?,?,'moving')
+         ON CONFLICT(project_id,path) DO UPDATE SET place=excluded.place,previous=excluded.previous,state='moving'`).run(projectId, path, place, previous ?? null);
+            setFile(projectId, path, { place, previous, state: "moving" });
+        },
+        fileDone(projectId, path) {
+            db.prepare("UPDATE file_places SET state='placed',previous=NULL WHERE project_id=? AND path=?").run(projectId, path);
+            const row = files.get(projectId)?.get(path);
+            if (row !== undefined)
+                setFile(projectId, path, { ...row, state: "placed", previous: undefined });
+        },
+        fileUndone(projectId, path) {
+            const row = files.get(projectId)?.get(path);
+            if (row?.previous === undefined || row.previous === path) {
+                db.prepare("DELETE FROM file_places WHERE project_id=? AND path=?").run(projectId, path);
+                setFile(projectId, path, undefined);
+                return;
+            }
+            db.prepare("UPDATE file_places SET place=previous,previous=NULL,state='placed' WHERE project_id=? AND path=?").run(projectId, path);
+            setFile(projectId, path, { place: row.previous, previous: undefined, state: "placed" });
+        },
+        arranged(projectId, key) {
+            db.prepare("UPDATE project_folders SET arranged=? WHERE project_id=?").run(key, projectId);
+            const row = folders.get(projectId);
+            if (row !== undefined)
+                folders.set(projectId, { ...row, arranged: key });
+        },
+        arrangedKey(projectId) {
+            return folders.get(projectId)?.arranged;
+        },
+    };
+    return {
+        // A move in flight still answers with where the file is until it is done.
+        folderOf(projectId) {
+            const row = folders.get(projectId);
+            if (row === undefined)
+                return undefined;
+            return row.state === "moving" ? row.previous : row.folder;
+        },
+        placeOf(projectId, path) {
+            const row = files.get(projectId)?.get(path);
+            if (row === undefined)
+                return undefined;
+            return row.state === "moving" ? row.previous : row.place;
+        },
+        storedAt(projectId, place) {
+            return stored.get(projectId)?.get(place.toLowerCase());
+        },
+        placesOf(projectId) {
+            const own = files.get(projectId);
+            const out = new Map();
+            for (const [path, row] of own ?? [])
+                if (row.state === "placed")
+                    out.set(path, row.place);
+            return out;
+        },
+        forget(projectId) {
+            folders.delete(projectId);
+            files.delete(projectId);
+            stored.delete(projectId);
+        },
+        moves,
+    };
+}
+// Settles moves a crash interrupted, from what is on disk: a move whose target exists and
+// whose source doesn't happened; any other is taken back. Run before anything reads a file.
+export function recoverPlaces(db, paths) {
+    let settled = 0;
+    for (const row of db.prepare("SELECT * FROM project_folders WHERE state='moving'").all()) {
+        const id = String(row.project_id);
+        const target = join(paths.projects, String(row.folder));
+        const source = join(paths.projects, row.previous === null ? id : String(row.previous));
+        if (existsSync(target) && !existsSync(source))
+            db.prepare("UPDATE project_folders SET state='placed',previous=NULL WHERE project_id=?").run(id);
+        else if (row.previous === null)
+            db.prepare("DELETE FROM project_folders WHERE project_id=?").run(id);
+        else
+            db.prepare("UPDATE project_folders SET folder=previous,previous=NULL,state='placed' WHERE project_id=?").run(id);
+        settled += 1;
+    }
+    const folderOf = new Map(db
+        .prepare("SELECT project_id,folder FROM project_folders")
+        .all()
+        .map((row) => [String(row.project_id), String(row.folder)]));
+    for (const row of db.prepare("SELECT * FROM file_places WHERE state='moving'").all()) {
+        const id = String(row.project_id);
+        const root = join(paths.projects, folderOf.get(id) ?? id);
+        const path = String(row.path);
+        const previous = row.previous === null ? path : String(row.previous);
+        if (existsSync(join(root, String(row.place))) && !existsSync(join(root, previous)))
+            db.prepare("UPDATE file_places SET state='placed',previous=NULL WHERE project_id=? AND path=?").run(id, path);
+        else if (row.previous === null || previous === path)
+            db.prepare("DELETE FROM file_places WHERE project_id=? AND path=?").run(id, path);
+        else
+            db.prepare("UPDATE file_places SET place=previous,previous=NULL,state='placed' WHERE project_id=? AND path=?").run(id, path);
+        settled += 1;
+    }
+    return settled;
+}

package/dist/slices/storage/reconcile.js

@@ -1,10 +1,17 @@
 import { readdirSync, rmSync, statSync, unlinkSync } from "node:fs";
 import { isAbsolute, join, relative, sep } from "node:path";
+import { adoptMarked, markerProject, projectMarker } from "./arrange.js";
 import { backupsFolderName, outputPath, stagingPath } from "./layout.js";
 import { stagedFiles as stagedRows } from "./repo.js";
 import { stagedFileReferenced } from "./staging-refs.js";
 export function reconcileStorage(db, paths) {
     const projects = idsOf(db, "SELECT id FROM projects", "id");
+    const folders = new Map();
+    for (const project of projects) {
+        const folder = paths.places?.folderOf(project);
+        if (folder !== undefined)
+            folders.set(folder.toLowerCase(), project);
+    }
     const kept = new Set();
     for (const row of db
         .prepare("SELECT project_id, path FROM outputs UNION SELECT project_id, path FROM project_assets")
@@ -13,7 +20,7 @@ export function reconcileStorage(db, paths) {
         const path = row.path;
         if (typeof projectId === "string" && typeof path === "string") {
             outputPath(paths, projectId, path);
-            kept.add(`${projectId}/${slashed(path)}`);
+            kept.add(`${projectId}/${slashed(placed(paths, projectId, path))}`);
         }
     }
     // A stage's unfinished work is on the project too: the audio chunks a previous run
@@ -27,7 +34,7 @@ export function reconcileStorage(db, paths) {
         const projectId = row.project_id;
         const file = pieceFile(row.payload);
         if (typeof projectId === "string" && file !== undefined) {
-            kept.add(`${projectId}/${slashed(file)}`);
+            kept.add(`${projectId}/${slashed(placed(paths, projectId, file))}`);
         }
     }
     let orphanFiles = 0;
@@ -50,15 +57,25 @@ export function reconcileStorage(db, paths) {
             orphanFiles += 1;
             continue;
         }
-        if (!projects.has(entry.name)) {
+        // A folder is a project's by its readable name (`places.ts`), its id, or the marker
+        // arranging left in it (`arrange.ts`). A deleted project's folder goes; a folder that is
+        // none of these is the person's own and stays.
+        const owner = folderOwner(db, paths, projects, folders, entry.name, path);
+        if (owner === "foreign")
+            continue;
+        if (owner === "deleted") {
             orphanFiles += filesUnder(path).length;
             rmSync(path, { recursive: true, force: true });
             continue;
         }
         for (const file of filesUnder(path)) {
-            if (kept.has(`${entry.name}/${slashed(file)}`)) {
+            const name = slashed(file);
+            if (kept.has(`${owner}/${name}`))
+                continue;
+            // The marker, and anything in the folders a person browses: a note or a file dropped
+            // next to the video is theirs. Only Slopify's own leftovers elsewhere are removed.
+            if (name === projectMarker || arrangedArea.test(name))
                 continue;
-            }
             unlinkSync(join(path, file));
             orphanFiles += 1;
         }
@@ -108,6 +125,38 @@ export function pieceFile(payload) {
     const file = parsed.file;
     return typeof file === "string" && file !== "" ? file : undefined;
 }
+// Where a stored path is on disk now, relative to its project folder.
+function placed(paths, projectId, path) {
+    return paths.places?.placeOf(projectId, path) ?? path;
+}
+// The folders arranging makes (`arrange.ts`): a file in them that no record names is the
+// person's, not a leftover.
+const arrangedArea = /^(Upload|Working|History)\//u;
+const ulid = /^[0-9A-HJKMNP-TV-Z]{26}$/u;
+// Whose a folder in the projects root is: a project's id, "deleted" (a project that no longer
+// exists: its id, or its marker's), or "foreign" (not Slopify's).
+function folderOwner(db, paths, projects, folders, name, path) {
+    const named = folders.get(name.toLowerCase());
+    if (named !== undefined)
+        return named;
+    const marked = markerProject(path);
+    if (marked !== undefined) {
+        if (!projects.has(marked))
+            return "deleted";
+        // The database lost this folder's record (restored from before it was arranged): its
+        // marker says whose it is, and where its files went.
+        if (paths.places !== undefined && paths.places.folderOf(marked) === undefined) {
+            adoptMarked(db, paths, marked, name, path);
+            return marked;
+        }
+        return paths.places?.folderOf(marked)?.toLowerCase() === name.toLowerCase()
+            ? marked
+            : "foreign";
+    }
+    if (projects.has(name))
+        return paths.places?.folderOf(name) === undefined ? name : "foreign";
+    return ulid.test(name) ? "deleted" : "foreign";
+}
 function idsOf(db, sql, column) {
     const ids = new Set();
     for (const row of db.prepare(sql).all()) {

package/dist/slices/storage/trim.js

@@ -2,7 +2,7 @@ import { existsSync, readdirSync, statSync, unlinkSync } from "node:fs";
 import { join, relative, sep } from "node:path";
 import { derive } from "../../kernel/runner/graph.js";
 import { projectExists, projectPaused, stagesOf } from "../admission/repo.js";
-import { backupsFolderName, projectDir } from "./layout.js";
+import { backupsFolderName, outputPath, projectDir } from "./layout.js";
 import { pieceFile } from "./reconcile.js";
 // Keep outputs only: a finished project drops the working files it was made from (images,
 // narration parts, subtitle timing, render settings) and keeps what gets published. Two
@@ -68,7 +68,7 @@ export function keepOutputsOnly(deps, projectId) {
         const bytes = files.get(path);
         if (bytes === undefined)
             continue;
-        unlinkSync(join(projectDir(deps.paths, projectId), path));
+        unlinkSync(outputPath(deps.paths, projectId, path));
         count += 1;
         bytesFreed += bytes;
     }
@@ -85,7 +85,7 @@ function finished(deps, projectId) {
         .prepare("SELECT 1 FROM revision_work WHERE project_id=? AND (state='running' OR (state='pending' AND dispatch_state='allowed')) LIMIT 1")
         .get(projectId) === undefined);
 }
-// Every file under the project folder, by project-relative path with forward slashes.
+// Every file under the project folder, by stored path with forward slashes.
 function filesOf(paths, projectId) {
     const files = new Map();
     if (projectId === backupsFolderName)
@@ -97,7 +97,9 @@ function filesOf(paths, projectId) {
         if (!entry.isFile())
             continue;
         const full = join(entry.parentPath, entry.name);
-        files.set(relative(root, full).split(sep).join("/"), statSync(full).size);
+        const place = relative(root, full).split(sep).join("/");
+        // Keyed by stored path: a file moved by arranging (`places.ts`) is found by where it is.
+        files.set(paths.places?.storedAt(projectId, place) ?? place, statSync(full).size);
     }
     return files;
 }

package/dist/tutorials/Where-Your-Files-Live.md

@@ -25,6 +25,24 @@ The terminal prints both places when Slopify starts (`Slopify data directory:` a
 
 The folder is created if it is missing.
 
+## Inside a project folder
+
+Each project has one folder in `Projects/`, named after its title (`Lolth | D&D Lore To Sleep To` becomes `Lolth - D&D Lore To Sleep To`). Inside it:
+
+| Folder | What is in it | Safe to delete? |
+| --- | --- | --- |
+| `Upload/` | The current version, ready to publish: `video.mp4`, `thumbnail.png` (and `thumbnail 2.png`…), `subtitles.srt` and `.vtt`, `description.txt`, `tags.txt`, `titles.txt`, `pinned comment.txt`, `document.pdf`, `article.md`, and `Shorts/1 - <title>.mp4`… | No: it is what you upload. |
+| `Working/` | What the current version was made from: `Images/`, `Narration/` (each chunk, the joined and levelled narration), `Research/`, `Article/`, `Subtitles/`, `Render/`, `Shorts/` (each short's images). | Only to free space on a finished video: changing that project later makes these again, which takes time and provider credits. **Keep outputs only** does it for you. |
+| `History/<date>/` | Files of older versions, by the day they were made (an earlier render, the narration before a voice change). | Yes. Delete a day's folder, or all of `History/`, to free its space. Going back to that version in History makes its files again. |
+
+A hidden `.slopify-project` file tells Slopify which project the folder holds and where its files went. Leave it there.
+
+Slopify sorts a project's files into these folders when nothing of it is running, so a project shows them a little after it finishes (or after an edit). While a run is going, its new files sit in `assets/` until then. Renaming a project renames its folder the same way.
+
+Files you add yourself to `Upload/`, `Working/` or `History/` (a note, a reworked thumbnail) are never removed by Slopify. A folder in `Projects/` that Slopify did not make is left alone.
+
+**After this change, don't go back to a Slopify older than 3.14:** older versions only know folders named by project id, and remove the readable ones when they start.
+
 ## New and existing installs
 
 Slopify decides once, the first time 3.0 starts, and remembers it:
@@ -126,7 +144,7 @@ A finished project's own page offers the same in its right rail: **Free space**
 
 ### Clear leftover files
 
-**Clear leftover files** deletes files in the projects folder that no project records any more, and uploaded files that no draft, template or project uses. Your projects, outputs and library are never touched. Slopify also does this each time it starts; use it after a crash or to free space now.
+**Clear leftover files** deletes files in the projects folder that no project records any more (never anything in a project's `Upload/`, `Working/` or `History/`, and never a folder Slopify did not make), and uploaded files that no draft, template or project uses. Your projects, outputs and library are never touched. Slopify also does this each time it starts; use it after a crash or to free space now.
 
 Cleanup only looks inside `Projects`. It leaves `Backups` alone (only Slopify's own `slopify-backup-*.tar` files there are ever pruned, by the backup rules), leaves hidden files such as `.DS_Store` and `desktop.ini`, never removes loose files in a `Projects` folder outside the data folder, and never touches `Exports` or anything else in your files folder.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gentbajko/slopify",
-  "version": "3.13.2",
+  "version": "3.14.1",
   "description": "Turn a prompt into a finished video, locally, with your own provider keys",
   "license": "Apache-2.0",
   "author": "Gent Bajko",