@gentbajko/slopify 0.1.0 → 0.2.0

package/dist/slices/storage/layout.js

@@ -8,7 +8,7 @@ export function outputPath(paths, projectId, relativePath) {
 export function stagingPath(paths, stagedFileId) {
     return contained(paths.staging, stagedFileId);
 }
-// Every asset of a project lives under its own folder (logic/14 §Q115); an id or a
+// Every asset of a project lives under its own folder; an id or a
 // stored path that resolves anywhere else is a bug in whatever produced it.
 function contained(root, path) {
     const target = resolve(root, path);
@@ -18,11 +18,10 @@ function contained(root, path) {
     }
     return target;
 }
-// logic/14 step 2 fixes the names inside a project folder, so a provided file is
-// stored under the name its role dictates and keeps only its extension. The stage is part
-// of the name for the one role more than one stage produces: research and the article each
-// store what they sent (logic/06 step 4, logic/07 step 4), and the project page offers
-// them per stage ("Show instructions", uiux/screens/08-project).
+// The names inside a project folder are fixed, so a provided file is stored under the name
+// its role dictates and keeps only its extension. The stage is part of the name for the one
+// role more than one stage produces: research and the article each store what they sent,
+// and the project page offers them per stage under "Show instructions".
 export function outputFileName(role, index, extension, stageKind) {
     switch (role) {
         case "notes":

package/dist/slices/storage/model.js

@@ -1,6 +1,6 @@
 export { stageKinds } from "../../kernel/pipeline.js";
 // The stages whose content arrives as a file. Research and article take pasted text
-// instead (logic/05 §Q37), and video is always generated (logic/01 step 5).
+// instead, and video is always generated.
 export const uploadableStageKinds = ["audio", "images", "thumbnail"];
 export const outputRoles = [
     "notes",

package/dist/slices/storage/reconcile.js

@@ -1,7 +1,7 @@
 import { readdirSync, rmSync, unlinkSync } from "node:fs";
 import { join, relative, sep } from "node:path";
 // Files the database does not know about, and staged uploads that never reached a
-// project, are removed at start (logic/05 §Q44, logic/14 step 5).
+// project, are removed at start.
 export function reconcileStorage(db, paths) {
     const projects = idsOf(db, "SELECT id FROM projects", "id");
     const kept = new Set();
@@ -12,12 +12,11 @@ export function reconcileStorage(db, paths) {
             kept.add(`${projectId}/${slashed(path)}`);
         }
     }
-    // A stage's unfinished work is on the project too: `logic/08` §Q66 keeps the audio
-    // chunks a previous run finished so a manual retry re-runs only the failed ones, and
-    // `logic/13` step 2 keeps them through a cancel. A chunk is not an output - the
-    // concatenated body is the project's only body audio (§Q65) - so the file it wrote is
-    // named by its `stage_pieces` payload instead, and that is as much of a record as an
-    // outputs row.
+    // A stage's unfinished work is on the project too: the audio chunks a previous run
+    // finished are kept so a manual retry re-runs only the failed ones, and a cancel keeps
+    // them as well. A chunk is not an output - the concatenated body is the project's only
+    // body audio - so the file it wrote is named by its `stage_pieces` payload instead, and
+    // that is as much of a record as an outputs row.
     for (const row of db
         .prepare("SELECT stages.project_id AS project_id, stage_pieces.payload AS payload FROM stage_pieces JOIN stages ON stages.id = stage_pieces.stage_id WHERE stage_pieces.payload IS NOT NULL")
         .all()) {

package/dist/slices/storage/repo.js

@@ -42,7 +42,7 @@ export function outputById(db, id) {
     const row = db.prepare("SELECT * FROM outputs WHERE id = ?").get(id);
     return row === undefined ? undefined : toOutput(outputRow.parse(row));
 }
-// `logic/12` §Q106: an action replaces an output rather than versioning it. The row goes
+// An action replaces an output rather than versioning it. The row goes
 // here; the file it names is the caller's to unlink once this has committed.
 export function deleteOutput(db, id) {
     db.prepare("DELETE FROM outputs WHERE id = ?").run(id);

package/dist/slices/storage/staging.js

@@ -37,13 +37,13 @@ export async function stageUpload(deps, input) {
         createdAt: deps.clock.now().toISOString(),
     };
     // The row exists before the first byte, so a process that dies mid-copy leaves a
-    // record reconcile collects rather than an untracked file (logic/05 §Q44).
+    // record reconcile collects rather than an untracked file.
     insertStagedFile(deps.db, file);
     let bytes = 0;
     let lastEmit = 0;
     const notify = (event) => {
         // Nothing about progress delivery may abort the write: a page that navigated away
-        // is not a reason to lose the upload it started (logic/05 §Q43).
+        // is not a reason to lose the upload it started.
         try {
             deps.emit(event);
         }
@@ -107,7 +107,7 @@ export function attachStagedFile(deps, input) {
     if (staged === undefined) {
         return { ok: false, reason: "unknown-staged-file" };
     }
-    // A run never starts with provided content that is still copying (logic/05 §Q44).
+    // A run never starts with provided content that is still copying.
     if (staged.state !== "staged") {
         return { ok: false, reason: "still-copying" };
     }
@@ -134,10 +134,9 @@ export function attachStagedFile(deps, input) {
         meta: input.role === "image" ? { index } : {},
         createdAt: deps.clock.now().toISOString(),
     };
-    // The file already moved. If this fails the file is under projects/ with no row,
-    // which is exactly what the boot reconcile collects.
-    // A savepoint rather than BEGIN, so startRun can attach several files inside the one
-    // transaction that creates the project.
+    // The file already moved. If this fails the file is under projects/ with no row, which is
+    // exactly what the boot reconcile collects. A savepoint rather than BEGIN, so startRun can
+    // attach several files inside the one transaction that creates the project.
     try {
         transact(deps.db, () => {
             insertOutput(deps.db, output);
@@ -164,14 +163,12 @@ export function dropStagedSource(deps, source) {
         deps.log.write("warn", "staging.source", { detail: `${source}: ${messageOf(error)}` });
     }
 }
-// logic/05 step 1: a stage set to Provide can carry pasted text instead of a file, and
-// the project holds it as an output like any other. Unlike an attached upload this needs
-// no two-phase dance: the text came in on the request, so a rollback loses nothing the
-// caller cannot write again, and the file left under a project id that was rolled back
-// is an orphan the boot reconcile removes.
-// ceiling: the paste is stored as typed. logic/05 §Q37 also asks for markdown syntax to
-// be stripped for the narration source; that reduction belongs to the narration slice
-// that reads this file, and lands with it.
+// A stage set to Provide can carry pasted text instead of a file, and the project holds it as
+// an output like any other. Unlike an attached upload this needs no two-phase dance: the text
+// came in on the request, so a rollback loses nothing the caller cannot write again, and the
+// file left under a project id that was rolled back is an orphan the boot reconcile removes.
+// ceiling: the paste is stored as typed. Markdown syntax still has to be stripped for the
+// narration source; that reduction belongs to the narration slice that reads this file.
 export function storeText(deps, input) {
     const name = outputFileName(input.role, 1, ".txt", input.stageKind);
     const target = outputPath(deps.paths, input.projectId, name);

package/dist/slices/telemetry/collector-client.js

@@ -1,4 +1,4 @@
-// 07-operations: the collector URL is built into the release and is not user
+// The collector URL is built into the release and is not user
 // configurable. The environment variable below is a test seam, not a documented knob:
 // packages/app/test/telemetry-flush.test.ts points it at a fake collector.
 export const defaultCollectorUrl = "https://collector.slopify.stream";
@@ -41,7 +41,7 @@ export function httpPostEvents(endpoint, timeoutMs) {
         }
         catch (error) {
             // Offline is the ordinary case, not a fault: the events stay queued and the user is
-            // told nothing (logic/16 step 5).
+            // told nothing.
             return { ok: false, retriable: true, reason: messageOf(error) };
         }
     };

package/dist/slices/telemetry/flush.js

@@ -2,16 +2,16 @@ import { machineOf, markDelivered, undeliveredEvents } from "./repo.js";
 // ceiling: 200 events per request against the collector's cap of 500, and at most 25
 // requests per flush. A queue longer than 5000 undelivered events drains over several
 // flushes rather than in one burst, which is the back-pressure an unbounded queue
-// (logic/16 §Q134) needs against a collector that has been away for months.
+// needs against a collector that has been away for months.
 export const batchSize = 200;
 const maxBatchesPerFlush = 25;
-// logic/16 step 5: the queue is flushed at app start and after each new event. Nothing
+// The queue is flushed at app start and after each new event. Nothing
 // here touches a pipeline, and an unreachable collector costs one refused socket.
 export async function flush(deps) {
     const machine = machineOf(deps.db);
     if (machine === undefined) {
         // Before the notice is dismissed there is no machine id to send events under, and
-        // logic/16 step 1 says nothing leaves until then.
+        // nothing leaves the machine until then.
         return { delivered: 0, dropped: 0 };
     }
     let delivered = 0;
@@ -30,7 +30,7 @@ export async function flush(deps) {
         }
         if (outcome.retriable) {
             // Offline, or the collector is having a bad day. The events stay queued and the
-            // user is told nothing (logic/16 step 5).
+            // user is told nothing.
             deps.log.write("info", "telemetry.deferred", {
                 detail: `${ids.length} events stay queued: ${outcome.reason}`,
             });
@@ -47,9 +47,9 @@ export async function flush(deps) {
     }
     return { delivered, dropped };
 }
-// The schedule from logic/16 step 5, debounced: a fan-out that finishes four stages at
-// once sends one request, not four. Every timer is unref'd, so a queued flush never
-// keeps the process alive.
+// The flush schedule, debounced: a fan-out that finishes four stages at once sends one
+// request, not four. Every timer is unref'd, so a queued flush never keeps the process
+// alive.
 export function createFlusher(deps, delayMs) {
     let timer;
     let running = false;
@@ -74,7 +74,7 @@ export function createFlusher(deps, delayMs) {
         flush(deps)
             .catch((error) => {
             // The timer has no caller to fail: a broken flush is logged and the next one
-            // tries again (logic/16 step 5).
+            // tries again.
             deps.log.write("warn", "telemetry.flush", { detail: messageOf(error) });
         })
             .finally(() => {

package/dist/slices/telemetry/machine.js

@@ -2,14 +2,13 @@ import { randomUUID } from "node:crypto";
 import { transact } from "../../kernel/db/tx.js";
 import { writeEvent } from "./record.js";
 import { insertMachine, machineOf } from "./repo.js";
-// logic/16 step 1: the notice is shown when no machine id exists.
+// The notice is shown when no machine id exists.
 export function noticeSeen(db) {
     return machineOf(db) !== undefined;
 }
-// logic/16 step 1 and mockup/02-first-run-notice: the id is created when the user
-// dismisses the notice, never at boot, so nothing is collected before the promise about
-// what is collected has been made. Deleting the data directory makes a new install
-// (§Q127); there is no reset control and no opt-out.
+// The id is created when the user dismisses the notice, never at boot, so nothing is collected
+// before the promise about what is collected has been made. Deleting the data directory makes a
+// new install; there is no reset control and no opt-out.
 export function dismissNotice(deps) {
     const existing = machineOf(deps.db);
     if (existing !== undefined) {
@@ -25,8 +24,8 @@ export function dismissNotice(deps) {
     };
     transact(deps.db, () => {
         insertMachine(deps.db, machine);
-        // logic/16 step 2: exactly one install event per machine. Written in the same
-        // transaction as the row that makes it unique, so a machine cannot exist without it.
+        // Exactly one install event per machine. Written in the same transaction as the row that
+        // makes it unique, so a machine cannot exist without it.
         writeEvent(deps, "install", {});
     });
     return machine;

package/dist/slices/telemetry/model.js

@@ -1,13 +1,12 @@
 import { z } from "zod";
 import { stageKinds } from "../../kernel/pipeline.js";
-// logic/16 step 2: one install event, one per project created, one per stage completing.
+// One install event, one per project created, one per stage completing.
 export const telemetryEventTypes = ["install", "project.created", "stage.completed"];
-// logic/16 step 2 counts finer than a stage: "one event per stage completing: research,
-// article, each intro/outro text, audio per segment (body, intro, outro), images,
-// thumbnail, video". The three that are not whole stages are named by `segment` beside
-// the stage that produced them - the article stage writes the intro and outro texts
-// (logic/07 step 5) and the audio stage narrates all three (logic/08 step 5) - so the
-// event type stays `stage.completed` and the pair (stage, segment) says which unit it is.
+// Counting is finer than a stage: one event per research, article, intro/outro text, audio
+// segment (body, intro, outro), images, thumbnail and video. The three that are not whole
+// stages are named by `segment` beside the stage that produced them - the article stage
+// writes the intro and outro texts, the audio stage narrates all three - so the event type
+// stays `stage.completed` and the pair (stage, segment) says which unit it is.
 export const audioSegments = ["body", "intro", "outro"];
 export const noTokens = { tokensIn: 0, tokensOut: 0 };
 export function plusUsage(tokens, usage) {
@@ -16,12 +15,11 @@ export function plusUsage(tokens, usage) {
         tokensOut: tokens.tokensOut + (usage?.outputTokens ?? 0),
     };
 }
-// The whole privacy surface. logic/16 step 4 bars API keys, prompt bodies, keyword
-// values, titles, article and research text, files, filenames, OS, locale and hardware
-// from a payload, and mockup/02-first-run-notice promises the user exactly that. The
-// schema below is strict, so a caller that hands `record` anything not named here is
-// rejected before the row is written; model.test.ts pins the set and record.test.ts
-// sweeps every event type against it.
+// The whole privacy surface. API keys, prompt bodies, keyword values, titles, article and
+// research text, files, filenames, OS, locale and hardware are all barred from a payload,
+// which is exactly what the first-run notice promises. The schema below is strict, so a
+// caller that hands `record` anything not named here is rejected before the row is written;
+// model.test.ts pins the set and record.test.ts sweeps every event type against it.
 export const payloadSchema = z.strictObject({
     appVersion: z.string().max(40),
     stage: z.enum(stageKinds).optional(),

package/dist/slices/telemetry/record.js

@@ -16,15 +16,15 @@ export function writeEvent(deps, type, counters) {
     insertTelemetryEvent(deps.db, event);
     return event;
 }
-// logic/16 step 5: telemetry never blocks and never fails a pipeline stage. This is the
-// one place in the codebase where an error is swallowed rather than propagated - a
-// failure to count a finished render must not undo the render. It is logged, so the
-// failure is still visible in <data-dir>/logs, and nothing else in this module catches.
+// Telemetry never blocks and never fails a pipeline stage. This is the one place in the
+// codebase where an error is swallowed rather than propagated - a failure to count a finished
+// render must not undo the render. It is logged, so the failure is still visible in
+// <data-dir>/logs, and nothing else in this module catches.
 export function record(deps, type, counters) {
     try {
-        // logic/16 step 2 precondition: a machine id exists for every event except the
-        // install event that creates it. Before the notice is dismissed nothing is written,
-        // so nothing about a run the user has not been told about can ever be sent.
+        // A machine id exists for every event except the install event that creates it. Before
+        // the notice is dismissed nothing is written, so nothing about a run the user has not
+        // been told about can ever be sent.
         if (type !== "install" && machineOf(deps.db) === undefined) {
             return;
         }

package/dist/slices/telemetry/repo.js

@@ -19,15 +19,15 @@ export function insertTelemetryEvent(db, event) {
 // recorded in the same millisecond carry the same timestamp and their ULIDs are random
 // within it, so a timestamp sort would hand back the install after the project it
 // preceded. The collector deduplicates by id, so re-sending the head of the queue after
-// an ambiguous failure is safe (logic/16 §Q134).
+// an ambiguous failure is safe.
 export function undeliveredEvents(db, limit) {
     return db
         .prepare("SELECT * FROM telemetry_events WHERE delivered_at IS NULL ORDER BY rowid LIMIT ?")
         .all(limit)
         .map((row) => toEvent(eventRow.parse(row)));
 }
-// logic/16 step 6 and §Q132: the Usage page's totals are the sum of the whole local log,
-// delivered or not, and §Q134 keeps that log forever.
+// The Usage page's totals are the sum of the whole local log, delivered or not, and that
+// log is kept forever.
 //
 // ceiling: every row is read and folded in memory. One event per stage of one run is a
 // few dozen bytes and a machine would need a hundred thousand runs to make this cost a
@@ -45,7 +45,7 @@ export function markDelivered(db, ids, at) {
     const holes = ids.map(() => "?").join(", ");
     db.prepare(`UPDATE telemetry_events SET delivered_at = ? WHERE id IN (${holes})`).run(at, ...ids);
 }
-// 02-models: a single row, so the first one is the machine.
+// A single row, so the first one is the machine.
 export function machineOf(db) {
     const row = db.prepare("SELECT * FROM machine LIMIT 1").get();
     return row === undefined ? undefined : toMachine(machineRow.parse(row));

package/dist/slices/telemetry/usage.js

@@ -16,8 +16,8 @@ function counters(events) {
         if (event.type === "project.created") {
             projects += 1;
         }
-        // One event per completed render (logic/16 step 3), which is the same rule the
-        // collector counts `videos_made` by, so the local page and the public board agree.
+        // One event per completed render, which is the same rule the collector counts `videos_made`
+        // by, so the local page and the public board agree.
         if (event.payload.stage === "video") {
             videosMade += 1;
         }
@@ -27,9 +27,9 @@ function counters(events) {
     }
     return { videosMade, audioSeconds, imagesMade, tokensUsed, projects };
 }
-// §Q128 counts tokens "with provider and model names, per stage", so the table groups by
-// all three. Rows with no tokens are left out: the table's two number columns would both
-// read zero, and the render and the image calls that produce them report no usage at all.
+// Tokens are counted with provider and model names per stage, so the table groups by all
+// three. Rows with no tokens are left out: the two number columns would both read zero, and
+// the render and image calls that produce them report no usage at all.
 //
 // ceiling: this is a per-stage table, not a per-model one. The user deferred the per-model
 // breakdown on the public counters on 2026-09-03; the payload already carries the provider

package/dist/slices/thumbnail/by-llm.js

@@ -23,8 +23,8 @@ export function thumbnailMessages(brief) {
         },
     ];
 }
-// §Q82: "empty output is a failed attempt". Returned as the sentence the stage would show
-// rather than thrown, because the wrapper's `check` hook is what makes it a retry.
+// Empty output is a failed attempt. Returned as the sentence the stage would show rather than
+// thrown, because the wrapper's `check` hook is what makes it a retry.
 export function writtenPrompt(text) {
     return text.trim() === "" ? "the LLM wrote no thumbnail prompt" : undefined;
 }

package/dist/slices/thumbnail/run.js

@@ -8,9 +8,9 @@ import { insertOutput, outputsOf } from "../storage/repo.js";
 import { storeText } from "../storage/staging.js";
 import { noTokens, plusUsage } from "../telemetry/model.js";
 import { thumbnailMessages, writtenPrompt } from "./by-llm.js";
-// The `prompt_written` sub-step of §Q82, persisted for resume: the prompt the LLM wrote
-// and the messages that asked for it, so a resumed run reproduces the record without
-// asking again.
+// The `prompt_written` sub-step, persisted for resume: the prompt the LLM wrote and the
+// messages that asked for it, so a resumed run reproduces the record without asking
+// again.
 const writtenPayload = z.object({ prompt: z.string(), sent: z.string() });
 export async function runThumbnail(deps, context, providers) {
     const { projectId } = context.stage;
@@ -20,25 +20,24 @@ export async function runThumbnail(deps, context, providers) {
     }
     const source = project.config.sources.thumbnail;
     if (source !== "from_prompt" && source !== "prompt_by_llm") {
-        // Off is `skipped` and Provide is `provided` at project creation (`logic/01` step 1),
+        // Off is `skipped` and Provide is `provided` at project creation,
         // so the runner never starts this stage for either.
         throw new Error(`the thumbnail stage cannot run with its source set to ${source}`);
     }
     const choice = project.config.images;
     if (choice === undefined) {
-        // Admission requires the image provider whenever the thumbnail is generated
-        // (`logic/04` step 2), so reaching here is a bug in admission rather than the user's.
+        // Admission requires the image provider whenever the thumbnail is generated, so reaching
+        // here is a bug in admission rather than the user's.
         throw new Error("the run has no image provider or model");
     }
     const written = source === "from_prompt" ? undefined : await byLlm(deps, context, providers, project);
     const prompt = written?.prompt ?? fromTemplate(project);
     await make(deps, context, providers, project, choice, prompt);
-    // logic/16 step 3 counts tokens "with provider and model names, per stage", and a
-    // payload names one provider. This stage can use two - the LLM that writes the prompt
-    // (`logic/10`) and the image model that draws it - so the event names the one whose
-    // usage it reports, because provider and model are shown beside the token columns on
-    // the Usage page. A thumbnail from a picked template makes no LLM call, so it names the
-    // image model that made it and reports the zero of step 3.
+    // Tokens are counted with a provider and model name per stage, and a payload names one
+    // provider. This stage can use two - the LLM that writes the prompt and the image model
+    // that draws it - so the event names whichever one's usage it reports, because both are
+    // shown beside the token columns on the Usage page. A thumbnail from a picked template
+    // makes no LLM call, so it names the image model and reports zero tokens.
     deps.count("stage.completed", {
         stage: "thumbnail",
         provider: written?.provider ?? choice.provider,
@@ -52,7 +51,7 @@ export async function runThumbnail(deps, context, providers) {
         detail: source === "from_prompt" ? "from the picked prompt" : "from the prompt the LLM wrote",
     });
 }
-// `logic/09` step 4: the rendered thumbnail template goes to the image provider as it is.
+// The rendered thumbnail template goes to the image provider as it is.
 function fromTemplate(project) {
     const rendered = project.config.rendered.thumbnailPrompt;
     if (rendered === undefined) {
@@ -60,14 +59,13 @@ function fromTemplate(project) {
     }
     return rendered;
 }
-// `logic/10` steps 1 to 3. §Q82: a written prompt already on the project is reused, so a
-// manual retry redoes only the image call and the wording the user is looking at does not
-// change under them.
+// A written prompt already on the project is reused, so a manual retry redoes only the
+// image call and the wording the user is looking at does not change under them.
 async function byLlm(deps, context, providers, project) {
     const kept = piecesOf(deps.db, context.stage.id, "prompt_written")[0];
     const llm = project.config.llm;
     if (kept !== undefined && kept.state === "done") {
-        // §Q82: the wording the user is looking at does not change under them. No call was
+        // The wording the user is looking at does not change under them. No call was
         // made, so this run counts none - the run that wrote the prompt already did.
         return {
             prompt: payloadOf(kept).prompt,
@@ -76,7 +74,7 @@ async function byLlm(deps, context, providers, project) {
         };
     }
     if (llm === undefined) {
-        // §Q81 makes the LLM row required when the thumbnail source is Prompt by LLM.
+        // Admission requires the LLM row when the thumbnail source is Prompt by LLM.
         throw new Error("the run has no LLM provider or model");
     }
     const messages = thumbnailMessages(brief(deps, project));
@@ -84,13 +82,13 @@ async function byLlm(deps, context, providers, project) {
         provider: llm.provider,
         model: llm.model,
         messages,
-        // §Q82: an empty answer is a failed attempt, and the wrapper is what retries it.
+        // An empty answer is a failed attempt, and the wrapper is what retries it.
         check: (given) => writtenPrompt(given.text),
     });
-    // Step 3 and §Q83: the image prompt is exactly the LLM's output, never edited by the app.
+    // The image prompt is exactly the LLM's output, never edited by the app.
     const prompt = answer.text.trim();
     keepWritten(deps, context, kept?.id, prompt, messages);
-    // The messages sent are stored beside the article stage's, per stage (`logic/14` step 2).
+    // The messages sent are stored beside the article stage's, per stage.
     storeText(deps, {
         projectId: context.stage.projectId,
         stageKind: "thumbnail",
@@ -115,9 +113,9 @@ function brief(deps, project) {
         article: articleText(deps, project.id),
     };
 }
-// §Q79's invariant: the stage never starts without an article on the project. The runner's
-// graph holds the other half - the thumbnail waits on the article stage - so a project
-// with no article row here is a stage that started against a run that never wrote one.
+// The stage never starts without an article on the project. The runner's graph holds the other
+// half - the thumbnail waits on the article stage - so a project with no article row here is a
+// stage that started against a run that never wrote one.
 function articleText(deps, projectId) {
     const article = outputsOf(deps.db, projectId).find((output) => output.role === "article_txt");
     if (article === undefined) {
@@ -142,12 +140,12 @@ function keepWritten(deps, context, existing, prompt, messages) {
     }
     setPiece(deps.db, existing, "done", payload);
 }
-// `logic/09` step 4: one call, the same aspect rule as the slideshow, stored apart from it
+// One call, the same aspect rule as the slideshow, stored apart from it
 // with the prompt text, the provider and the model.
 async function make(deps, context, providers, project, choice, prompt) {
     const { projectId } = context.stage;
     if (outputsOf(deps.db, projectId).some((output) => output.role === "thumbnail")) {
-        // §Q82's `image-done` sub-step: a retry that failed after the image landed keeps it.
+        // The `image-done` sub-step: a retry that failed after the image landed keeps it.
         return;
     }
     const made = await providers.image({
@@ -158,8 +156,8 @@ async function make(deps, context, providers, project, choice, prompt) {
     });
     const name = outputFileName("thumbnail", 1, made.mime === "image/png" ? ".png" : ".jpg", "thumbnail");
     write(deps, projectId, name, made);
-    // `logic/13` §Q113 protects an output already stored, not one about to be: a cancel
-    // landing between the write and the row leaves a file the boot reconcile collects.
+    // A cancel protects an output already stored, not one about to be: one landing between
+    // the write and the row leaves a file the boot reconcile collects.
     context.signal.throwIfAborted();
     const output = {
         id: deps.ids.next(),
@@ -170,8 +168,8 @@ async function make(deps, context, providers, project, choice, prompt) {
         originalFilename: null,
         bytes: made.bytes.byteLength,
         durationMs: null,
-        // §Q76 and §Q80. There is no `index`: §Q72 keeps the thumbnail out of the slideshow,
-        // and the render reads that list by role.
+        // There is no `index`: the thumbnail stays out of the slideshow, and the render reads
+        // that list by role.
         meta: {
             promptName: project.config.thumbnailPrompt ?? "",
             prompt,
@@ -180,8 +178,8 @@ async function make(deps, context, providers, project, choice, prompt) {
         },
         createdAt: deps.clock.now().toISOString(),
     };
-    // No `image.landed`: §Q72 keeps the thumbnail out of the slideshow, and that event's
-    // `index` is a place in it. The stage reaching `done` is what tells the page.
+    // No `image.landed`: the thumbnail stays out of the slideshow, and that event's `index`
+    // is a place in it. The stage reaching `done` is what tells the page.
     insertOutput(deps.db, output);
 }
 function write(deps, projectId, name, made) {

package/dist/slices/video/ffmpeg.js

@@ -4,8 +4,8 @@ import { zoomBy, zoomFrom, zoomTo } from "./plan.js";
 // and a wrapper would hide it. Every value goes into an argument array, never a shell
 // string, so a title or a filename cannot become a command.
 // zoompan works on a still that has been pre-scaled, because it steps the zoom in
-// sub-pixel increments and a source at output resolution visibly jitters (logic/11 §Q85
-// asks for a smooth linear zoom). Four times the frame is enough at 115%.
+// sub-pixel increments and a source at output resolution visibly jitters where the zoom is
+// meant to be smooth and linear. Four times the frame is enough at 115%.
 const prescale = 4;
 const sampleRate = 44100;
 const channelLayout = "stereo";
@@ -74,7 +74,7 @@ function filterGraph(plan, audioAt) {
     const tall = plan.height * prescale;
     plan.images.forEach((slot, at) => {
         chains.push(`[${at}:v]trim=end_frame=1,setpts=PTS-STARTPTS,` +
-            // logic/11 step 4: cover the frame and centre-crop, never letterbox.
+            // Cover the frame and centre-crop, never letterbox.
             `scale=${wide}:${tall}:force_original_aspect_ratio=increase,crop=${wide}:${tall},` +
             `zoompan=z='${zoomExpression(slot)}':d=${slot.frames}:` +
             `x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':` +
@@ -89,7 +89,7 @@ function filterGraph(plan, audioAt) {
     chains.push(`${audioAt.map((_input, at) => `[a${at}]`).join("")}concat=n=${audioAt.length}:v=0:a=1[a]`);
     return chains.join(";");
 }
-// §Q85: odd images 100% → 115%, even images 115% → 100%, linear over the slot. `on` is
+// Odd images 100% → 115%, even images 115% → 100%, linear over the slot. `on` is
 // zoompan's output frame counter, 0 to d-1, and a one-frame slot has no span to divide
 // by, so it holds the zoom it starts at.
 function zoomExpression(slot) {
@@ -111,8 +111,8 @@ export function progressMsOf(line) {
     const microseconds = matched?.[1];
     return microseconds === undefined ? undefined : Math.floor(Number(microseconds) / 1000);
 }
-// ceiling: the last 20 lines of stderr are kept. logic/11 §Q89 shows the renderer's error
-// verbatim, and ffmpeg's useful complaint is always at the end of what it wrote.
+// ceiling: the last 20 lines of stderr are kept. The renderer's error is shown verbatim,
+// and ffmpeg's useful complaint is always at the end of what it wrote.
 const stderrLines = 20;
 export function runFfmpeg(run) {
     return new Promise((resolve, reject) => {

package/dist/slices/video/plan.js

@@ -1,10 +1,10 @@
-// logic/11 step 5: 30 fps, 1920×1080 for 16:9 and 1080×1920 for 9:16.
+// 30 fps, 1920×1080 for 16:9 and 1080×1920 for 9:16.
 export const fps = 30;
 const frames = {
     "16:9": { width: 1920, height: 1080 },
     "9:16": { width: 1080, height: 1920 },
 };
-// §Q85: 100% → 115%, linear, centred, alternating per image. The three are written out
+// 100% → 115%, linear, centred, alternating per image. The three are written out
 // rather than derived from one another, because they are formatted into an ffmpeg
 // expression and 1.15 - 1 is not 0.15 in binary floating point.
 export const zoomFrom = 1;
@@ -12,7 +12,7 @@ export const zoomTo = 1.15;
 export const zoomBy = 0.15;
 export function planRender(input) {
     if (input.images.length === 0) {
-        // logic/04 §Q31 makes an image source mandatory, so an empty set is a bug upstream.
+        // Admission makes an image source mandatory, so an empty set is a bug upstream.
         throw new Error("a render needs at least one image");
     }
     const frame = frames[input.format];
@@ -31,7 +31,7 @@ export function planRender(input) {
         output: input.output,
     };
 }
-// logic/11 step 1: intro, gap, body, gap, outro, with a gap only where the segment on
+// Intro, gap, body, gap, outro, with a gap only where the segment on
 // the other side of it exists.
 function timeline(input) {
     const segments = [];
@@ -55,17 +55,17 @@ function timeline(input) {
     }
     return segments;
 }
-// logic/11 step 2: the slot is the total divided by the image count, and the last image
-// absorbs the frame rounding. §Q100: one image fills the whole length.
-// ceiling: every slot holds at least one frame, so a run with more images than the
-// timeline has frames renders slightly longer than its audio rather than failing.
+// The slot is the total divided by the image count, and the last image absorbs the frame
+// rounding. One image fills the whole length. ceiling: every slot holds at least one frame, so
+// a run with more images than the timeline has frames renders slightly longer than its audio
+// rather than failing.
 function slots(paths, totalFrames) {
     const each = Math.max(1, Math.floor(totalFrames / paths.length));
     return paths.map((path, at) => ({
         path,
         index: at + 1,
         frames: at === paths.length - 1 ? Math.max(1, totalFrames - each * at) : each,
-        // §Q85: odd images zoom in, even images zoom out.
+        // Odd images zoom in, even images zoom out.
         zoom: at % 2 === 0 ? "in" : "out",
     }));
 }