@gentbajko/slopify 0.1.0 → 0.3.0

package/dist/adapters/llm/codex.js

@@ -5,7 +5,7 @@ import { cliEvent, cliShaped, endedWithout, promptOf } from "./run-cli.js";
 import { lines } from "./sse-lines.js";
 // The local-agent adapter for the Codex CLI. Same shape as Claude Code's and a different
 // vocabulary: Codex writes a JSONL thread of `thread.started`, `item.*` and `turn.*`
-// events. No key here either - the CLI's own login authenticates it (`logic/02` §Q135).
+// events. No key here either - the CLI's own login authenticates it.
 export const codexBinary = "codex";
 // ceiling: a fixed list. `codex` has no offline command that prints the models an account
 // may use - `codex doctor` reports the install, not the catalogue, and the model refresh
@@ -16,13 +16,13 @@ export const codexModels = [
     { id: "gpt-5.1-codex-max", name: "GPT-5.1 Codex Max" },
     { id: "gpt-5.6-sol", name: "GPT-5.6 Sol" },
 ];
-// `codex exec --help` (0.149.1) for the flags. `-c web_search=<mode>` is a TOML override,
-// and the binary's own error names the modes: "unknown variant `bogus`, expected one of
-// `disabled`, `cached`, `indexed`, `live`". `live` is the grounded mode `logic/06` asks
-// for and `disabled` is what every other stage runs under, so no stage grounds itself by
-// accident. `--ephemeral` keeps no session file, `--skip-git-repo-check` lets it run in
-// the data directory, and the quotes in the value are part of the argv element because
-// the override is parsed as TOML, where a bare `live` is not a string.
+// `codex exec --help` (0.149.1) for the flags. `-c web_search=<mode>` is a TOML override, and
+// the binary's own error names the modes: "unknown variant `bogus`, expected one of `disabled`,
+// `cached`, `indexed`, `live`". `live` is the grounded mode research asks for and `disabled` is
+// what every other stage runs under, so none grounds itself by accident. `--ephemeral` keeps no
+// session file, `--skip-git-repo-check` lets it run in the data directory, and the quotes in
+// the value are part of the argv element because the override is parsed as TOML, where a bare
+// `live` is not a string.
 export function codexArgs(req) {
     return [
         "exec",
@@ -72,10 +72,9 @@ export function codexLlm(deps) {
                 }
                 if (event.type === "turn.completed") {
                     const { usage } = cliShaped(binary, turnCompleted, event.value);
-                    // ceiling: Codex reports no stop reason, so the continuation loop of
-                    // `logic/07` §Q59 cannot tell a finished answer from one cut at the output
-                    // limit for this provider. A `--output-schema` run would, at the cost of
-                    // constraining every stage's answer.
+                    // ceiling: Codex reports no stop reason, so the continuation loop cannot tell a
+                    // finished answer from one cut at the output limit. A `--output-schema` run
+                    // would, at the cost of constraining every stage's answer.
                     yield { type: "done", usage: usageOf(usage), finishReason: null };
                     return;
                 }
@@ -101,8 +100,8 @@ export function codexLlm(deps) {
             run.kill();
         }
         // A cancelled run ends its stream the same way an exhausted one does: the child was
-        // killed, so stdout simply stopped. `logic/13` §Q112 says an aborted call counts
-        // nothing, so it must not be reported as the provider failing.
+        // killed, so stdout simply stopped. An aborted call counts as nothing, so it must not
+        // be reported as the provider failing.
         req.signal.throwIfAborted();
         // The stream ended with neither a completed turn nor a failure.
         throw providerError({
@@ -113,7 +112,7 @@ export function codexLlm(deps) {
     return {
         id: "codex",
         // ceiling: one `item.completed` per whole message rather than per token, same as the
-        // other CLI. Enough for the idle timeout of `logic/01` §Q62 to see life on the stream.
+        // other CLI. Enough for the idle timeout to see life on the stream.
         capabilities: { streams: true, reportsUsage: true, webSearch: true },
         models: () => Promise.resolve(codexModels),
         complete,

package/dist/adapters/llm/openrouter.js

@@ -3,9 +3,8 @@ import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
 import { retryAfter } from "../retry-after.js";
 import { sseData } from "./sse-lines.js";
-// The HTTP gateway adapter (01-architecture Module boundaries). `fetch` plus the line
-// reader beside this file, no SDK: 05-dependencies records global `fetch` at rung 3 and
-// the reader at rung 6, so nothing here is worth a dependency.
+// The HTTP gateway adapter: the platform's own `fetch` plus the line reader beside this
+// file, no SDK. Neither is worth a dependency.
 export const openRouterBase = "https://openrouter.ai/api/v1";
 // OpenRouter ranks apps by these two headers; they carry no user data.
 const appHeaders = {
@@ -13,7 +12,7 @@ const appHeaders = {
     "X-Title": "Slopify",
 };
 // A wire payload is narrowed, never cast: everything unlisted is dropped at the seam so
-// no vendor shape can leak past this file (01-architecture §Q10, §Q33).
+// no vendor shape can leak past this file.
 const modelList = z.object({
     data: z.array(z.object({ id: z.string(), name: z.string().optional() })),
 });
@@ -46,9 +45,9 @@ export function openRouterLlm(deps) {
                 })),
                 stream: true,
                 // The usage-accounting flag: without it the final chunk carries no token counts
-                // and the Usage page would have nothing to count (`logic/16`).
+                // and the Usage page would have nothing to count.
                 usage: { include: true },
-                // `logic/06` §Q47: web grounding is asked for explicitly. OpenRouter runs the
+                // Web grounding is asked for explicitly. OpenRouter runs the
                 // search itself, so the plugin works whatever model was picked.
                 ...(req.webSearch === true ? { plugins: [{ id: "web" }] } : {}),
             }),
@@ -86,8 +85,8 @@ export function openRouterLlm(deps) {
             }
             if (choice?.finish_reason !== undefined && choice.finish_reason !== null) {
                 // It arrives on the last choice chunk, one frame before the usage frame, so it is
-                // held rather than read off whichever chunk happens to be last (`logic/07` §Q59
-                // reads it to tell a finished article from a truncated one).
+                // held rather than read off whichever chunk happens to be last - the continuation
+                // loop reads it to tell a finished article from a truncated one.
                 finishReason = choice.finish_reason;
             }
             if (chunk.usage !== undefined && chunk.usage !== null) {
@@ -131,7 +130,7 @@ export function openRouterLlm(deps) {
     };
 }
 function headers(key) {
-    // `logic/02` §Q13: an attempt that finds no key fails rather than calling anonymously
+    // An attempt that finds no key fails rather than calling anonymously
     // and being told off by the provider in words the user cannot act on. `missing_key`
     // rather than `auth` because the same rule makes it terminal: there is nothing to
     // retry until the user saves a key, and the wrapper is where that is decided.
@@ -140,8 +139,7 @@ function headers(key) {
     }
     return { Authorization: `Bearer ${key}`, ...appHeaders };
 }
-// Only the adapter can read a vendor's status code, so only the adapter names the kind;
-// the attempt wrapper maps it and nothing downstream classifies again (03-conventions).
+// Only the adapter sees the vendor's status code, so only the adapter names the kind.
 function kindOf(status) {
     if (status === 401 || status === 403) {
         return "auth";
@@ -149,16 +147,15 @@ function kindOf(status) {
     if (status === 429) {
         return "rate_limit";
     }
-    // ceiling: everything else is `other` and is retried. 400 and 402 will fail the same
-    // way four times over; a terminal kind for "this request will never work" would have to
-    // be added to the port's error contract first, which is not this adapter's to widen.
+    // ceiling: everything else is `other` and is retried, so a 400 or a 402 fails the same
+    // way four times over. A terminal "this will never work" kind has to reach the port's
+    // error contract first, which is not this adapter's to widen.
     return "other";
 }
 async function failure(response) {
     const text = await response.text().catch(() => "");
     const parsed = errorBody.safeParse(safeJson(text));
-    // The provider's own words, verbatim, through the same redactor the wrapper uses: an
-    // error body is free to quote the key back and this is the first place it is held.
+    // The provider's own words, through the redactor - an error body may quote the key back.
     const message = redact(parsed.success ? parsed.data.error.message : text.trim() || response.statusText);
     const retryAfterMs = retryAfter(response.headers.get("retry-after"));
     return providerError({

package/dist/adapters/llm/run-cli.js

@@ -8,12 +8,11 @@ import { providerError } from "../../kernel/ports/model.js";
 // buries its reason in the first line of a long report.
 export const stderrMax = 8192;
 export function nodeRunCli(binary, args, signal) {
-    // An argument array, never a shell string: a prompt carrying backticks, `$(...)`,
-    // quotes or newlines is one argv element and nothing in it can become a command.
-    // stdin is /dev/null because `codex exec` appends piped stdin to the prompt, and a pipe
-    // nobody closes would leave it waiting for an EOF that never comes.
-    // `signal` is how the child dies: Node sends it SIGTERM when the stage is cancelled, so
-    // no agent session outlives the run that started it (`logic/13`).
+    // An argument array, never a shell string: a prompt carrying backticks, `$(...)`, quotes or
+    // newlines is one argv element and nothing in it can become a command. stdin is /dev/null
+    // because `codex exec` appends piped stdin to the prompt, and a pipe nobody closes would
+    // leave it waiting for an EOF that never comes. `signal` is how the child dies: Node sends it
+    // SIGTERM when the stage is cancelled, so no agent session outlives the run that started it.
     const child = spawn(binary, [...args], {
         signal,
         stdio: ["ignore", "pipe", "pipe"],
@@ -60,16 +59,15 @@ export function nodeRunCli(binary, args, signal) {
     };
 }
 // ceiling: both CLIs take one prompt string, so a system or assistant turn is flattened
-// into it under a header rather than being sent as its own message. Claude Code's
-// `--append-system-prompt` is the upgrade if a stage ever needs a real system turn; today
-// `logic/06` and `logic/07` each compose exactly one user message.
+// into it under a header. Claude Code's `--append-system-prompt` is the upgrade if a stage
+// ever needs a real system turn; today research and the article each compose one message.
 export function promptOf(messages) {
     return messages
         .map((message) => message.role === "user" ? message.content : `[${message.role}]\n${message.content}`)
         .join("\n\n");
 }
-// A bare non-zero exit tells the user nothing, so whatever the CLI put on stderr is what
-// the stage shows (`logic/01` unhappy paths: the provider's error text verbatim).
+// A bare non-zero exit tells the user nothing, so the stage shows whatever the CLI put on
+// stderr - the provider's error text, verbatim.
 export function endedWithout(binary, ended, stderr) {
     const said = redact(stderr.trim());
     const how = ended.error === null

package/dist/adapters/llm/sse-lines.js

@@ -1,7 +1,6 @@
 // Bytes off a socket or off a child's stdout, turned into the units above them. One file
 // for both because OpenRouter's SSE and the two CLIs' JSONL differ only in what a line
-// means, and 05-dependencies records the decision: global `fetch` at rung 3, this reader
-// at rung 6, no SDK for any of the three providers.
+// means, and none of the three providers is worth an SDK.
 // A chunk boundary lands wherever the network or the pipe put it: between two lines, in
 // the middle of one, or inside a multi-byte character. TextDecoder's streaming mode holds
 // back the tail of a split UTF-8 sequence instead of emitting a replacement character,

package/dist/adapters/retry-after.js

@@ -1,10 +1,10 @@
-// `logic/01` §Q4: a 429 naming a Retry-After replaces the fixed backoff for that wait.
-// RFC 9110 allows seconds or an HTTP date; `Date.parse` is the platform's own reader for
-// the second form, so no date parsing is written here.
+// A 429 naming a Retry-After replaces the fixed backoff for that wait. RFC 9110 allows seconds
+// or an HTTP date; `Date.parse` is the platform's own reader for the second form, so no date
+// parsing is written here.
 //
-// It sits beside the adapters rather than inside one because the rule is the retry
-// policy's, not any provider's: four adapters read the same header off the same kind of
-// response. Nothing else is shared between them.
+// It sits beside the adapters rather than inside one because the rule is the retry policy's,
+// not any provider's: four adapters read the same header off the same kind of response. Nothing
+// else is shared between them.
 export function retryAfter(header) {
     if (header === null) {
         return undefined;

package/dist/adapters/tts/cartesia.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
 import { retryAfter } from "../retry-after.js";
-// The HTTP gateway adapter for Cartesia (01-architecture Module boundaries). `fetch` and
+// The HTTP gateway adapter for Cartesia. `fetch` and
 // nothing else; `/tts/bytes` streams the audio it renders, so the response body is
 // already the stream the port asks for.
 export const cartesiaBase = "https://api.cartesia.ai";
@@ -12,7 +12,7 @@ export const cartesiaBase = "https://api.cartesia.ai";
 export const cartesiaVersion = "2026-03-01";
 export const cartesiaModel = "sonic-3.5";
 // mp3 is the port's container; `bit_rate` is required for it and `sample_rate` fixes the
-// rate the concatenation of `logic/08` step 4 then keeps.
+// rate the concatenation then keeps.
 const outputFormat = { container: "mp3", bit_rate: 128_000, sample_rate: 44_100 };
 // The structured error of API version 2026-03-01 and newer.
 const errorBody = z.object({
@@ -33,7 +33,7 @@ export function cartesiaTts(deps) {
                     "Cartesia-Version": cartesiaVersion,
                     "Content-Type": "application/json",
                 },
-                // `logic/08` §Q69: no pre-check on length; Cartesia's own limit surfaces as its
+                // No pre-check on length; Cartesia's own limit surfaces as its
                 // error. `language` is left out so the model reads it off the transcript.
                 body: JSON.stringify({
                     model_id: cartesiaModel,
@@ -54,7 +54,7 @@ export function cartesiaTts(deps) {
 }
 function keyOf(deps) {
     const key = deps.key();
-    // `logic/02` §Q13: an absent key is terminal, so it never becomes a request.
+    // An absent key is terminal, so it never becomes a request.
     if (key === undefined || key === "") {
         throw providerError({ kind: "missing_key", message: "no Cartesia key is stored" });
     }
@@ -78,7 +78,7 @@ async function failure(response, voiceId) {
     const retryAfterMs = retryAfter(response.headers.get("retry-after"));
     return providerError({
         kind: kindOf(response.status),
-        // `logic/02` §Q14: `voice_not_found` has to say which voice was asked for; Cartesia's
+        // `voice_not_found` has to say which voice was asked for; Cartesia's
         // own message does not repeat the id.
         message: `Cartesia answered ${response.status} for voice ${voiceId}: ${message}`,
         ...(retryAfterMs === undefined ? {} : { retryAfterMs }),

package/dist/adapters/tts/elevenlabs.js

@@ -2,17 +2,16 @@ import { z } from "zod";
 import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
 import { retryAfter } from "../retry-after.js";
-// The HTTP gateway adapter for ElevenLabs (01-architecture Module boundaries). `fetch`
-// and nothing else: 05-dependencies records global `fetch` at rung 3, and the response
-// body already is the `ReadableStream<Uint8Array>` the port asks for, so an SDK would buy
-// nothing but a dependency.
+// The HTTP gateway adapter for ElevenLabs: the platform's own `fetch` and nothing else. The
+// response body already is the `ReadableStream<Uint8Array>` the port asks for, so an SDK
+// would buy nothing but a dependency.
 export const elevenLabsBase = "https://api.elevenlabs.io/v1";
 // The /stream endpoint rather than the plain one: `capabilities.streams` is true, and the
 // attempt wrapper measures its 120 s as an idle timeout between chunks only when bytes
-// keep arriving (`logic/01` §Q62).
+// keep arriving.
 export const elevenLabsModel = "eleven_multilingual_v2";
-// mp3 at the port's container, 44.1 kHz, 128 kbps: `kernel/ports/tts.ts` fixes mp3 and
-// `logic/08` step 4 keeps the provider's own sample rate through the concatenation.
+// mp3 at the port's container, 44.1 kHz, 128 kbps: `kernel/ports/tts.ts` fixes mp3 and the
+// concatenation keeps the provider's own sample rate.
 export const elevenLabsFormat = "mp3_44100_128";
 // A wire payload is narrowed, never cast. `detail` is an object on a handled failure and
 // a string on the framework's own; anything else falls back to the raw text.
@@ -32,7 +31,7 @@ export function elevenLabsTts(deps) {
                 method: "POST",
                 signal: req.signal,
                 headers: { "xi-api-key": keyOf(deps), "Content-Type": "application/json" },
-                // `logic/08` §Q69: no pre-check on length. A text past the model's limit comes
+                // No pre-check on length. A text past the model's limit comes
                 // back as the provider's own 400 and that is what the stage shows.
                 body: JSON.stringify({ text: req.text, model_id: elevenLabsModel }),
             });
@@ -48,15 +47,13 @@ export function elevenLabsTts(deps) {
 }
 function keyOf(deps) {
     const key = deps.key();
-    // `logic/02` §Q13: an attempt that finds no key fails rather than calling anonymously.
-    // `missing_key` rather than `auth` because the same rule makes it terminal.
+    // `missing_key`, not `auth`, because that rule makes it terminal.
     if (key === undefined || key === "") {
         throw providerError({ kind: "missing_key", message: "no ElevenLabs key is stored" });
     }
     return key;
 }
-// Only the adapter can read a vendor's status code, so only the adapter names the kind;
-// the attempt wrapper maps it and nothing downstream classifies again (03-conventions).
+// Only the adapter sees the vendor's status code, so only the adapter names the kind.
 function kindOf(status) {
     if (status === 401 || status === 403) {
         return "auth";
@@ -64,21 +61,19 @@ function kindOf(status) {
     if (status === 429) {
         return "rate_limit";
     }
-    // ceiling: everything else is `other` and is retried, so a text past the character
-    // limit fails the same way four times over. A terminal kind for "this request will
-    // never work" would have to be added to the port's error contract first, which is not
-    // this adapter's to widen.
+    // ceiling: everything else is `other` and is retried, so a text past the character limit
+    // fails the same way four times over. A terminal "this will never work" kind has to reach the
+    // port's error contract first, which is not this adapter's to widen.
     return "other";
 }
 async function failure(response, voiceId) {
     const text = await response.text().catch(() => "");
-    // The provider's own words, verbatim, through the same redactor the wrapper uses: an
-    // error body is free to quote the key back and this is the first place it is held.
+    // The provider's own words, through the redactor - an error body may quote the key back.
     const message = redact(detailOf(text) || response.statusText);
     const retryAfterMs = retryAfter(response.headers.get("retry-after"));
     return providerError({
         kind: kindOf(response.status),
-        // `logic/02` §Q14: a rejected voice ID has to be named, and it is the one part of the
+        // A rejected voice ID has to be named, and it is the one part of the
         // request the user chose. It is not secret, unlike everything else on the wire.
         message: `ElevenLabs answered ${response.status} for voice ${voiceId}: ${message}`,
         ...(retryAfterMs === undefined ? {} : { retryAfterMs }),

package/dist/adapters/tts/openai.js

@@ -2,12 +2,11 @@ import { z } from "zod";
 import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
 import { retryAfter } from "../retry-after.js";
-// The HTTP gateway adapter for OpenAI's speech endpoint (01-architecture Module
-// boundaries). `fetch` and nothing else; the response body is already the stream the port
-// asks for.
+// The HTTP gateway adapter for OpenAI's speech endpoint. `fetch` and nothing else; the response
+// body is already the stream the port asks for.
 export const openAiAudioBase = "https://api.openai.com/v1";
-// 05-dependencies lists gpt-4o-mini-tts, tts-1 and tts-1-hd; the first is the current one
-// and the cheapest of the three per character.
+// gpt-4o-mini-tts, tts-1 and tts-1-hd; the first is the current one and the cheapest of the
+// three per character.
 export const openAiTtsModel = "gpt-4o-mini-tts";
 const errorBody = z.object({
     error: z.object({ message: z.string(), code: z.string().nullish() }),
@@ -28,9 +27,9 @@ export function openAiTts(deps) {
                     Authorization: `Bearer ${keyOf(deps)}`,
                     "Content-Type": "application/json",
                 },
-                // `logic/08` §Q69: the 4096-character cap is not checked here. A longer text
-                // comes back as OpenAI's own 400 and that is what the stage shows, so a user who
-                // chose Whole text learns the limit from the provider that set it.
+                // The 4096-character cap is not checked here. A longer text comes back as OpenAI's own
+                // 400 and that is what the stage shows, so a user who chose Whole text learns the limit
+                // from the provider that set it.
                 body: JSON.stringify({
                     model: openAiTtsModel,
                     input: req.text,
@@ -53,7 +52,7 @@ function voiceOf(voiceId) {
 }
 function keyOf(deps) {
     const key = deps.key();
-    // `logic/02` §Q13: an absent key is terminal, so it never becomes a request.
+    // An absent key is terminal, so it never becomes a request.
     if (key === undefined || key === "") {
         throw providerError({ kind: "missing_key", message: "no OpenAI key is stored" });
     }
@@ -79,7 +78,7 @@ async function failure(response, voiceId) {
     const retryAfterMs = retryAfter(response.headers.get("retry-after"));
     return providerError({
         kind: kindOf(response.status),
-        // `logic/02` §Q14: the voice ID is named, so a rejected voice reads differently from
+        // The voice ID is named, so a rejected voice reads differently from
         // a rejected key.
         message: `OpenAI answered ${response.status} for voice ${voiceId}: ${message}`,
         ...(retryAfterMs === undefined ? {} : { retryAfterMs }),

package/dist/edge/http/actions.js

@@ -8,10 +8,9 @@ import { cancelProject } from "../../slices/cancel/index.js";
 import { deleteImage, editArticle, regenerateImage, rerunStage, retryStage, } from "../../slices/reruns/index.js";
 import { outputsOf } from "../../slices/storage/repo.js";
 import { onInvalid, problem, titleOf } from "./problem.js";
-// The actions `mockup/08-project.md` puts on the project header and on each stage: Cancel,
-// Retry, Re-run, Save & re-run, Regenerate one image, Delete one image. Every one of them
-// changes rows and files through a slice and then ticks the runner; the route itself
-// decides nothing (`logic/12`, `logic/13`).
+// The actions on the project header and on each stage: Cancel, Retry, Re-run, Save &
+// re-run, Regenerate one image, Delete one image. Every one changes rows and files through
+// a slice and then ticks the runner; the route itself decides nothing.
 const idParam = z.object({
     id: z
         .string()
@@ -44,12 +43,12 @@ const details = {
     "no-project": "No project has that id.",
     "unknown-image": "This project has no image with that id.",
     "empty-article": "An article cannot be saved empty.",
-    // logic/12 preconditions: "no stage of the project is `running` (§Q106)".
+    // The precondition on every re-run: no stage of the project is `running`.
     running: "This project is still running. Cancel it or wait for it to finish.",
     "not-rerunnable": "Only a stage that has finished, failed, or been canceled can be re-run.",
     "not-retryable": "Only a failed or canceled stage can be retried.",
     "no-article": "This project has no article to edit yet.",
-    // logic/09 §Q75 and logic/12's invariant: "at least one image always remains".
+    // At least one image always remains.
     "last-image": "At least one image must remain, so the last one cannot be deleted.",
 };
 // The return type is inferred so Hono keeps the route types the SPA's client is
@@ -79,8 +78,8 @@ export function actionRoutes(deps) {
             outputs: outputsOf(deps.db, projectId),
         };
     };
-    // Every re-run action ends the same way: the rows are written, then the runner is
-    // asked to look at the project. `logic/12` step 9 does the rest by itself.
+    // Every re-run action ends the same way: the rows are written, then the runner is asked
+    // to look at the project. The cascade does the rest by itself.
     const started = (c, projectId, result) => {
         if (!result.ok) {
             return problem(c, {
@@ -99,7 +98,7 @@ export function actionRoutes(deps) {
         if (!result.ok) {
             return problem(c, { status: 404, title: titleOf(404), detail: details["no-project"] });
         }
-        // No tick: §Q111 leaves a canceled project sitting until the user retries a stage.
+        // No tick: a canceled project sits until the user retries a stage.
         return c.json({ ...view(id), canceled: result.canceled });
     })
         .post("/:id/stages/:kind/retry", zValidator("param", stageParam, onInvalid), (c) => {

package/dist/edge/http/app.js

@@ -24,8 +24,8 @@ function apiRoutes(deps, startedAt) {
     }))
         .route("/staging", stagingRoutes(deps))
         .route("/projects", projectRoutes(deps))
-        // The actions of `logic/12` and `logic/13` sit on the same prefix as the project
-        // itself; they are their own router because they are their own concern.
+        // The re-run and cancel actions sit on the same prefix as the project itself; they
+        // are their own router because they are their own concern.
         .route("/projects", actionRoutes(deps))
         .route("/prompts", promptRoutes(deps))
         .route("/entries", entryRoutes(deps))
@@ -46,7 +46,7 @@ export function createApp(deps) {
         .route("/api", apiRoutes(deps, startedAt))
         .get("/api/events/global", (c) => streamSSE(c, (stream) => deps.hub.subscribeGlobal(stream, c.req.raw.signal)))
         .get("/api/events/projects/:id", (c) => streamSSE(c, (stream) => deps.hub.subscribe(c.req.param("id"), stream, c.req.raw.signal)))
-        // Files are served by URL, not through the API (02-models Boundaries).
+        // Files are served by URL, not through the API.
         .route("/", fileRoutes(deps))
         // The API answers for its whole prefix, so an unknown endpoint is a problem+json 404
         // rather than the SPA's index.html with a 200.

package/dist/edge/http/entries.js

@@ -5,7 +5,7 @@ import { entryCategories, entryModes } from "../../slices/library/model.js";
 import { listEntries } from "../../slices/library/repo.js";
 import { createEntry, removeEntry, updateEntry } from "../../slices/library/save.js";
 import { onInvalid } from "./problem.js";
-// `logic/15` §Q121: one rule set for prompts and entries, so one refusal mapping too.
+// One rule set for prompts and entries, so one refusal mapping too.
 import { refused } from "./prompts.js";
 const idParam = z.object({
     id: z

package/dist/edge/http/projects.js

@@ -44,7 +44,7 @@ export function projectRoutes(deps) {
     });
     return (new Hono()
         .post("/", zValidator("json", runDraftSchema, onInvalid), (c) => {
-        // logic/04 §Q34: the bodies are read here, at the click, so an edit made since the
+        // The bodies are read here, at the click, so an edit made since the
         // prompt was selected is the one that runs.
         const picked = pickTemplates(deps.db, c.req.valid("json"));
         const admitted = admit({
@@ -63,13 +63,13 @@ export function projectRoutes(deps) {
             });
         }
         // Rendered from the values admit() has trimmed, so the stored text carries no
-        // padding the user did not intend (logic/03 step 4 and step 5).
+        // padding the user did not intend.
         const { project } = startRun(storage, admitted.draft, renderPicked(picked, admitted.draft.values));
-        // logic/16 step 2: one event per project created. record() swallows its own
+        // One event per project created. record() swallows its own
         // failures, so a broken telemetry write cannot cost the user the run.
         record(telemetry, "project.created", {});
         deps.flushSoon();
-        // logic/04 step 6: the run starts only once the project is committed.
+        // The run starts only once the project is committed.
         deps.runner.tick(project.id);
         // Read back after the tick, not from the rows startRun built: the runner has
         // already claimed every eligible stage, and a body that paired status "running"
@@ -101,8 +101,8 @@ export function projectRoutes(deps) {
             outputs: outputsOf(deps.db, project.id),
         });
     })
-        // `logic/14` step 4. Irreversible, and only from the app: 07 Projects puts the
-        // confirmation dialog in front of it.
+        // Irreversible, and only from the app: the Projects screen puts a confirmation
+        // dialog in front of it.
         .delete("/:id", zValidator("param", idParam, onInvalid), (c) => {
         const result = deleteProject(storageForDelete, c.req.valid("param").id);
         if (result.ok) {
@@ -122,7 +122,7 @@ const deleteStatus = {
 };
 const deleteDetails = {
     "no-project": "No project has that id.",
-    // §Q117: the run has to be stopped before its files can go.
+    // The run has to be stopped before its files can go.
     running: "This project is still running. Cancel the run first.",
     files: "Some of this project's files could not be removed.",
 };

package/dist/edge/http/prompts.js

@@ -13,7 +13,7 @@ const idParam = z.object({
         .regex(/^[0-9A-Za-z_-]+$/),
 });
 // Shape only. The rules - trimming, emptiness, length, the slot lint - are the slice's,
-// so one set of messages reaches the editor (03-conventions).
+// so one set of messages reaches the editor.
 const promptBody = z.object({
     kind: z.enum(promptKinds),
     name: z.string(),
@@ -25,7 +25,7 @@ export function promptRoutes(deps) {
     const library = { db: deps.db, ids: deps.ids, clock: deps.clock };
     return (new Hono()
         // Every kind in one list: 04 Prompts filters by tab, and Duplicate needs the body it
-        // is copying (`logic/15` step 3).
+        // is copying.
         .get("/", (c) => c.json({ prompts: listPrompts(deps.db) }))
         .post("/", zValidator("json", promptBody, onInvalid), (c) => {
         const result = createPrompt(library, c.req.valid("json"));
@@ -35,15 +35,15 @@ export function promptRoutes(deps) {
         const result = updatePrompt(library, c.req.valid("param").id, c.req.valid("json"));
         return result.ok ? c.json(result.value) : refused(c, result, "prompt");
     })
-        // `logic/15` §Q123: a project holds its own rendered text, so nothing cascades and a
+        // A project holds its own rendered text, so nothing cascades and a
         // template used by past projects is deleted like any other.
         .delete("/:id", zValidator("param", idParam, onInvalid), (c) => {
         const result = removePrompt(library, c.req.valid("param").id);
         return result.ok ? c.body(null, 204) : refused(c, result, "prompt");
     }));
 }
-// One refusal mapping for both libraries: `logic/15` §Q121 puts one rule set over
-// prompts and entries, so entryRoutes shares this rather than mirroring it.
+// One refusal mapping for both libraries: prompts and entries share one rule set, so
+// entryRoutes reuses this rather than mirroring it.
 export function refused(c, failure, noun) {
     switch (failure.reason) {
         case "invalid":
@@ -53,7 +53,7 @@ export function refused(c, failure, noun) {
                 detail: `This ${noun} cannot be saved; the listed fields need attention.`,
                 extensions: { fields: failure.fields },
             });
-        // §Q122: the name is refused against a row that exists, and the form marks the field.
+        // The name is refused against a row that exists, and the form marks the field.
         case "duplicate-name":
             return problem(c, {
                 status: 409,

package/dist/edge/http/providers.js

@@ -6,9 +6,9 @@ import { providerById, providerIds } from "../../slices/settings/model.js";
 import { providerStatuses } from "../../slices/settings/readiness.js";
 import { onInvalid, problem, titleOf } from "./problem.js";
 const providerParam = z.object({ id: z.enum(providerIds) });
-// ceiling: `logic/02` §Q11 forbids any format check, so the only thing said about the
-// value is that it is a string of a length a key could plausibly have. Raise the bound
-// if a provider ever issues something longer.
+// ceiling: no format check is allowed on a key, so the only thing said about the value is
+// that it is a string of a length a key could plausibly have. Raise the bound if a provider
+// ever issues something longer.
 const keyBody = z.object({ key: z.string().min(1).max(4096) });
 // The return type is inferred so Hono keeps the route types the SPA's client is
 // generated from; see stagingRoutes.
@@ -17,7 +17,7 @@ export function providerRoutes(deps) {
     const readiness = { db: deps.db, probe: deps.probe };
     return (new Hono()
         // What Settings draws its rails from and Play its dropdowns: every provider, with
-        // the one fact that decides whether it is selectable (`logic/02` step 5, §Q135).
+        // the one fact that decides whether it is selectable.
         .get("/", async (c) => c.json({ providers: await providerStatuses(readiness) }))
         .put("/:id/key", zValidator("param", providerParam, onInvalid), zValidator("json", keyBody, onInvalid), (c) => {
         const { id } = c.req.valid("param");

package/dist/edge/http/settings.js

@@ -7,7 +7,7 @@ import { addVoice, removeVoice, voiceIdMax, voiceNameMax, voices, } from "../../
 import { onInvalid, problem, titleOf } from "./problem.js";
 const idParam = z.object({ id: z.string().min(1).max(64) });
 // Shape only. The rules - trimming, emptiness, length, the provider speaking at all -
-// are the slice's, so one set of messages reaches the form (03-conventions).
+// are the slice's, so one set of messages reaches the form.
 const voiceBody = z.object({
     provider: z.enum(providerIds),
     name: z.string(),
@@ -40,7 +40,7 @@ export function settingsRoutes(deps) {
         .post("/voices", zValidator("json", voiceBody, onInvalid), (c) => {
         const result = addVoice(voiceDeps, c.req.valid("json"));
         if (!result.ok) {
-            // `logic/02` §Q18: a voice ID already listed for its provider is a conflict with
+            // A voice ID already listed for its provider is a conflict with
             // a row that exists, which the form shows under the Voice ID input.
             return result.reason === "duplicate-voice-id"
                 ? problem(c, {

package/dist/edge/http/staging.js

@@ -10,7 +10,7 @@ import { onInvalid, problem, titleOf } from "./problem.js";
 const kindParam = z.object({ kind: z.enum(uploadableStageKinds) });
 const idParam = z.object({ id: z.string().min(1).max(64) });
 // The return type is inferred on purpose: annotating it would erase the route types the
-// SPA's client is generated from (02-models §Q27).
+// SPA's client is generated from.
 export function stagingRoutes(deps) {
     const storage = {
         db: deps.db,