@gentbajko/slopify 0.1.0 → 0.3.0

package/dist/slices/reruns/cascade.js

@@ -13,8 +13,8 @@ function staleStages(input) {
         case "rerun":
             return withDependents([action.stage]);
         case "article-edit": {
-            // §Q101, in its own words: "audio, LLM-mode intro/outro text, LLM-written
-            // thumbnail, and video re-run; prompt-based images are untouched". The video comes
+            // An article edit re-runs audio, LLM-mode intro/outro text, the LLM-written
+            // thumbnail and the video, leaving prompt-based images untouched. The video comes
             // along as a dependent of the audio, so it is never named here.
             const roots = ["audio"];
             if (input.thumbnailSource === "prompt_by_llm") {
@@ -23,26 +23,25 @@ function staleStages(input) {
             return withDependents(roots);
         }
         case "image-deleted":
-            // Step 5: the image is "removed from the set; video re-renders". The remaining
+            // The image is removed from the set and the video re-renders. The remaining
             // images stand, so the images stage itself is not redone.
             return withDependents(["video"]);
         case "image-regenerated":
             return withDependents(["images"]);
     }
 }
-// `logic/01` forbids `provided` → `running` and `skipped` → `running`, so a stage whose
-// output the user supplied or switched off is stepped over. The walk above still passes
+// `provided` → `running` and `skipped` → `running` are forbidden, so a stage whose output
+// the user supplied or switched off is stepped over. The walk above still passes
 // through it: re-running the article with a provided audio must reach the video.
 function redoable(state) {
     return state !== "provided" && state !== "skipped";
 }
 function clearsOf(action, kind) {
-    // §Q106: "the previous video stays downloadable until the new render finishes". Clearing
-    // the video's outputs here would take it away the moment the user pressed Re-render - or
-    // for the whole of a re-narration, when the video comes along as a dependent. It is kept
-    // instead, and `slices/video/run.ts` replaces the file and the rows in one swap once
-    // ffmpeg has exited cleanly. A render that fails or is canceled leaves the old one
-    // standing, which is exactly what §Q106 promises.
+    // The previous video stays downloadable until the new render finishes. Clearing the video's
+    // outputs here would take it away the moment the user pressed Re-render - or for the whole of
+    // a re-narration, when the video comes along as a dependent. It is kept instead, and
+    // `slices/video/run.ts` replaces the file and the rows in one swap once ffmpeg has exited
+    // cleanly. A render that fails or is canceled leaves the old one standing.
     if (kind === "video") {
         return "nothing";
     }

package/dist/slices/reruns/index.js

@@ -12,10 +12,10 @@ import { redoPlan } from "./cascade.js";
 // Only the one field this module changes is named; the rest of a piece's payload belongs
 // to the stage that wrote it and travels through untouched.
 const anyObject = z.record(z.string(), z.unknown());
-// What an article edit replaces (step 1). `instructions` is not among them: §Q57 keeps
-// the record of what was actually sent to the model, and an edit did not send anything.
+// What an article edit replaces. `instructions` is not among them: that row records what
+// was actually sent to the model, and an edit did not send anything.
 const articleRoles = ["article_md", "article_txt", "sources", "glossary"];
-// `logic/13` step 5 and `logic/01` §Q5: Retry is offered on a stage that stopped short,
+// Retry is offered on a stage that stopped short,
 // and a canceled stage resumes exactly as a failed one does.
 export function retryStage(deps, projectId, kind) {
     const loaded = load(deps, projectId);
@@ -27,14 +27,14 @@ export function retryStage(deps, projectId, kind) {
         return { ok: false, reason: "not-retryable" };
     }
     // The pieces and the outputs stay where they are: the per-stage resume rules keep what
-    // finished (`logic/06` §Q54, `logic/08` §Q66, `logic/09` §Q73), and `logic/13` step 2
-    // keeps them through a cancel too. That is the whole of "a canceled stage is resumable".
+    // finished, and a cancel keeps them too. That is the whole of a canceled stage being
+    // resumable.
     transact(deps.db, () => {
         resetStage(deps.db, stage.id);
     });
     return { ok: true, redone: [kind] };
 }
-// Steps 2, 3 and 8: Re-run audio with another voice, Re-run images, Re-render. The stage
+// Re-run audio with another voice, Re-run images, Re-render. The stage
 // starts over from the project's stored configuration rather than resuming.
 export function rerunStage(deps, projectId, kind) {
     const loaded = load(deps, projectId);
@@ -47,15 +47,15 @@ export function rerunStage(deps, projectId, kind) {
     }
     return apply(deps, projectId, { kind: "rerun", stage: kind }, loaded);
 }
-// Step 1: "the inline editor replaces the stored markdown; the plain-text narration source
-// and the sources and glossary files are rebuilt; then audio, LLM-mode intro/outro text,
-// LLM-written thumbnail, and video re-run; prompt-based images are untouched".
+// The inline editor replaces the stored markdown; the plain-text narration source and the
+// sources and glossary files are rebuilt; then audio, LLM-mode intro/outro text, the
+// LLM-written thumbnail and the video re-run, leaving prompt-based images untouched.
 //
 // ceiling: the LLM-mode intro and outro texts are *not* rewritten from the edited article.
-// Only the article stage writes them (`logic/07` step 5), and §Q60 makes any run of that
-// stage regenerate the whole article - which would throw away the edit that triggered it.
-// The audio does re-narrate the kept entry text, so the video is whole; the upgrade is a
-// mode on the article stage that keeps the stored article and rewrites the entries alone.
+// Only the article stage writes them, and any run of that stage regenerates the whole
+// article - which would throw away the edit that triggered it. The audio does re-narrate
+// the kept entry text, so the video is whole; the upgrade is a mode on the article stage
+// that keeps the stored article and rewrites the entries alone.
 export function editArticle(deps, projectId, markdown) {
     const loaded = load(deps, projectId);
     if (!loaded.ok) {
@@ -67,8 +67,8 @@ export function editArticle(deps, projectId, markdown) {
     }
     const text = markdown.trim();
     if (text === "") {
-        // §Q106 leaves a project with one output per stage; an empty article would leave the
-        // audio stage with nothing to narrate and no way back except another edit.
+        // A project keeps one output per stage; an empty article would leave the audio stage
+        // with nothing to narrate and no way back except another edit.
         return { ok: false, reason: "empty-article" };
     }
     return apply(deps, projectId, { kind: "article-edit" }, loaded, () => {
@@ -76,15 +76,15 @@ export function editArticle(deps, projectId, markdown) {
         for (const output of replaced) {
             deleteOutput(deps.db, output.id);
         }
-        // The four files are written back under the names they already had, so the write is
-        // the replacement §Q106 asks for rather than a second version beside the first.
+        // The four files are written back under the names they already had, so the write
+        // replaces rather than leaving a second version beside the first.
         storeText(deps, { projectId, stageKind: "article", role: "article_md", text });
         storeArticleText(deps, { projectId, markdown: text });
         return replaced.map((output) => output.path);
     });
 }
-// Step 5 with `logic/09` §Q75: one image is "removed from the set; at least one image must
-// remain; video re-renders".
+// One image is removed from the set, at least one image has to remain, and the video
+// re-renders.
 export function deleteImage(deps, projectId, outputId) {
     const loaded = load(deps, projectId);
     if (!loaded.ok) {
@@ -95,8 +95,7 @@ export function deleteImage(deps, projectId, outputId) {
         return { ok: false, reason: "unknown-image" };
     }
     if (loaded.outputs.filter((output) => output.role === "image").length <= 1) {
-        // §Q103's invariant: "at least one image always remains". `logic/11` step 2 has no
-        // slideshow to compute without one.
+        // At least one image always remains: there is no slideshow to compute without one.
         return { ok: false, reason: "last-image" };
     }
     return apply(deps, projectId, { kind: "image-deleted" }, loaded, () => {
@@ -108,9 +107,9 @@ export function deleteImage(deps, projectId, outputId) {
         return [image.path];
     });
 }
-// Step 4: "one new call with that image's stored prompt text, replacing it in place at the
-// same index (§Q103)". The piece carries that prompt and that index, so it is left alone
-// and the images stage sees one image of its plan missing.
+// One new call with that image's stored prompt text, replacing it in place at the same
+// index. The piece carries that prompt and that index, so it is left alone and the images
+// stage sees one image of its plan missing.
 export function regenerateImage(deps, projectId, outputId) {
     const loaded = load(deps, projectId);
     if (!loaded.ok) {
@@ -132,9 +131,9 @@ function load(deps, projectId) {
         return { ok: false, reason: "no-project" };
     }
     const stages = stagesOf(deps.db, projectId);
-    // The precondition every action of `logic/12` shares: "no stage of the project is
-    // `running` (§Q106)". The page disables the controls; this is the other half, because
-    // clearing an output from under a stage that is writing it would lose both.
+    // The precondition every re-run action shares: no stage of the project is `running`. The
+    // page disables the controls; this is the other half, because clearing an output from
+    // under a stage that is writing it would lose both.
     if (stages.some((stage) => stage.state === "running")) {
         return { ok: false, reason: "running" };
     }
@@ -145,15 +144,15 @@ function load(deps, projectId) {
         thumbnailSource: project.config.sources.thumbnail,
     };
 }
-// One transaction for every row the action touches, then the filesystem. S4's lesson:
-// an unlink cannot be rolled back, so it waits for the commit - and a file with no row is
-// what the boot reconcile collects, where a row with no file is a broken download.
+// One transaction for every row the action touches, then the filesystem: an unlink cannot
+// be rolled back, so it waits for the commit. A file with no row is what the boot reconcile
+// collects, where a row with no file is a broken download.
 function apply(deps, projectId, action, loaded, own) {
     const plan = redoPlan({ action, stages: loaded.stages, thumbnailSource: loaded.thumbnailSource });
     // `own` is the action's own change - the new article, the image that goes - and it runs
     // first and inside the same transaction, so it lands or rolls back with the cascade it
-    // triggers. The files it writes take the names they already had, which is the
-    // replacement §Q106 asks for rather than work a rollback would have to undo.
+    // triggers. The files it writes take the names they already had, replacing in place
+    // rather than leaving work a rollback would have to undo.
     const orphaned = transact(deps.db, () => {
         const files = own === undefined ? [] : [...own()];
         for (const redo of plan) {
@@ -172,7 +171,7 @@ function apply(deps, projectId, action, loaded, own) {
     return { ok: true, redone: plan.map((redo) => redo.stage) };
 }
 // Everything the stage produced: its outputs, and the resumable pieces whose payloads name
-// files of their own - the audio chunks of `logic/08` §Q65, which are not outputs.
+// files of their own - the audio chunks, which are not outputs.
 function clearStage(deps, stage, outputs) {
     const files = [];
     for (const output of outputs) {
@@ -191,7 +190,7 @@ function clearStage(deps, stage, outputs) {
     deletePieces(deps.db, stage.id);
     return files;
 }
-// §Q103 replaces the image "in place at the same index", so the piece keeps the prompt
+// A regenerated image is replaced in place at the same index, so the piece keeps the prompt
 // and the index it was planned with and only stops naming a file: `slices/images/run.ts`
 // then sees one image of its plan still to make, and the file it named can be removed.
 function forgetImageFile(deps, stages, path) {
@@ -252,9 +251,9 @@ function removeFiles(deps, projectId, orphaned) {
         }
     }
 }
-// `logic/01`: `done` → `running` is scenario 12's own transition, and a stage that failed
-// or was canceled may be started over rather than resumed. `provided` and `skipped` never
-// run, and `pending` has nothing to redo.
+// `done` → `running` is a re-run's own transition, and a stage that failed or was canceled may
+// be started over rather than resumed. `provided` and `skipped` never run, and `pending` has
+// nothing to redo.
 function rerunnable(state) {
     return state === "done" || state === "failed" || state === "canceled";
 }

package/dist/slices/research/planner.js

@@ -7,7 +7,7 @@ export function plannerMessages(brief) {
                 "",
                 briefText(brief),
                 "",
-                // §Q53: the prompt's section guide decides the chapters when it has one, and the
+                // The prompt's section guide decides the chapters when it has one, and the
                 // planner proposes them when it does not. There is no cap on the count.
                 "List the chapters to research. If the prompt sets out a section guide, take the",
                 "chapters from it, in the order it gives them. If it does not, propose the chapters",
@@ -21,8 +21,7 @@ export function plannerMessages(brief) {
 }
 // The answer is a list, however the model chose to punctuate it. Numbering and bullets
 // are stripped because the instruction above asks for neither and models add them
-// anyway; a repeated title is dropped because `logic/06`'s invariant is that no chapter
-// is researched twice.
+// anyway; a repeated title is dropped because no chapter is researched twice.
 export function chaptersFrom(text) {
     const seen = new Set();
     const chapters = [];
@@ -40,7 +39,7 @@ export function chaptersFrom(text) {
     }
     return chapters;
 }
-// §Q52, §Q53: one sub-agent per chapter, web-grounded, answering that chapter's notes
+// One sub-agent per chapter, web-grounded, answering that chapter's notes
 // and its sources. The whole outline travels with it so it covers its own chapter and
 // leaves the neighbouring ones to the sub-agents researching them.
 export function subAgentMessages(brief, chapter, outline) {
@@ -65,7 +64,7 @@ export function subAgentMessages(brief, chapter, outline) {
         },
     ];
 }
-// The half of every instruction that is the same for all three calls (§Q46): the
+// The half of every instruction that is the same for all three calls: the
 // rendered prompt the article will be written from, and the run's keyword values.
 export function briefText(brief) {
     const values = Object.entries(brief.values);

package/dist/slices/research/run.js

@@ -7,11 +7,11 @@ import { storeText } from "../storage/staging.js";
 import { noTokens, plusUsage } from "../telemetry/model.js";
 import { chaptersFrom, plannerMessages, subAgentMessages } from "./planner.js";
 import { sourcedAnswer, synthesisMessages } from "./synthesis.js";
-// §Q47, verbatim: "the stage fails immediately with 'web research unsupported by this
-// model'; no fallback to model knowledge".
+// A model that cannot ground on the web fails the stage immediately, with no fallback to
+// what the model already knows.
 export const webResearchUnsupported = "web research unsupported by this model";
 // What a chapter piece carries between runs: its title, and its notes once a sub-agent
-// has answered. That is the whole of the resume of §Q54.
+// has answered. That is the whole of the resume.
 const chapterPayload = z.object({ title: z.string(), notes: z.string().optional() });
 export async function runResearch(deps, context, providers) {
     const { projectId } = context.stage;
@@ -22,7 +22,7 @@ export async function runResearch(deps, context, providers) {
     const choice = project.config.llm;
     const articlePrompt = project.config.rendered.article;
     if (choice === undefined || articlePrompt === undefined) {
-        // Admission refuses a run whose research is Generate without both (`logic/04`), so
+        // Admission refuses a run whose research is Generate without both, so
         // reaching here is a bug in admission rather than something the user did.
         throw new Error("the run has no LLM provider or no rendered article prompt");
     }
@@ -32,7 +32,7 @@ export async function runResearch(deps, context, providers) {
     }
     catch (error) {
         // The adapter says the model cannot ground on the web and the wrapper has already
-        // made that terminal; this is where it becomes the sentence the user reads (§Q47).
+        // made that terminal; this is where it becomes the sentence the user reads.
         if (isProviderError(error) && error.fault.kind === "unsupported") {
             throw new Error(webResearchUnsupported);
         }
@@ -40,10 +40,9 @@ export async function runResearch(deps, context, providers) {
     }
 }
 async function research(deps, context, providers, choice, brief) {
-    // logic/16 step 3 counts tokens per stage, so the planner, every sub-agent and the
-    // synthesis add into one total. A call that was aborted or that failed never answers,
-    // so it adds nothing (§Q112); a provider that reports no usage adds zero, never an
-    // estimate (§Q131).
+    // Tokens are counted per stage, so the planner, every sub-agent and the synthesis add
+    // into one total. A call that was aborted or failed never answers and adds nothing; a
+    // provider that reports no usage adds zero, never an estimate.
     let tokens = noTokens;
     const add = (usage) => {
         tokens = plusUsage(tokens, usage);
@@ -58,8 +57,8 @@ async function research(deps, context, providers, choice, brief) {
     });
     add(answer.usage);
     const { projectId } = context.stage;
-    // Step 4: the notes and every instruction sent are stored on the project. Each
-    // sub-agent's own output stays on its chapter row, which is where the resume reads it.
+    // The notes and every instruction sent are stored on the project. Each sub-agent's own output
+    // stays on its chapter row, which is where the resume reads it.
     storeText(deps, { projectId, stageKind: "research", role: "notes", text: answer.text.trim() });
     storeText(deps, {
         projectId,
@@ -80,7 +79,7 @@ async function research(deps, context, providers, choice, brief) {
     });
 }
 // The chapter list, planned once and kept. A retry after a failure finds the rows the
-// first run wrote and does not ask again (§Q54).
+// first run wrote and does not ask again.
 async function plan(deps, context, providers, choice, brief, add) {
     const existing = piecesOf(deps.db, context.stage.id, "chapter");
     if (existing.length > 0) {
@@ -90,11 +89,11 @@ async function plan(deps, context, providers, choice, brief, add) {
         provider: choice.provider,
         model: choice.model,
         messages: plannerMessages(brief),
-        // §Q50: an empty answer, or one with no chapter in it, is a failed attempt.
+        // An empty answer, or one with no chapter in it, is a failed attempt.
         check: (given) => chaptersFrom(given.text).length === 0 ? "the planner named no chapters" : undefined,
     });
     add(answer.usage);
-    // §Q53: no cap on the count. The list is the prompt's own section guide as often as
+    // No cap on the count. The list is the prompt's own section guide as often as
     // not, and capping it would silently drop a section the article asks for.
     const planned = chaptersFrom(answer.text).map((title, index) => ({
         id: deps.ids.next(),
@@ -111,9 +110,9 @@ async function plan(deps, context, providers, choice, brief, add) {
     });
     return planned;
 }
-// §Q53: "one per chapter, all in parallel". §Q54: a chapter a previous run finished is
-// not researched again, and one that fails fails the whole stage while its siblings
-// finish and keep their output for the next resume.
+// One sub-agent per chapter, all in parallel. A chapter a previous run finished is not
+// researched again, and one that fails takes down the whole stage while its siblings finish and
+// keep their output for the next resume.
 async function researchChapters(deps, context, providers, choice, brief, chapters, add) {
     const outline = chapters.map((piece) => payloadOf(piece).title);
     const total = chapters.length;
@@ -130,7 +129,7 @@ async function researchChapters(deps, context, providers, choice, brief, chapter
                 provider: choice.provider,
                 model: choice.model,
                 messages: subAgentMessages(brief, kept.title, outline),
-                // §Q47: grounding is asked for explicitly, so a model without it says so
+                // Grounding is asked for explicitly, so a model without it says so
                 // instead of answering from what it already knows.
                 webSearch: true,
                 check: (given) => sourcedAnswer(`the researcher on "${kept.title}"`, given.text),
@@ -143,8 +142,8 @@ async function researchChapters(deps, context, providers, choice, brief, chapter
             return { ok: true, finding: { title: kept.title, notes } };
         }
         catch (error) {
-            // A cancel is not this chapter failing: `logic/13` §Q112 counts an aborted call
-            // as nothing, and the resume runs a `pending` chapter exactly as a failed one.
+            // A cancel is not this chapter failing: an aborted call counts as nothing, and
+            // the resume runs a `pending` chapter exactly as a failed one.
             setPiece(deps.db, piece.id, context.signal.aborted ? "pending" : "failed", piece.payload);
             return { ok: false, error };
         }
@@ -158,8 +157,8 @@ async function researchChapters(deps, context, providers, choice, brief, chapter
     }
     return findings;
 }
-// Step 5: "k of N chapters researched". Written as well as emitted, so a page opened
-// mid-stage reads the count off the row rather than waiting for the next chapter.
+// K of N chapters researched, written as well as emitted, so a page opened mid-stage reads the
+// count off the row rather than waiting for the next chapter.
 function report(deps, context, done, total) {
     setStageProgress(deps.db, context.stage.id, done, total);
     context.emit({
@@ -170,7 +169,7 @@ function report(deps, context, done, total) {
         total,
     });
 }
-// §Q51: every instruction sent is stored on the project. All three are pure functions of
+// Every instruction sent is stored on the project. All three are pure functions of
 // the brief and the findings, so a resumed run reproduces the ones it did not send.
 function instructionsText(brief, findings) {
     const outline = findings.map((finding) => finding.title);

package/dist/slices/research/synthesis.js

@@ -1,7 +1,7 @@
 import { briefText } from "./planner.js";
-// §Q52: "an editorial pass over every sub-agent's output that selects and organizes the
-// findings; it does not concatenate". The sub-agents' notes are the material, not the
-// answer, and the synthesising model is told so.
+// An editorial pass over every sub-agent's output that selects and organizes the findings; it
+// does not concatenate. The sub-agents' notes are the material, not the answer, and the
+// synthesising model is told so.
 export function synthesisMessages(brief, findings) {
     return [
         {
@@ -26,7 +26,7 @@ export function synthesisMessages(brief, findings) {
         },
     ];
 }
-// §Q48 and §Q55: the stored notes always end with a Sources list, and an answer without
+// The stored notes always end with a Sources list, and an answer without
 // one "counts as a failed attempt". A heading with nothing under it is not a list, so
 // the line has to be followed by something.
 const heading = /^\s*(?:#{1,6}\s*)?(?:\*\*)?\s*sources(?:\s+(?:list|consulted))?\s*(?:\*\*)?\s*:?\s*$/i;
@@ -36,7 +36,7 @@ export function endsWithSources(text) {
     return at !== -1 && lines.slice(at + 1).some((line) => line.trim() !== "");
 }
 // The one shape a stage hands `StageProviders.llm` as its `check`: an answer that arrived
-// but cannot be used is a failed attempt, so the wrapper retries it (§Q50, §Q55).
+// but cannot be used is a failed attempt, so the wrapper retries it.
 export function sourcedAnswer(who, text) {
     if (text.trim() === "") {
         return `${who} answered with nothing`;

package/dist/slices/settings/cli-status.js

@@ -1,16 +1,15 @@
 import { execFile } from "node:child_process";
-// ceiling: `logic/02` §Q135 computes readiness at request time, so nothing is cached and
-// a hung CLI costs the settings page this long. Both probes run in parallel, so the page
-// waits 2 s in the worst case. Caching the answer for a few seconds is the upgrade if a
-// slow machine makes the status line flap.
+// ceiling: readiness is computed at request time, so nothing is cached and a hung CLI costs the
+// settings page this long. Both probes run in parallel, so the page waits 2 s in the worst
+// case. Caching the answer for a few seconds is the upgrade if a slow machine makes the status
+// line flap.
 export const cliProbeTimeoutMs = 2000;
 const probeOutputMax = 64 * 1024;
-// The real probe: an argument array, never a shell string, so nothing in a binary name
-// or an argument can be interpreted as a command. It resolves for every outcome; a
-// missing CLI is an answer, not a failure.
-// ceiling: POSIX only. A Windows install puts `claude` on PATH as a `.cmd` shim, which
-// execFile cannot run without a shell; a shim-aware lookup is the upgrade when Windows
-// is supported.
+// The real probe: an argument array, never a shell string, so nothing in a binary name or an
+// argument can be interpreted as a command. It resolves for every outcome; a missing CLI is an
+// answer, not a failure. ceiling: POSIX only. A Windows install puts `claude` on PATH as a
+// `.cmd` shim, which execFile cannot run without a shell; a shim-aware lookup is the upgrade
+// when Windows is supported.
 export function nodeCliProbe(binary, args, timeoutMs) {
     return new Promise((resolve) => {
         execFile(binary, [...args], { timeout: timeoutMs, maxBuffer: probeOutputMax, windowsHide: true }, (error, stdout) => {

package/dist/slices/settings/keys.js

@@ -1,17 +1,16 @@
 import { providerById } from "./model.js";
 import { deleteKey, hasKey, keyOf, upsertKey } from "./repo.js";
-// `logic/02` step 1 says the field shows the key masked and points at
-// `mockup/03-settings.md`, which draws it with nothing legible in it; the scenario's own
-// invariant is that keys never appear outside a provider call. So the mask is a
-// constant: it carries no character of the key and not even its length. Every response
-// that reports a stored key reports this string and nothing else about the value.
+// The Settings field shows a stored key masked, with nothing legible in it, and a key never
+// appears outside a provider call. So the mask is a constant: it carries no character of
+// the key and not even its length. Every response that reports a stored key reports this
+// string and nothing else about the value.
 export const keyMask = "••••••••••••";
 export function keyStatus(deps, provider) {
     const stored = hasKey(deps.db, provider);
     return { provider, hasKey: stored, masked: stored ? keyMask : null };
 }
-// `logic/02` step 1: trimmed, stored as given, overwriting any previous one. No format
-// check and no test call (§Q11, §Q17, §Q18).
+// Trimmed, stored as given, overwriting any previous one. No format
+// check and no test call.
 export function saveProviderKey(deps, provider, key) {
     if (providerById(provider).auth === "cli") {
         return { ok: false, reason: "cli-provider" };
@@ -37,9 +36,9 @@ export function removeProviderKey(deps, provider) {
     }
     return deleteKey(deps.db, provider) ? { ok: true } : { ok: false, reason: "absent" };
 }
-// `logic/02` step 7: the key is read at the moment an attempt starts. This reads the row
+// The key is read at the moment an attempt starts. This reads the row
 // every time and hands back a plain string, so an attempt holds the value it started
-// with and a save or a remove landing mid-run reaches the next attempt only (§Q16).
+// with and a save or a remove landing mid-run reaches the next attempt only.
 export function keyForAttempt(deps, provider) {
     if (providerById(provider).auth === "cli") {
         return { ok: false, reason: "cli-provider" };

package/dist/slices/settings/model.js

@@ -1,9 +1,9 @@
-// The provider catalogue and the settings domain types (02-models, `logic/02`).
+// The provider catalogue and the settings domain types.
 // The three families are the three ports, so the set is named beside them.
 export { providerFamilies } from "../../kernel/ports/model.js";
-// The supported set is `05-dependencies` External services. OpenAI ships two adapters
-// with two ids, one per family: `provider_keys.provider` is the primary key, and a row
-// per family is what lets a user key TTS without keying image generation.
+// The supported set. OpenAI ships two adapters with two ids, one per family:
+// `provider_keys.provider` is the primary key, and a row per family is what lets a user key TTS
+// without keying image generation.
 export const providerIds = [
     "openrouter",
     "claude-code",
@@ -49,6 +49,6 @@ export function providerById(id) {
     }
     return found;
 }
-// uiux §Q19: the theme override the Appearance control writes.
+// The theme override the Appearance control writes.
 export const appearances = ["system", "light", "dark"];
 export const defaultSettings = { silenceGapSeconds: 3, appearance: "system" };

package/dist/slices/settings/readiness.js

@@ -1,10 +1,9 @@
 import { cliReadiness } from "./cli-status.js";
 import { providers } from "./model.js";
 import { keyedProviders } from "./repo.js";
-// `logic/02` step 5 and §Q135: every supported provider is listed, keyed or not, found
-// or not, so Play can grey one out with a reason instead of hiding it. A keyed provider
-// is ready when a key is stored; a CLI provider when its binary answers. Readiness is
-// computed per request and nothing about a CLI is stored.
+// Every supported provider is listed, keyed or not, found or not, so Play can grey one out with
+// a reason instead of hiding it. A keyed provider is ready when a key is stored; a CLI provider
+// when its binary answers. Readiness is computed per request and nothing about a CLI is stored.
 export async function providerStatuses(deps) {
     const keyed = keyedProviders(deps.db);
     return await Promise.all(providers.map(async (provider) => ({

package/dist/slices/settings/repo.js

@@ -20,7 +20,7 @@ export function deleteKey(db, provider) {
     return Number(result.changes) > 0;
 }
 // The one place a key value leaves the database. Every caller reads it for a single
-// provider call and holds it no longer (`logic/02` §Q16). Nothing under `edge/` calls
+// provider call and holds it no longer. Nothing under `edge/` calls
 // this: a route asks the two functions below, which never select the `key` column.
 export function keyOf(db, provider) {
     const row = db.prepare("SELECT key FROM provider_keys WHERE provider = ?").get(provider);

package/dist/slices/settings/voices.js

@@ -3,10 +3,9 @@ import { providerById } from "./model.js";
 import { deleteVoice, insertVoice, listVoices } from "./repo.js";
 export const voiceNameMax = 200;
 export const voiceIdMax = 200;
-// `logic/02` step 3: a non-empty name and a non-empty voice ID, the ID unique within its
-// provider, names free to repeat. Nothing is verified against the provider - a wrong ID
-// is discovered when the audio stage uses it (§Q14), which is why a key is not required
-// here either.
+// A non-empty name and a non-empty voice ID, the ID unique within its provider, names free to
+// repeat. Nothing is verified against the provider - a wrong ID is discovered when the audio
+// stage uses it, which is why a key is not required here either.
 export function addVoice(deps, draft) {
     if (providerById(draft.provider).family !== "tts") {
         return { ok: false, reason: "not-a-tts-provider" };

package/dist/slices/storage/asset-name.js

@@ -3,8 +3,8 @@
 // draws, and `downloads.ts` reads the disk: importing it into the SPA would drag
 // `node:fs` and the zip encoder into the browser bundle. Nothing here touches IO.
 // An output's role is its asset name; images add their place in the slideshow, and the
-// instructions add their stage, those being the two roles a project holds more than one of
-// (logic/06 step 4 and logic/07 step 4 both store what the stage sent).
+// instructions add their stage, those being the two roles a project holds more than one of -
+// research and the article each store what they sent.
 export function assetOf(output) {
     const asset = output.role.replaceAll("_", "-");
     if (output.role === "instructions") {

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

@@ -9,9 +9,8 @@ export function deleteProject(deps, projectId) {
     if (derive(stagesOf(deps.db, projectId)) === "running") {
         return { ok: false, reason: "running" };
     }
-    // Files first, rows second. A folder that would not go leaves the project listed, which
-    // is what `logic/14`'s unhappy path asks for; rows removed first would leave the files
-    // orphaned under a project nothing names.
+    // Files first, rows second. A folder that would not go leaves the project listed; rows
+    // removed first would leave the files orphaned under a project nothing names.
     const dir = projectDir(deps.paths, projectId);
     try {
         rmSync(dir, { recursive: true, force: true });
@@ -25,8 +24,7 @@ export function deleteProject(deps, projectId) {
     }
     // Stages, attempts, pieces and outputs go with it: every one of those tables declares
     // ON DELETE CASCADE on the project, and the connection runs with foreign keys on
-    // (kernel/db/index.ts). The invariant of `logic/14` is that a deleted project leaves no
-    // files and no rows.
+    // (kernel/db/index.ts). A deleted project leaves no files and no rows.
     deps.db.prepare("DELETE FROM projects WHERE id = ?").run(projectId);
     return { ok: true };
 }

package/dist/slices/storage/downloads.js

@@ -36,7 +36,7 @@ export function slugOf(title) {
 // `assetOf` moved to asset-name.ts so the SPA can build the same URLs; it is still part
 // of this module's surface, because a download name is built from it.
 export { assetOf };
-// logic/14 §Q116: "single files as `<title-slug>-<asset>.<ext>`".
+// "single files as `<title-slug>-<asset>.<ext>`".
 export function downloadName(slug, output) {
     return `${slug}-${assetOf(output)}${extname(output.path)}`;
 }
@@ -64,7 +64,7 @@ export function findDownload(deps, projectId, asset) {
         },
     };
 }
-// logic/14 §Q116: "download all" images as `<title-slug>-images.zip`, thumbnail included.
+// "download all" images as `<title-slug>-images.zip`, thumbnail included.
 export function imagesZip(deps, projectId) {
     const title = projectTitle(deps.db, projectId);
     if (title === undefined) {
@@ -78,11 +78,11 @@ export function imagesZip(deps, projectId) {
         }
         const path = outputPath(deps.paths, projectId, output.path);
         if (sizeOf(path) === undefined) {
-            // A missing file is the project page's problem per logic/14; the rest still zips.
+            // A missing file is the project page's problem; the rest still zips.
             continue;
         }
         // Images are already compressed formats, so deflating them costs time and saves
-        // nothing. ceiling: 60 images (logic/05 §Q39) are read into memory at once; a set
+        // nothing. ceiling: 60 images are read into memory at once; a set
         // large enough to hurt would move to fflate's streaming Zip.
         entries[`${slug}-${assetOf(output)}${extname(output.path)}`] = [
             readFileSync(path),