toolroll 0.9.104 → 0.9.105

package/dist/flow-engine.js

@@ -1,10 +1,3 @@
-/**
- * The flow engine: moves cards through their flow's zones. Deterministic
- * and model-free — it runs in a worker's pass beside builds, files work
- * through the ordinary task door (so every approval and check a task needs
- * still applies), reads task state, posts messages through the outbox, and
- * waits for people. See flows.ts for what each zone does.
- */
 import { assignmentOf } from "./assignment.js";
 import { currentActor } from "./actor.js";
 import { activeRemote } from "./remote-run.js";
@@ -25,7 +18,6 @@ import { chooseStep, flowPersonOf, sendStep } from "./flow-send.js";
 import { parseSoul, subagentLabel } from "./subagents.js";
 import { cardTaskArchived, taskArchived } from "./task-archive.js";
 import { withStageHandoff } from "./contracts/stage-output.js";
-/** The flow's drawing, or null when it can't be read (the card then says so and waits). */
 export function flowDefinitionOf(flow) {
     try {
         return validateFlowDefinition(JSON.parse(flow.definitionJson), { stored: true });
@@ -34,12 +26,8 @@ export function flowDefinitionOf(flow) {
         return null;
     }
 }
-/** Where a card's link opens: the flow's canvas with the card selected. */
 export const flowCardHref = (flow, card) => `/flows/${flow}?card=${card}`;
-/** A reply wait that timed out with nowhere to send the card asks its owner (or the flow's owner) to move it on: the
- * card's waiting words end with this (flows-ui.ts flowCardWaitsOn reads it). */
 export const NO_REPLY_MOVE_ON = "Move the card on when you're ready.";
-/** Where a confirmed flow action may point: a flow's canvas, maybe with one card open. */
 export const FLOW_HREF = /^\/flows\/[1-9][0-9]{0,9}(\?card=[1-9][0-9]{0,9})?$/;
 const ACCEPTANCE = FLOW_ACCEPTANCE;
 function fill(template, card) {
@@ -47,12 +35,10 @@ function fill(template, card) {
 }
 const titleIn = (definition, id) => definition.stages.find(one => one.id === id)?.title ?? id;
 const flowDefinitionStage = (definition, id) => definition.stages.find(one => one.id === id);
-/** A subagent's name as its soul file gives it (its handle when the file can't be read). */
 function subagentName(mate) {
     const read = parseSoul(mate.soul);
     return read.ok ? read.soul.name : mate.handle;
 }
-/** What a subagent said when it handed a card to its person, or why it couldn't decide. */
 function handoffWords(mate, turn) {
     const read = parseSoul(mate.soul);
     const label = read.ok ? subagentLabel(read.soul) : mate.handle;
@@ -66,7 +52,6 @@ function handoffWords(mate, turn) {
     }
     return { label, said: turn.state === "failed" ? `${label} couldn't decide this one (${turn.result ?? "it didn't finish"}), so it's yours.` : `${label}: ${note || "Over to you on this one."}` };
 }
-/** Advance every active card in one project's flows. */
 export function advanceFlows(store, repo, now, options = {}) {
     const outcome = { moved: 0, filed: [], problems: [] };
     const flows = new Map();
@@ -94,8 +79,6 @@ function advanceCard(store, flow, definition, card, now, options, outcome) {
         return;
     }
     const stage = definition.stages.find(one => one.id === card.stage);
-    // A put-away task (v145, task-tidy.md) holds its card where it is, whatever the zone: nothing moves on, files, sends
-    // or notifies until the task is restored.
     if (cardTaskArchived(store, card.id)) {
         const waiting = "Its task is put away. Restore the task to continue.";
         if (card.waiting !== waiting)
@@ -103,7 +86,6 @@ function advanceCard(store, flow, definition, card, now, options, outcome) {
         return;
     }
     if (stage === undefined) {
-        // The zone was removed while the card sat in it: back to the start.
         if (store.moveFlowCard(card.id, { to: definition.start, outcome: "moved", actor: "flow", note: null, expectEntry: card.entry }, now))
             outcome.moved++;
         return;
@@ -121,8 +103,6 @@ function advanceCard(store, flow, definition, card, now, options, outcome) {
                 notifyPeople(store, card, [card.owner], null, { key: `failed:${card.entry}`, subject: `“${card.title}” went back to ${titleIn(definition, to)}`, body: `${note ?? "Its step didn't finish."} It's in ${titleIn(definition, to)} now.`, attention: true }, now);
         }
     };
-    // A time limit (v91): once a card has sat here that long, the person it waits on hears about it, once,
-    // and a Holding or "Person decides" zone can move it on.
     if (stage.limit !== undefined && stage.kind !== "wait" && stage.kind !== "done") {
         const entered = Date.parse(store.flowCardEnteredAt(card.id) ?? card.updatedAt);
         if (now.getTime() >= entered + stage.limit.minutes * 60_000) {
@@ -144,7 +124,6 @@ function advanceCard(store, flow, definition, card, now, options, outcome) {
             return;
         case "wait": {
             const wait = stage.wait ?? { for: "reply", minutes: 24 * 60 };
-            // Set hours (like 22:00–06:00): a card goes on once the clock is inside them, at once when it already is.
             if (wait.for === "hours") {
                 if (withinHours(wait, now)) {
                     onward("ok");
@@ -158,10 +137,8 @@ function advanceCard(store, flow, definition, card, now, options, outcome) {
             const entered = Date.parse(store.flowCardEnteredAt(card.id) ?? card.updatedAt);
             const words = durationWords(wait.minutes);
             if (now.getTime() < entered + wait.minutes * 60_000) {
-                // Replies are taken as they're read (flow-replies.ts), which moves the card on; until then it says what it waits for.
                 const watch = wait.for === "reply" ? store.flowMailWatch() : null;
                 const trouble = watch !== null && watch.failures > 0 && watch.lastOutcome !== null ? ` ${watch.lastOutcome}` : "";
-                // How long is on the card itself (when it moves on, in the viewer's own time); this says what for.
                 const waiting = wait.for === "time" ? "Waiting before moving on." : `Waiting for a reply.${trouble}`;
                 if (card.waiting !== waiting)
                     store.updateFlowCard(card.id, { waiting }, now);
@@ -200,9 +177,6 @@ function advanceCard(store, flow, definition, card, now, options, outcome) {
         case "approval": {
             const decider = deciderOf(stage, flow);
             const who = decider ?? "an approver";
-            // v92: a zone an active subagent staffs is its to decide first (the step pass runs it). A person hears
-            // about the card only when the subagent hands it over, can't decide, or is paused or gone.
-            // v102: on a protected project a subagent never decides; the person does.
             const mate = stage.subagent === undefined || store.approvalRules(flow.repo).protectProject ? null : store.subagentByHandle(flow.repo, stage.subagent);
             const turn = mate === null ? null : store.flowStepRun(card.id, card.entry);
             const handed = turn !== null && turn.kind === "subagent" && (turn.state === "failed" || turn.state === "passed");
@@ -214,8 +188,6 @@ function advanceCard(store, flow, definition, card, now, options, outcome) {
             }
             const handoff = handed && mate !== null ? handoffWords(mate, turn) : null;
             if (card.waiting === null || (mate !== null && card.waiting === `${subagentName(mate)} is deciding`)) {
-                // A named decider hears it alone; "anyone who approves" pages everyone who can.
-                // With a draft in front of it, the decision carries the draft itself: it can be read (and answered) where it arrives.
                 const draft = draftFor(definition, stage);
                 const text = draft === null ? undefined : card.outputs[draft.id];
                 store.enqueueNotification({
@@ -230,12 +202,10 @@ function advanceCard(store, flow, definition, card, now, options, outcome) {
             return;
         }
         case "send":
-            // What the step before produced, to the card's person in each chat app they paired and on the card; then on.
             sendStep(store, flow, definition, stage, card, now, options.evidenceRoot);
             onward("ok");
             return;
         case "choose":
-            // The same, with the zone's options as buttons: the card waits for the person's choice (chooseFlowCard).
             chooseStep(store, flow, definition, stage, card, now, options.evidenceRoot);
             return;
         case "task":
@@ -250,20 +220,15 @@ function advanceCard(store, flow, definition, card, now, options, outcome) {
         case "request":
         case "email":
         case "tool":
-            // Run by the worker's step pass (flow-steps.ts), which moves the card on.
             return;
     }
 }
 function workStage(store, flow, definition, stage, card, now, options, outcome, onward) {
-    // A build may work in another project (its zone's repo), one the flow's owner may file in; research stays in the flow's.
     const repo = stage.kind === "task" && stage.repo !== undefined ? stage.repo : flow.repo;
     if (card.task === null) {
         const report = stage.kind === "report";
-        // Waiting cards try again every pass, so a cause that's fixed (a shorter zone, a freed backlog) files the work then.
         const wait = (why) => { const waiting = `Couldn't file the work: ${why} It tries again on the next pass.`; if (card.waiting !== waiting)
             store.updateFlowCard(card.id, { waiting }, now); };
-        // The goal fits a task: the zone's words whole and the card's details whole; a value too long for the goal (a
-        // script's output) is attached instead, and the agent is given it in full (flowGoalCuts). Nothing is cut.
         const goal = flowGoal(stage.instructions ?? card.title, card, id => titleIn(definition, id));
         if (goal === null) {
             wait(`${stage.title}'s instructions are too long for a task. Open the flow and shorten them.`);
@@ -273,14 +238,10 @@ function workStage(store, flow, definition, stage, card, now, options, outcome,
             wait(`${flow.owner}, who owns this flow, can't file work in ${repo}. Choose another project for ${stage.title}, or give them access.`);
             return;
         }
-        // Filed exactly once however many passes advance this project: the card is claimed (still this entry, in this zone,
-        // with no task) in the same transaction that files its task, so another pass finds it claimed and leaves it.
         const filed = store.transact(() => {
             const fresh = store.getFlowCard(card.id);
             if (fresh === null || fresh.state !== "active" || fresh.entry !== card.entry || fresh.stage !== stage.id || fresh.task !== null)
                 return null;
-            // A card this flow's own schedule added, while the flow runs on its own (flow-unattended.ts): the grant's frozen
-            // criteria and budget, sealed here, in the same transaction. Any other card files as it always did and waits.
             const grant = unattendedCoverageFor(store, flow, fresh, repo, now);
             const kind = report ? "report" : "task";
             const made = fileTaskProposal(store, {
@@ -288,8 +249,6 @@ function workStage(store, flow, definition, stage, card, now, options, outcome,
                 repo,
                 goal,
                 filedVia: `flow:${flow.id}`,
-                // Who made the card asked for the work (an owner can be reassigned by anyone). v126: an automation's card (a
-                // delivery, a poll, a schedule, a form) files as automation, by the kind kept on the card, never by its name.
                 filedBy: { name: card.createdBy, kind: card.createdKind },
                 deliverable: report ? "report" : "branch",
                 planning: report ? "skip" : stage.planning ?? "auto",
@@ -297,7 +256,6 @@ function workStage(store, flow, definition, stage, card, now, options, outcome,
                 ...(grant?.terms.perAttemptBudgetMicrousd == null ? {} : { budgetMicrousd: grant.terms.perAttemptBudgetMicrousd }),
                 admittedRepos: [repo],
             }, now);
-            // v126: a card an outside event's delivery made gives its task a snapshot of where it came from, in this transaction.
             const snapshot = made.ok ? snapshotOf(fresh.source) : null;
             if (made.ok && snapshot !== null)
                 store.recordTaskSource(made.id, { flow: flow.id, card: fresh.id, entry: fresh.entry }, JSON.stringify(snapshot), now);
@@ -315,7 +273,6 @@ function workStage(store, flow, definition, stage, card, now, options, outcome,
         outcome.filed.push(filed.id);
         return;
     }
-    // A send back may have made a revision: follow the task's current version.
     const family = store.taskFamilyOf(card.task, [repo], false);
     const current = family?.current.id ?? card.task;
     const task = store.getTask(current);
@@ -323,7 +280,6 @@ function workStage(store, flow, definition, stage, card, now, options, outcome,
         store.updateFlowCard(card.id, { waiting: "Its task is gone. Move the card to try again." }, now);
         return;
     }
-    // A put-away task (v145, task-tidy.md) holds its card where it is: nothing moves on, files or sends until it's restored.
     if (taskArchived(store, current) || taskArchived(store, card.task)) {
         const waiting = "Its task is put away. Restore the task to continue.";
         if (card.waiting !== waiting)
@@ -331,7 +287,6 @@ function workStage(store, flow, definition, stage, card, now, options, outcome,
         return;
     }
     if (task.state === "done") {
-        // A build whose project checks failed is done but not good: it takes the failure path, like a failed build.
         if (stage.kind === "task") {
             const checks = assignmentOf(store, current, now, { principal: "operator", repos: [repo] }, options.evidenceRoot)?.receipt?.checks ?? null;
             if (checks?.status === "failed") {
@@ -348,18 +303,14 @@ function workStage(store, flow, definition, stage, card, now, options, outcome,
         if (stage.kind === "report") {
             const ref = store.lookupRef(current);
             const summary = ref === null ? null : reportSummaryFor(store, options.evidenceRoot, ref.id);
-            // {{stage.<id>.items}} and {{stage.<id>.report}}: what it found and the whole report, for the zones after it.
-            // A visit's report replaces the last visit's, so nothing stale is left behind.
             const view = ref === null || options.evidenceRoot === undefined ? null : readVerifiedReport(store, options.evidenceRoot, ref.id);
             const found = view?.ok === true ? reportFillIns(view.report) : { items: "", report: "" };
             handoff = {
-                // The summary whole (a report's summary is within TEXT_LIMITS.reportSummary bytes; an older, longer one is linked).
                 text: summary !== null && "summary" in summary ? passOn(summary.summary, TEXT_LIMITS.stageOutput, { label: `task ${current}`, href: null }).text : "The report is ready on its task.",
                 ...(found.items === "" ? {} : { items: found.items }), ...(found.report === "" ? {} : { report: found.report }),
             };
         }
         store.updateFlowCard(card.id, { outputs: withStageHandoff(card.outputs, stage.id, handoff), ...(stage.kind === "task" ? { primaryTask: current } : {}), waiting: null }, now);
-        // A "Send to me" or "Person chooses" zone next reads what this task produced: the task goes with the card there.
         const following = stage.next === null ? undefined : flowDefinitionStage(definition, stage.next);
         onward("ok", undefined, following?.kind === "send" || following?.kind === "choose" ? current : undefined);
         return;
@@ -380,11 +331,6 @@ function workStage(store, flow, definition, stage, card, now, options, outcome,
     if (waiting !== card.waiting)
         store.updateFlowCard(card.id, { waiting }, now);
 }
-/** What a flow task's goal had to cut, whole, for the agent doing it: each value its zone fills in from the card that the
- * goal doesn't hold in full. Empty when the task didn't come from a flow card or nothing was cut. Script output and
- * card text can come from outside, so the brief quotes these as untrusted data. */
-/** The most of one attached value the agent's brief carries: more than any card value holds (a whole report is at most
- * 64 KiB), so in practice an attachment is never shortened. */
 const FLOW_ATTACHED_LIMIT = 128_000;
 export function flowGoalCuts(store, taskId, goal) {
     let cuts = [];
@@ -393,9 +339,7 @@ export function flowGoalCuts(store, taskId, goal) {
     }
     catch {
         cuts = [];
-    } // context, never a reason a build can't start
-    // v126: where the work came from, from the task's own kept source (or the task it revises) — never from the card's
-    // current task link or zone, which move on. Given whole whenever the goal itself couldn't carry it.
+    }
     try {
         const kept = store.taskSourceOf(taskId);
         const snapshot = kept === null ? null : readSnapshot(kept.sourceJson);
@@ -403,7 +347,7 @@ export function flowGoalCuts(store, taskId, goal) {
         if (words !== "" && !goal.includes(words) && !cuts.some(one => one.text === words))
             cuts.push({ label: flowValueLabel("card.source"), text: words });
     }
-    catch { /* context, never a reason a build can't start */ }
+    catch { }
     return cuts;
 }
 function goalCuts(store, taskId, goal) {
@@ -420,7 +364,6 @@ function goalCuts(store, taskId, goal) {
         if (seen.has(match[1]))
             continue;
         seen.add(match[1]);
-        // An output too long to pass on is kept whole on the card (src/contracts/stage-output.ts): the agent gets it whole.
         const whole = match[2] !== undefined && match[3] === undefined ? card.attached[match[2]] : undefined;
         const text = whole ?? fillFlowText(`{{${match[1]}}}`, card);
         if (text === "" || (whole === undefined && goal.includes(text)))
@@ -429,7 +372,6 @@ function goalCuts(store, taskId, goal) {
     }
     return cuts;
 }
-/** Why a flow can't be saved as drawn: a build zone in a project its owner, or whoever saves it, may not file work in; null when none. */
 export function crossProjectProblem(store, definition, flow, editor = flow.owner) {
     const elsewhere = definition.stages.filter((one) => one.kind === "task" && one.repo !== undefined && one.repo !== flow.repo);
     const owners = elsewhere.find(one => !store.accountCanAccess(flow.owner, one.repo));
@@ -439,7 +381,6 @@ export function crossProjectProblem(store, definition, flow, editor = flow.owner
     return editors === undefined ? null : `Zone ${editors.title}: you can't file work in that project, so you can't point a build there.`;
 }
 const zoneWords = (title) => `${title}${/[.?!]$/.test(title) ? "" : "."}`;
-/** A card's words, checked once for every door: a title, an optional description, and no keys, because cards become agent instructions. */
 export function flowCardText(title, description) {
     const cleanTitle = (typeof title === "string" ? title : "").replace(/[\u0000-\u001f\u007f]/g, " ").trim().slice(0, 200);
     const cleanDescription = (typeof description === "string" ? description : "").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "").trim().slice(0, 4000) || null;
@@ -449,7 +390,6 @@ export function flowCardText(title, description) {
         return { problem: "That looks like a key or password. Cards become agent instructions; keep secrets out of them." };
     return { title: cleanTitle, description: cleanDescription };
 }
-/** Add a card to a flow, in its start zone unless a zone is named. */
 export function addCardToFlow(store, flow, input, actor, now) {
     const definition = flowDefinitionOf(flow);
     if (definition === null || flow.state !== "active")
@@ -459,11 +399,9 @@ export function addCardToFlow(store, flow, input, actor, now) {
         return { ok: false, message: text.problem };
     const stage = definition.stages.find(one => one.id === input.stage) ?? definition.stages.find(one => one.id === definition.start);
     const card = store.addFlowCard({ flow: flow.id, title: text.title, description: text.description, stage: stage.id, by: actor, byKind: "person" }, now);
-    // Whoever adds a card follows it; owning it is a separate, deliberate step.
     store.setFlowCardWatcher(card, actor, true, now);
     return { ok: true, said: `Card added to ${zoneWords(stage.title)}`, card };
 }
-/** Move a card to another zone of its flow by hand; the zone's step runs on the next pass. */
 export function moveCardInFlow(store, card, to, actor, now) {
     const flow = store.getFlow(card.flow);
     const definition = flow === null ? null : flowDefinitionOf(flow);
@@ -480,7 +418,6 @@ export function moveCardInFlow(store, card, to, actor, now) {
         notifyPeople(store, card, [card.owner], actor, { key: `moved:${card.entry}`, subject: `${actor} moved “${card.title}” to ${stage.title}`, body: `It was in ${definition.stages.find(one => one.id === card.stage)?.title ?? "another zone"}.` }, now);
     return { ok: true, said: `Moved to ${zoneWords(stage.title)}`, card: card.id };
 }
-/** Take a card out of its flow; the tasks it filed are left as they are. */
 export function cancelFlowCard(store, card, actor, now) {
     if (card.state !== "active")
         return { ok: false, message: "That card is already finished." };
@@ -488,18 +425,13 @@ export function cancelFlowCard(store, card, actor, now) {
     store.updateFlowCard(card.id, { state: "cancelled", waiting: null }, now);
     return { ok: true, said: "Card cancelled. Its tasks are unchanged.", card: card.id };
 }
-/** A person's decision on a card waiting in an approval zone. A send back to a build zone whose work has a result becomes a revision of that work. */
-/** The draft a decision is about: the draft zone that sends its cards to this one. */
 export function draftFor(definition, stage) {
     return definition.stages.find(one => one.kind === "draft" && one.next === stage.id)
-        // A subagent's zone that leads here (by its next, or one of its answers) wrote the draft this decision checks (starter kits).
         ?? definition.stages.find(one => one.kind === "subagent" && (one.next === stage.id || (one.routes ?? []).some(route => route.to === stage.id))) ?? null;
 }
-/** Back to a build zone with a finished result: a revision of that same work, carrying the note; null when it isn't one. */
 export function revisionWithNote(store, card, target, note, actor, repos, evidenceRoot, now) {
     if (target?.kind !== "task" || card.primaryTask === null || evidenceRoot === undefined)
         return null;
-    // The build's own project (a zone may build in another) must be one the person can reach.
     const repo = store.lookupRef(card.primaryTask)?.repo ?? null;
     if (repo !== null && !repos.includes(repo))
         return null;
@@ -523,20 +455,15 @@ export function decideFlowCard(store, input, now) {
     const stage = definition.stages.find(one => one.id === card.stage);
     if (stage === undefined || stage.kind !== "approval" || (input.entry !== undefined && input.entry !== card.entry))
         return { ok: false, message: "That card has moved on since; nothing was changed." };
-    // A subagent decides only a zone it staffs; its person (and only them) can always decide instead.
     const decider = deciderOf(stage, flow);
     if (input.subagent !== undefined ? stage.subagent !== input.subagent : decider !== null && decider !== input.actor)
         return { ok: false, message: `Only ${decider ?? "an approver"} decides here.` };
-    // v102: a protected project's decisions are a person's, never a subagent's.
     if (input.subagent !== undefined && store.approvalRules(flow.repo).protectProject)
         return { ok: false, message: "This project is protected: a person decides here." };
-    // Every decision is one ledger line, the same wherever it was made; only `via` says where.
     const ledger = (outcome) => store.recordAction({ at: now.toISOString(), actor: input.actor, repo: flow.repo, taskId: card.primaryTask, runId: null,
         action: "flow decision", outcome, source: "request", detail: `${flow.name} · card ${card.id} · ${stage.title}${input.subagent === undefined ? "" : ` · subagent ${input.subagent}`} · via ${input.where ?? "Toolroll"}` });
     if (input.decision === "approve") {
-        // An edited draft replaces the one Claude wrote, so the steps after this send what the person approved.
         const draft = draftFor(definition, stage);
-        // A person's edit over the draft limit is refused with it, never cut. (A subagent's was asked once to shorten and is kept whole.)
         if (draft !== null && input.subagent === undefined && typeof input.draft === "string" && input.draft.trim().length > DRAFT_CHARS) {
             return { ok: false, message: `Keep the draft to ${DRAFT_CHARS.toLocaleString("en-US")} characters; this is ${input.draft.trim().length.toLocaleString("en-US")}.` };
         }
@@ -549,7 +476,6 @@ export function decideFlowCard(store, input, now) {
             ledger("approved");
             return { ok: true, said: "Approved. The card is done." };
         }
-        // Who decided, from trusted context (approval policy §1.7): only a person's approval lets a Pull request zone merge.
         const authority = input.subagent !== undefined ? "subagent" : currentActor()?.lead === true ? "lead" : activeRemote() !== null ? "remote" : "person";
         if (!store.moveFlowCard(card.id, { to: stage.next, outcome: "approved", actor: input.actor, note: input.note, expectEntry: card.entry, authority }, now))
             return { ok: false, message: "That card has moved on since; nothing was changed." };

package/dist/flow-gallery-ui.js

@@ -1,10 +1,3 @@
-/**
- * New flow (Flows → New): describe it to the lead, or start from a template. Templates are rows grouped by what
- * they're for, each with its promise, its steps in order, what it needs and one "Use this"; the starter kits ("With
- * an agent"), the recipes ("One-time work") and the starter flows join them as groups. A template's page asks only
- * what it needs, previews in plain words what it will do and never do, and creates it: the same answers it previewed.
- * A template's tools show their marks and whether the project has them; one it lacks offers Connect first.
- */
 import { brandMarkHtml } from "./brand-mark.js";
 import { BLANK, GALLERY, GALLERY_GROUPS, galleryAdmitsAnyone, galleryDiagram, galleryToolsOf, OUTDATED_COMMANDS, SEND_RESULT, sendsAlready } from "./flow-gallery.js";
 import { choiceTargets } from "./flows.js";
@@ -15,18 +8,14 @@ export const GALLERY_CSS = `.fl-new .k-sec{gap:12px}.fl-th{display:grid;justify-
     `.fl-trow{display:grid;grid-template-columns:minmax(0,1fr) auto;gap:16px;align-items:center;padding:12px 0;border-bottom:1px solid var(--so-line)}` +
     `.fl-tmain{display:grid;gap:3px;min-width:0}.fl-tmain>b{font:500 13.5px/1.35 var(--so-font-sans);color:var(--so-ink)}.fl-tp{color:var(--so-muted);font-size:12.5px;line-height:1.45;overflow-wrap:anywhere}` +
     `.fl-tline{display:flex;flex-wrap:wrap;align-items:center;gap:4px 8px;font-size:12px;margin-top:3px;color:var(--so-muted);min-width:0;overflow-wrap:anywhere}.fl-ta .k-btn{min-width:108px}.fl-ta form{margin:0}` +
-    // A template's steps in order, joined by arrows.
     `.gallery-steps{display:inline-flex;flex-wrap:wrap;align-items:center;gap:4px 6px;list-style:none;padding:0;margin:0;font-size:12px;line-height:1.5;color:var(--so-ink)}` +
     `.gallery-steps li{display:inline-flex;align-items:center;gap:6px;min-width:0;overflow-wrap:anywhere}.gallery-steps li>span[aria-hidden]{color:var(--so-muted)}.gallery-steps b{font-weight:500}` +
     `.gallery-tools{display:inline-flex;flex-wrap:wrap;gap:4px 10px;list-style:none;padding:0;margin:0}.gallery-tools li{display:inline-flex;align-items:center;gap:6px;min-width:0}` +
     `.fl-blank{padding-top:4px}.fl-describe-note{margin-top:2px}` +
-    // A template's page: the tools to connect, the form, and what it will do.
     `.fl-use form{display:grid;gap:18px;margin:0}.fl-tool{display:grid;gap:10px;padding:12px 0;border-top:1px solid var(--so-line)}.fl-tool:last-child{border-bottom:1px solid var(--so-line)}.fl-tool form{gap:10px}` +
     `.fl-tool-h{display:flex;align-items:center;gap:8px;flex-wrap:wrap;margin:0;font-size:13px;font-weight:500}.fl-check{display:flex;align-items:flex-start;gap:8px;font-size:13px;font-weight:500;cursor:pointer}.fl-check input{margin-top:3px;width:16px;height:16px;flex:none}.fl-check .k-note{display:block;font-weight:400}` +
     `.fl-will{display:grid;gap:10px;padding:16px 0;border-top:1px solid var(--so-line);border-bottom:1px solid var(--so-line)}.fl-will ul{margin:0;padding-left:18px;font-size:13px;line-height:1.55}.fl-will ol{margin:6px 0 0;padding-left:20px;white-space:pre-line;font-size:12.5px;line-height:1.5;color:var(--so-muted)}.fl-will li{overflow-wrap:anywhere}.fl-never{margin:0;font-size:13px;font-weight:600}` +
     `@media(max-width:760px){.fl-page .k-btn.k-docked,.fl-new .k-btn.k-docked,.fl-use .k-btn.k-docked,.fl-kit .k-btn.k-docked{display:none}.fl-trow{grid-template-columns:minmax(0,1fr);gap:10px;padding:14px 0}.fl-ta .k-btn{width:100%}.fl-ta:empty{display:none}.fl-check input{width:20px;height:20px}}`;
-/** A flow's main path, as a person reads it: from the start, each step's first way on (a sort's first answer, a choose's
- * first option that goes somewhere, else next; a check's failure when passing just ends), never back to a step shown. */
 export function mainPath(definition) {
     const byId = new Map(definition.stages.map(one => [one.id, one]));
     const path = [];
@@ -39,30 +28,23 @@ export function mainPath(definition) {
     }
     return path;
 }
-/** A step's short name in the strip: a person's own steps from their side. */
 const stepName = (stage) => stage.kind === "choose" ? "You choose" : stage.kind === "approval" ? "You approve" : stage.kind === "send" ? "Sent to you" : stage.title;
-/** A flow's steps in order, joined by arrows. */
 export function stepStrip(definition) {
     return html `<ol class="gallery-steps" aria-label="Steps">${mainPath(definition).map((one, i) => {
         const name = stepName(one);
         return html `<li>${i === 0 ? "" : html `<span aria-hidden="true">→</span>`}${one.kind === "choose" || one.kind === "approval" ? html `<b>${name}</b>` : name}</li>`;
     })}</ol>`;
 }
-/** What a template needs, in words: its needs, else its tools, else nothing to connect. */
 const needsWords = (template) => template.needs.length > 0 ? `Needs ${template.needs.join(", ")}` : (template.tools ?? []).length > 0 ? "" : "Nothing to connect";
-/** A tool's state in words, as Settings → Integrations says it; nothing without a project. */
 const STATE = { connected: "Connected", open: "Not connected", taken: "Added another way" };
 const toolState = (tool) => tool.state === null ? "" : chip(STATE[tool.state], tool.state === "connected" ? "done" : "", { dot: tool.state === "connected" });
 const toolMark = (tool) => brandMarkHtml(tool.id.replace(/-desktop$/, ""), tool.label, tool.state === "connected");
 const toolsList = (tools) => tools.length === 0 ? ""
     : html `<ul class="gallery-tools" aria-label="Tools">${tools.map(one => html `<li data-tool="${one.id}" data-state="${one.state ?? "unknown"}">${toolMark(one)}<span>${one.label}${one.state === "open" ? " (not connected)" : ""}</span></li>`)}</ul>`;
-/** One row of New flow: name · promise · one line · one outline action (the same shape for templates, kits, recipes and starters). */
 export function templateRow(options) {
     return html `<div class="fl-trow"${options.attrs ?? ""}><div class="fl-tmain"><b>${options.name}</b><span class="fl-tp">${options.promise}</span>${options.line ? html `<span class="fl-tline">${options.line}</span>` : ""}</div><div class="fl-ta">${options.action ?? ""}</div></div>`;
 }
-/** The groups New flow filters by: the template groups, then kits, recipes and starter flows. */
 export const NEW_FLOW_GROUPS = [["all", "All"], ...GALLERY_GROUPS.map(one => [one.id, one.label]), ["kits", "With an agent"], ["recipes", "One-time work"], ["starters", "Starter flows"]];
-/** The templates as rows, grouped (or one group): each with one "Use this". `repo` carries a chosen project to the template's page. */
 export function galleryHtml(input) {
     const href = (id) => `/flows/new/${id}${input.repo === null ? "" : `?repo=${encodeURIComponent(input.repo)}`}`;
     const rowOf = (template) => {
@@ -75,10 +57,6 @@ export function galleryHtml(input) {
     const shown = GALLERY_GROUPS.filter(one => input.group === undefined || input.group === "all" || input.group === one.id);
     return html `${shown.map(one => { const templates = GALLERY.filter(template => template.group === one.id); return html `${group(one.label, count(templates.length))}<div data-group="${one.id}">${templates.map(rowOf)}</div>`; })}`;
 }
-/**
- * New flow: describe it (the shared composer; the words go to the lead as a chat draft, the project on its bar), then
- * start from a template, filtered by group. Kits, recipes and starter flows arrive as their own rows.
- */
 export function newFlowHtml(input) {
     const groupKey = NEW_FLOW_GROUPS.some(([key]) => key === input.group) ? input.group : "all";
     const keep = (key) => `/flows/new?${new URLSearchParams({ ...(key === "all" ? {} : { group: key }), ...(input.repo === null ? {} : { repo: input.repo }) }).toString()}`.replace(/\?$/, "");
@@ -98,16 +76,12 @@ export function newFlowHtml(input) {
     return html `<div class="fl-new" data-kit-page>${phoneHeader("New flow", { back: "/flows" })}${doc(docHeader({ title: "New flow", back: ["/flows", "Flows"], meta: input.canUse ? "Describe it in a sentence, or start from a template." : "An approver creates flows.", same: true }), said, describe, html `<section class="k-sec" aria-labelledby="fl-th"><div class="fl-th"><h3 id="fl-th">Start from a template</h3>${filter}</div><div class="fl-tlist">${list}</div></section>`)}\
 ${input.canUse ? dock(btn("Draft the flow", { variant: "primary", type: "submit", attrs: { form: "fl-ask-form" } })) : ""}</div>`;
 }
-/** A template's page, a reading page: its steps and tools, its questions, what it will do and never do, then Create. */
 export function galleryUseHtml(input) {
     const { template } = input;
     const tools = input.tools ?? input.preview?.tools ?? [];
-    // A tool added another way is there: only one the project lacks is missing.
     const missing = tools.filter(one => one.state !== "connected" && one.state !== "taken");
-    // Each tool with its state; one the project lacks offers its own Connect (the Tools page's, with the same password), and comes back here.
     const connect = (tool) => {
         const head = html `<p class="fl-tool-h">${toolMark(tool)} ${tool.label} ${toolState(tool)}</p>`;
-        // Added another way, it is there: nothing to connect.
         if (tool.state === "connected" || tool.state === "taken" || input.csrf === "")
             return html `<div class="fl-tool" data-tool="${tool.id}" data-state="${String(tool.state)}">${head}</div>`;
         const how = tool.id === "figma-desktop" ? "Open the Figma desktop app and turn on its Dev Mode MCP server in Preferences." : `You sign in on ${tool.label}, then come back here.`;
@@ -115,7 +89,6 @@ export function galleryUseHtml(input) {
         return html `<div class="fl-tool" data-tool="${tool.id}" data-state="open">${head}${postForm("/settings/tools/connect", html `${note(how)}${reauth(field({ id: fieldId, label: "Your Toolroll password", control: kInput({ id: fieldId, name: "password", type: "password", attrs: { autocomplete: "current-password", required: true } }) }))}${acts(btn(`Connect ${tool.label}`, { type: "submit", attrs: { name: "service", value: tool.id } }))}`, { hidden: { repo: input.repo, shown: input.repo, template: template.id } })}</div>`;
     };
     const toolsBlock = tools.length === 0 ? "" : html `<section class="k-sec" aria-label="Tools"><h3>Tools</h3><div>${tools.map(connect)}</div></section>`;
-    // Made without a tool, the preview names the zone that needs it.
     const zones = (tool) => joinHtml(tool.zones.map(zone => html `“${zone}”`), " and ");
     const needing = html `${missing.filter(one => one.zones.length > 0).map(one => html `<p class="k-note" data-needs-tool="${one.id}">${zones(one)} need${one.zones.length === 1 ? "s" : ""} ${one.label}, which isn't connected.</p>`)}${tools.filter(one => one.state === "taken" && one.zones.length > 0).map(one => html `<p class="k-note" data-tool-taken="${one.id}">${zones(one)} use${one.zones.length === 1 ? "s" : ""} ${one.label}, added another way.</p>`)}`;
     const ask = (one, index) => {
@@ -132,7 +105,6 @@ export function galleryUseHtml(input) {
     const preview = input.preview === null ? "" : html `<section class="k-sec fl-will" aria-labelledby="fl-will"><h3 id="fl-will">What it will do</h3><ul>${input.preview.built.does.map(one => html `<li>${one}</li>`)}</ul><p class="fl-never">${input.preview.built.never}</p>${needing}\
 ${input.preview.startsFrom.length === 0 ? note("Cards start when you add them.") : input.preview.startsFrom.map(one => note(`Starts from: ${one}`))}${disclose("Every step", html `<ol>${input.preview.steps.map(one => html `<li>${one.replace(/^\d+\.\s/, "")}</li>`)}</ol>`)}</section>`;
     const sendResult = !sendsAlready(template) && html `<label class="fl-check"><input type="checkbox" name="${SEND_RESULT.key}" value="yes"${input.answers[SEND_RESULT.key] === "yes" && html ` checked`} data-send-result><span>${SEND_RESULT.title}<span class="k-note">When a card finishes, what was done comes to you in your chat apps.</span></span></label>`;
-    // A flow that brings in items from anyone takes the password to make (chat-management.md §0a.3): a step-up, which Passwordless stands in for.
     const anyone = input.preview !== null && galleryAdmitsAnyone(template);
     const step = anyone ? reauth(field({ id: "fl-use-password", label: "Your password", hint: "It brings in items from anyone.", control: kInput({ id: "fl-use-password", name: "password", type: "password", hint: true, attrs: { autocomplete: "current-password" } }) })) : "";
     const creates = input.preview !== null;