mockpit 1.3.0 → 2.0.0

package/dist/server/app.js

@@ -5,11 +5,12 @@ import { streamSSE } from "hono/streaming";
 import { ICON_SIZES, ICON_SVG, themeColor, webManifest } from "./appIcon.js";
 import { ICON_PNG_BASE64 } from "./appIconPng.js";
 import { decodeBase64 } from "./base64.js";
-import { mockDetailView, treeNodeView, mockSummaryView, sessionRowView, surfaceRef, } from "./apiViews.js";
+import { mockDetailView, treeNodeView, mockSummaryView, placeOf, sessionRowView, surfaceRef, } from "./apiViews.js";
 import { askNudges } from "./askNudges.js";
 import { EventBus } from "./events.js";
 import { GUIDE_TOPICS, isGuideTopic, renderBriefGuide, unknownTopicMessage, } from "./designGuide.js";
 import { buildFeedbackBatches } from "./feedbackBatch.js";
+import { guidanceSections, MAX_RULES_CHARS, parseRulesFile, RULES_SETTING, USER_RULES_SETTING, } from "./guidance.js";
 import { HANDOFF_NOTE, handoffReady, supersedes } from "./handoff.js";
 import { bundledIconSets, expandIcons, iconCount, isIconName, mayHaveIcons, parseIconSet, resolverFor, } from "./icons.js";
 import { checkProjectKit, KIT_IDS, kitSummaries } from "./kits.js";
@@ -26,7 +27,7 @@ import { logMiddleware, writeLog } from "./eventLog.js";
 import { RUN_API } from "./runApi.js";
 import { escapeHtml, renderHtmlPage, renderMermaidPage, knobAttributes, renderSandboxedPart, STATIC_ASSET_PREFIX, staticAsset, } from "./surfacePage.js";
 import { DEFAULT_MODE, DEFAULT_THEME_ID, isMode, themeById } from "./themes.js";
-import { askAnswered, builtinAsk, builtinAskIds, DEFAULT_PROJECT, DEFAULT_VARIANT, htmlSurface, isSandboxedSurfaceKind, ATTACHABLE_IMAGE_TYPES, MAX_ASK_IMAGES, MAX_ASSET_BYTES, inUseVersion, isLive, optionState, newId, openAsks, openCount, OTHER_ID, REACTIONS, projectFromCwd, postAtVersion, versionAt, reservedAgent, sameScreen, slugify, surfacesByteLength, } from "./types.js";
+import { askAnswered, builtinAsk, builtinAskIds, DEFAULT_PROJECT, DEFAULT_VARIANT, htmlSurface, isSandboxedSurfaceKind, ATTACHABLE_IMAGE_TYPES, MAX_ASK_IMAGES, MAX_ASSET_BYTES, inUseVersion, isLive, isMockKind, momentOf, NORMAL_SITUATION, optionState, newId, openAsks, openCount, OTHER_ID, REACTIONS, projectFromCwd, AREA_ORDER_SETTING, stripNul, postAtVersion, versionAt, variantStatus, reservedAgent, sameScreen, situationKey, slugify, surfacesByteLength, } from "./types.js";
 import { coerceSurfaces, validateSurfaces, } from "./postSurfaces.js";
 import { isViewerRequest } from "./viewerRequest.js";
 const MAX_SURFACE_BYTES = 2 * 1024 * 1024;
@@ -169,16 +170,33 @@ const fail = (status, error, extra = {}) => ({
     body: { error, ...extra },
 });
 const MAX_NOTE = 400;
+const MAX_SOURCE = 1024;
 const MAX_WIDTHS = 4;
 const MIN_WIDTH = 280;
 const MAX_WIDTH = 2560;
 const str = (v, max) => typeof v === "string" && v.trim() ? v.trim().slice(0, max) : undefined;
 const MAX_LABEL = 120;
+const MAX_AREAS = 50;
 const MAX_FLOWS = 50;
 const MAX_FLOW_STEPS = 100;
 const MAX_ASKS = 20;
 const MAX_OPTIONS = 20;
 const MAX_DRAFT_COMMENTS = 50;
+// A title that names a step of the agent's process instead of what the mock
+// is: it reads as noise on Home, where titles are seen out of context.
+const PROCESS_TITLE = /^\s*(round\s*\d+|flow\s*\d+\s*[·:\-–—]|v\d+\b|prototype\b)/i;
+// Once, on a variant's first version: a canvas page runs live in every
+// overview card, and a browser holds only about 16 WebGL contexts.
+const posterNudges = (surfaces) => surfaces.some((s) => s.kind === "html" && !s.poster && /<canvas[\s>]/i.test(s.html))
+    ? [
+        "this page draws on a <canvas> and has no poster, so Studio and Home run it live; send a still of it as poster (upload the image, or CLI --poster shot.png) with each version",
+    ]
+    : [];
+const titleNudges = (title) => title && PROCESS_TITLE.test(title)
+    ? [
+        `title "${title}" names your process; title the mock by what it is ("Hold menu"), as states are named by what the user sees`,
+    ]
+    : [];
 const APP_FILES = new Set([
     "/manifest.webmanifest",
     "/icon.svg",
@@ -186,7 +204,7 @@ const APP_FILES = new Set([
     ...ICON_SIZES.map((s) => `/icon-${s}.png`),
 ]);
 const titleFromSlug = (slug) => slug.replace(/-/g, " ").replace(/^./, (ch) => ch.toUpperCase());
-export function createApp({ store, viewerHtml, setupText, topics = {}, authenticate, authToken, basePath, publicRead, screenshots, version, upgradeCommand, renderRev, fetchLatestRelease, onEvent, maxHoldConnections = DEFAULT_MAX_HOLD_CONNECTIONS, executor, runLimits, log, }) {
+export function createApp({ store, viewerHtml, setupText, topics = {}, packs = {}, userRules, authenticate, authToken, basePath, publicRead, screenshots, version, upgradeCommand, renderRev, fetchLatestRelease, onEvent, maxHoldConnections = DEFAULT_MAX_HOLD_CONNECTIONS, executor, runLimits, log, }) {
     const app = new Hono();
     // The scripts topic carries the run API from runApi.ts, its one source.
     if (topics.scripts)
@@ -534,13 +552,42 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     async function briefFor(project) {
         try {
             const name = project ?? (await store.listProjects())[0]?.name ?? DEFAULT_PROJECT;
-            return renderBriefGuide(await designFor(name));
+            return renderBriefGuide(await designFor(name), await guidanceFor(name));
         }
         catch (err) {
             console.warn("[mockpit] project design unavailable for the brief", err);
             return renderBriefGuide(null);
         }
     }
+    // The user's file wins over the stored copy when the host can read it: the
+    // copy exists for hosts that can't.
+    async function userRulesText() {
+        const file = userRules ? await userRules().catch(() => null) : null;
+        return file ?? (await store.getSetting(USER_RULES_SETTING));
+    }
+    async function guidanceFor(project) {
+        return guidanceSections({
+            packs,
+            user: await userRulesText(),
+            project: await store.getSetting(`${RULES_SETTING}:${project}`),
+        });
+    }
+    // A rules file as sent by `mockpit rules`: stored whole, "" clears it. The
+    // answer says what the brief will make of it, so a mistyped pack name shows
+    // at once rather than as a quietly missing layer.
+    async function saveRules(key, body) {
+        if (!body || typeof body !== "object" || typeof body.text !== "string") {
+            return fail(400, 'provide "text", the rules file ("" clears it)');
+        }
+        const text = stripNul(body.text).trim();
+        if (text.length > MAX_RULES_CHARS) {
+            return fail(400, `a rules file is at most ${MAX_RULES_CHARS} characters`);
+        }
+        await store.setSetting(key, text);
+        const parsed = parseRulesFile(text);
+        const unknown = parsed.packs.filter((p) => !(p in packs));
+        return ok({ packs: parsed.packs, unknown, rules: parsed.body.length > 0, cleared: !text });
+    }
     // Push + webhooks. Detached on purpose: a dead push endpoint must never fail
     // (or slow) the write that triggered it.
     function fireNotify(payload) {
@@ -698,6 +745,45 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         code: failure.code,
         issues: failure.issues,
     });
+    // A poster is a still of the html beside it. Carried over unchanged onto
+    // changed html (a parts or fills splice, a fork with edits) it would show an
+    // old page, so it goes unless the write brings one; `poster` names the still
+    // of the page this write produces.
+    async function withPoster(surfaces, before, poster) {
+        const given = poster === undefined ? undefined : str(poster, MAX_LABEL);
+        if (poster !== undefined && !given) {
+            return fail(400, '"poster" must be the asset id of an uploaded image');
+        }
+        const pagesBefore = (before ?? []).filter((s) => s.kind === "html");
+        let ordinal = 0;
+        const out = surfaces.map((s) => {
+            if (s.kind !== "html")
+                return s;
+            const old = (s.id !== undefined && pagesBefore.find((b) => b.id === s.id)) || pagesBefore[ordinal];
+            let next = s;
+            if (s.poster && old?.kind === "html" && old.html !== s.html && old.poster === s.poster) {
+                const { poster: _stale, ...rest } = s;
+                next = rest;
+            }
+            if (ordinal === 0 && given)
+                next = { ...next, poster: given };
+            ordinal++;
+            return next;
+        });
+        if (given && ordinal === 0)
+            return fail(400, '"poster" needs an html surface to be the still of');
+        for (const s of out) {
+            if (s.kind !== "html" || !s.poster)
+                continue;
+            const asset = await store.getAsset(s.poster);
+            if (!asset)
+                return fail(404, `poster "${s.poster}" is not an uploaded asset; upload the image first`);
+            if (!asset.contentType.startsWith("image/")) {
+                return fail(400, `poster "${s.poster}" is ${asset.contentType}, not an image`);
+            }
+        }
+        return out;
+    }
     function checkSurfaces(surfaces) {
         if (surfaces.length === 0)
             return fail(400, "a variant needs at least one surface");
@@ -772,6 +858,18 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         }
         return used;
     }
+    // Being embedded is what makes a mock a component, so a sketch another mock
+    // embeds becomes one; a declared page stays a page.
+    async function promoteEmbedded(project, embeds) {
+        for (const slug of new Set(embeds.map((e) => e.slug))) {
+            const m = await store.findMock(project, slug);
+            if (m?.kind !== "sketch")
+                continue;
+            const updated = await store.updateMock(m.id, { kind: "component" });
+            if (updated)
+                bus.broadcast({ type: "mock-updated", id: updated.id, project });
+        }
+    }
     // What the variants of a mock show through their embeds now: per post, the
     // resolved list (nested included) with each component's versions, and the
     // key that changes when any of them does.
@@ -862,7 +960,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         const states = mock.states.length ? mock.states : [null];
         const wide = states.every((s) => key(live(s)) === key(names));
         // An ask that already picks between some of these variants is the question:
-        // a second, generic "Which one?" would make the user choose the look twice.
+        // a second, generic "Which variant?" would make the user choose twice.
         // A mock-wide one only fits while every state has the same variants; else a
         // variant only some states have would leave the others no real choice.
         const existing = mock.asks.find((a) => applies(a) && a.options.some((o) => o.variant) && (a.scope === "state" || wide));
@@ -886,7 +984,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                 ],
             };
             return {
-                nudge: `${where}: bind ${missing.map((m) => `"${m}"`).join(", ")} to your existing ask "${existing.id}": call ask with suggestedAsk. Never ask in chat.`,
+                nudge: `${where}: bind ${missing.map((m) => `"${m}"`).join(", ")} to your existing question "${existing.id}": call ask with suggestedAsk. Never ask in chat.`,
                 ask,
             };
         }
@@ -894,15 +992,15 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         // Not the built-in's reserved id: a stored ask under it would collide with the
         // built-in the viewer synthesizes once a new variant goes unbound. Nor any id
         // already taken, which sending this would silently replace.
-        const base = wide ? "look" : `look-${slugify(state ?? "")}`;
+        const base = wide ? "choice" : `choice-${slugify(state ?? "")}`;
         let id = base;
         for (let n = 2; mock.asks.some((a) => a.id === id); n++)
             id = `${base}-${n}`;
         const ask = wide
-            ? { id, text: "Which one?", scope: "mock", options }
-            : { id, text: "Which one?", scope: "state", state, options };
+            ? { id, text: "Which variant?", scope: "mock", options }
+            : { id, text: "Which variant?", scope: "state", state, options };
         return {
-            nudge: `${where} has ${names.length} variants and no ask binds them: call ask with suggestedAsk. Never ask in chat.`,
+            nudge: `${where} has ${names.length} variants and no question binds them: call ask with suggestedAsk. Never ask in chat.`,
             ask,
         };
     }
@@ -913,7 +1011,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         const posts = await store.listPosts({ mockId: mock.id });
         const detail = mockDetailView(mock, posts);
         const unbound = unboundVariants(mock, posts, post.state);
-        // A slot no ask sets is a decision nobody was asked; hand over the ask.
+        // A part with fills that no ask sets is a decision nobody was asked; hand over the ask.
         const slots = slotsInSurfaces(post.surfaces);
         const setPaths = new Set(mock.asks.flatMap((a) => a.options.flatMap((o) => Object.keys(o.set ?? {}))));
         const slotAsks = slots
@@ -930,7 +1028,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             ...(unbound ? [unbound.nudge] : []),
             ...(slotAsks.length
                 ? [
-                    `${slotAsks.map((a) => `slot "${a.part}"`).join(", ")} ${slotAsks.length === 1 ? "has" : "have"} fills and no ask sets ${slotAsks.length === 1 ? "it" : "them"}: send suggestedSlotAsks with ask (reword the text in the user's terms)`,
+                    `${slotAsks.map((a) => `part "${a.part}"`).join(", ")} ${slotAsks.length === 1 ? "has" : "have"} fills and no question sets ${slotAsks.length === 1 ? "it" : "them"}: send suggestedFillAsks with ask (reword the text in the user's terms)`,
                 ]
                 : []),
         ];
@@ -947,6 +1045,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                 slug: mock.slug,
                 title: mock.title,
                 kind: mock.kind,
+                ...placeOf(mock),
                 states: mock.states,
             },
             post: {
@@ -954,20 +1053,20 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                 state: post.state,
                 variant: post.variant,
                 version: post.version,
-                status: post.status,
+                status: variantStatus(post.status),
                 surfaces: post.surfaces.map(surfaceRef),
             },
             sessionId: post.sessionId,
             url: mockUrl(ctx.base, mock, post),
             parts: detail.parts,
-            ...(slots.length ? { slots } : {}),
+            ...(slots.length ? { fills: slots } : {}),
             ...(extra.applied ? { applied: extra.applied } : {}),
             ...(partChanges && (partChanges.vanished.length || partChanges.renamed.length)
                 ? { partChanges }
                 : {}),
             ...(nudges.length ? { nudges } : {}),
             ...(unbound ? { suggestedAsk: unbound.ask } : {}),
-            ...(slotAsks.length ? { suggestedSlotAsks: slotAsks } : {}),
+            ...(slotAsks.length ? { suggestedFillAsks: slotAsks } : {}),
             ...(warnings.length ? { warnings } : {}),
             ...(extra.flow ? { flow: extra.flow } : {}),
             feedback,
@@ -1031,7 +1130,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             return fail(400, variantKnobs.error);
         const stateIn = stateArg(body.state);
         const variantIn = str(body.variant, MAX_LABEL);
-        const kind = body.kind === "page" || body.kind === "component" ? body.kind : undefined;
+        const kind = isMockKind(body.kind) ? body.kind : undefined;
         const title = str(body.title, MAX_TITLE);
         const fromN = Number(body.from);
         const from = Number.isInteger(fromN) && fromN > 0 ? fromN : undefined;
@@ -1041,6 +1140,12 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         const widths = widthsArg(body.widths);
         if (isResult(widths))
             return widths;
+        const area = labelArg(body, "area", MAX_LABEL);
+        if (isResult(area))
+            return area;
+        const source = labelArg(body, "source", MAX_SOURCE);
+        if (isResult(source))
+            return source;
         // An existing mock is addressable by id before a session exists.
         let mock = null;
         if (typeof body.mock === "string")
@@ -1072,6 +1177,32 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             }
             state = stateIn;
         }
+        const situationIn = str(body.situation, MAX_LABEL);
+        // A situation is another render of one state ("Couldn't save"); "Normal"
+        // names the state's own render.
+        let situation;
+        if (situationIn && situationIn.toLowerCase() !== NORMAL_SITUATION.toLowerCase()) {
+            if (state === null) {
+                return fail(400, '"situation" needs "state": the state it is another render of');
+            }
+            if (!mock || !mock.states.includes(state)) {
+                return fail(404, `${slug} has no state "${state}" yet: publish its normal render first, then its situations`, mock ? { states: mock.states } : {});
+            }
+            const moment = momentOf(mock.situations, state);
+            // The key feedback names it by, passed back with its own situation.
+            if (moment !== state && moment !== null && situationKey(moment, situationIn) === state) {
+                state = moment;
+            }
+            else if (moment !== state) {
+                return fail(400, `"${state}" is a situation; give "situation" the state it belongs to`);
+            }
+            const key = situationKey(state, situationIn);
+            if (mock.states.includes(key) && !(mock.situations[state] ?? []).includes(situationIn)) {
+                return fail(409, `${slug} already has a state named "${key}"; name the situation otherwise`);
+            }
+            situation = { of: state, name: situationIn };
+            state = key;
+        }
         const inState = posts.filter((p) => p.state === state);
         let variant = variantIn;
         if (!variant) {
@@ -1094,7 +1225,8 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         const missing = () => fail(404, `${slug} has no variant "${variant}"${state === null ? "" : ` in "${state}"`}`, {
             variants: posts.map(variantLabel),
         });
-        const screen = { mock: slug, state };
+        // A flow steps through states; a situation's step is its state's.
+        const screen = { mock: slug, state: situation ? situation.of : state };
         if (flowIn) {
             const full = await flowFull(project, flowIn.name, screen, flowIn.step);
             if (full)
@@ -1171,13 +1303,23 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                 return parsed;
             surfaces = parsed;
         }
+        const before = base();
+        const postered = await withPoster(surfaces, isResult(before) ? null : before, body.poster);
+        if (isResult(postered))
+            return postered;
+        surfaces = postered;
         const bad = checkSurfaces(surfaces);
         if (bad)
             return bad;
-        const nudges = knobNudges({ ...knobs.value, ...variantKnobs.value });
+        const nudges = [
+            ...knobNudges({ ...knobs.value, ...variantKnobs.value }),
+            ...titleNudges(title),
+            ...(target ? [] : posterNudges(surfaces)),
+        ];
         const embeds = await publishEmbeds(project, slug, surfaces);
         if (isResult(embeds))
             return embeds;
+        await promoteEmbedded(project, embeds);
         if (!target) {
             // A new variant: carried by the session the agent is writing from.
             if (!session) {
@@ -1194,7 +1336,9 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                     project,
                     slug,
                     title: title ?? titleFromSlug(slug),
-                    kind: kind ?? "component",
+                    kind: kind ?? "sketch",
+                    ...(area === undefined ? {} : { area }),
+                    ...(source === undefined ? {} : { source }),
                     states: state === null ? [] : [state],
                     knobs: knobs.value,
                     ...(widths ? { widths } : {}),
@@ -1225,10 +1369,13 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                 return fail(404, "session not found");
             mock = await updateMockAfterWrite(mock, {
                 state,
+                situation,
                 kind,
                 title,
                 knobs: knobs.value,
                 widths,
+                area,
+                source,
                 session,
             });
             const flow = flowIn ? await placeFlow(project, flowIn.name, screen, flowIn.step) : undefined;
@@ -1255,7 +1402,16 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         if (!updated)
             return fail(404, "variant not found");
         const flow = flowIn ? await placeFlow(project, flowIn.name, screen, flowIn.step) : undefined;
-        mock = await updateMockAfterWrite(mock, { state, kind, knobs: knobs.value, widths, session });
+        mock = await updateMockAfterWrite(mock, {
+            state,
+            situation,
+            kind,
+            knobs: knobs.value,
+            widths,
+            area,
+            source,
+            session,
+        });
         announcePost(mock, updated, false);
         if (prompt && ctx.request)
             notifyPublish(mock, updated, prompt, ctx);
@@ -1342,6 +1498,18 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             return fail(400, bad);
         return version === undefined ? { variant } : { variant, version };
     }
+    // An optional free-text field of the mock (`area`, `source`): absent keeps
+    // it, "" or null clears it.
+    function labelArg(body, key, max) {
+        const v = body?.[key];
+        if (v === undefined)
+            return undefined;
+        if (v === null)
+            return null;
+        if (typeof v !== "string")
+            return fail(400, `"${key}" must be a string; "" clears it`);
+        return str(v, max) ?? null;
+    }
     // `widths`: the device widths the mock is judged at, in the agent's order;
     // [] hands the choice back to the viewer.
     function widthsArg(v) {
@@ -1383,14 +1551,34 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     // A write may add a state, retitle the mock, declare knobs, and makes its
     // session the one a reply is delivered to.
     async function updateMockAfterWrite(mock, w) {
-        const states = w.state !== null && !mock.states.includes(w.state) ? [...mock.states, w.state] : undefined;
+        let states;
+        let situations;
+        if (w.state !== null && !mock.states.includes(w.state)) {
+            if (w.situation) {
+                // After its state and that state's other situations, so the order of
+                // states reads moment by moment.
+                const { of, name } = w.situation;
+                const own = mock.situations[of] ?? [];
+                const last = [of, ...own.map((n) => situationKey(of, n))]
+                    .map((st) => mock.states.indexOf(st))
+                    .reduce((a, b) => Math.max(a, b), -1);
+                states = [...mock.states.slice(0, last + 1), w.state, ...mock.states.slice(last + 1)];
+                situations = { ...mock.situations, [of]: [...own, name] };
+            }
+            else {
+                states = [...mock.states, w.state];
+            }
+        }
         const knobs = Object.keys(w.knobs).length ? { ...mock.knobs, ...w.knobs } : undefined;
         const updated = await store.updateMock(mock.id, {
             ...(states ? { states } : {}),
+            ...(situations ? { situations } : {}),
             ...(w.kind ? { kind: w.kind } : {}),
             ...(w.title ? { title: w.title } : {}),
             ...(knobs ? { knobs } : {}),
             ...(w.widths ? { widths: w.widths } : {}),
+            ...(w.area === undefined ? {} : { area: w.area }),
+            ...(w.source === undefined ? {} : { source: w.source }),
             ...(w.session ? { sessionId: w.session.id } : {}),
         });
         if (!updated)
@@ -1441,35 +1629,41 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         const pending = [];
         for (const m of mocks) {
             const posts = await store.listPosts({ mockId: m.id });
-            const embeds = await embedViews(m, posts);
-            const uses = new Set();
+            const views = await embedViews(m, posts);
+            const embeds = new Set();
             for (const p of posts) {
                 if (!isLive(p.status))
                     continue;
                 for (const x of p.surfaces) {
                     if (x.kind === "html")
                         for (const t of parseEmbedTags(x.html))
-                            uses.add(t.slug);
+                            embeds.add(t.slug);
                 }
             }
             nodes.push(treeNodeView(m, posts, {
                 settled: settledValues(await replyPayloads(m.id), m, posts),
-                uses: [...uses],
-                embeds,
+                embeds: [...embeds],
+                embedViews: views,
             }));
             pending.push(pendingOf(m, posts));
         }
         const bySlug = new Map(nodes.map((n) => [n.slug, n]));
         for (const n of nodes) {
-            n.uses = n.uses.filter((s) => bySlug.has(s));
-            for (const s of n.uses)
-                bySlug.get(s).usedIn.push(n.slug);
+            n.embeds = n.embeds.filter((s) => bySlug.has(s));
+            for (const s of n.embeds)
+                bySlug.get(s).embeddedIn.push(n.slug);
         }
-        return ok({ project, tree: nodes, flows: await flowsView(project, mocks), pending });
+        return ok({
+            project,
+            tree: nodes,
+            flows: await flowsView(project, mocks),
+            areaOrder: await areaOrderOf(project),
+            pending,
+        });
     }
     async function replyPayloads(mockId) {
         return (await store.listComments({ mockId }))
-            .filter((c) => c.kind === "reply" && c.payload)
+            .filter((c) => c.kind === "reply" && c.payload && !c.payload.edited)
             .map((c) => c.payload);
     }
     async function getMockFlow(ref, query) {
@@ -1513,9 +1707,9 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                 continue;
             const post = postAtVersion(found, inUseVersion(found)) ?? found;
             const html = post.surfaces.find((s) => s.kind === "html");
-            // With slots, the screen as decided: only the chosen fills, by every
+            // With fills, the state as decided: only the chosen fills, by every
             // value sent so far (defaults before any reply). The authored markup with
-            // every fill stays available as `source`.
+            // every fill stays available as `allFills`.
             const slots = slotsInSurfaces(post.surfaces);
             const raw = html && html.kind === "html" ? html.html : "";
             const composed = slots.length ? composeFills(raw, chosenFills(slots, settled)) : raw;
@@ -1526,9 +1720,9 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                 version: post.version,
                 // The agent's newer versions wait until the user puts one in use.
                 ...(found.version !== post.version ? { latest: found.version } : {}),
-                status: post.status,
+                status: variantStatus(post.status),
                 html: composed,
-                ...(slots.length ? { source: raw } : {}),
+                ...(slots.length ? { allFills: raw } : {}),
                 markdown: postToMarkdown(post, {
                     postUrl: `${ctx.base}/s/${post.id}`,
                     assetBase: ctx.base,
@@ -1601,6 +1795,10 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         const options = [];
         // Seeded with the viewer's write-in, so a label "Other" slugs to "other-2".
         const optionIds = new Set([OTHER_ID]);
+        // The agent's own pick, shown as a quiet mark on its option: one per ask.
+        const picks = raw.options.filter((o) => o && typeof o === "object" && o.recommended === true).length;
+        if (picks > 1)
+            return `ask "${text}" recommends ${picks} options; recommend one`;
         for (const o of raw.options) {
             const opt = typeof o === "string" ? { label: o } : o;
             const label = str(opt?.label, 200);
@@ -1624,14 +1822,21 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                     return checked.error;
                 set = checked.value;
             }
+            const pick = opt.recommended === true ? { recommended: true } : {};
             if (opt.version !== undefined) {
                 const pinned = versionOption(opt.version, label, variant, { scope, state }, mock, posts);
                 if (typeof pinned === "string")
                     return pinned;
-                options.push({ id, label, ...pinned, ...(set ? { set } : {}) });
+                options.push({ id, label, ...pinned, ...(set ? { set } : {}), ...pick });
                 continue;
             }
-            options.push({ id, label, ...(variant ? { variant } : {}), ...(set ? { set } : {}) });
+            options.push({
+                id,
+                label,
+                ...(variant ? { variant } : {}),
+                ...(set ? { set } : {}),
+                ...pick,
+            });
         }
         let id = slugify(str(raw.id, 64) ?? text).slice(0, 40);
         if (!str(raw.id, 64))
@@ -1719,7 +1924,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                 return fail(400, ask);
             const at = asks.findIndex((a) => a.id === ask.id);
             // The user closed this one as not worth answering; asking it again is
-            // exactly the noise they resolved away. Only their Reopen revives it.
+            // exactly the noise they closed away. Only their Reopen revives it.
             if (at >= 0 && asks[at].dismissed) {
                 skipped.push(ask.id);
                 continue;
@@ -1731,7 +1936,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             taken.add(ask.id);
             added.push(ask);
         }
-        const skippedNudges = skipped.map((id) => `ask "${id}": the user dismissed it when they resolved ${mock.slug}; not asked again. Don't re-ask it.`);
+        const skippedNudges = skipped.map((id) => `ask "${id}": the user dismissed it when they closed ${mock.slug}; not asked again. Don't re-ask it.`);
         if (!added.length) {
             return ok({
                 mock: mock.slug,
@@ -1749,12 +1954,12 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         if (typeof body.session === "string" && (await store.getSession(body.session))) {
             sessionId = body.session;
         }
-        // A new question on a resolved mock brings it back to the open list, or it
+        // A new question on a closed mock brings it back to the open list, or it
         // would wait where the user no longer looks.
         const updated = await store.updateMock(mock.id, {
             asks,
             sessionId,
-            ...(mock.resolvedAt ? { resolvedAt: null } : {}),
+            ...(mock.closedAt ? { closedAt: null } : {}),
         });
         if (!updated)
             return fail(404, "mock not found");
@@ -1810,15 +2015,33 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             if (reaction !== undefined && !REACTIONS.includes(reaction))
                 return `reaction must be one of ${REACTIONS.join(", ")}`;
             const text = str(c?.text, MAX_COMMENT_TEXT);
-            if (!text && !reaction)
+            const borrowIn = c?.borrow;
+            if (!text && !reaction && !borrowIn)
                 return "every comment needs text";
             const state = stateArg(c.state) ?? null;
             if (state !== null && !mock.states.includes(state))
                 return `${mock.slug} has no state "${state}"`;
             const part = str(c.part, 200) ?? null;
             const variant = str(c.variant, 200);
-            if (variant && !posts.some((p) => p.variant === variant && p.state === state))
+            const post = variant ? posts.find((p) => p.variant === variant && p.state === state) : null;
+            if (variant && !post)
                 return `${mock.slug} has no variant "${variant}"${state ? ` in "${state}"` : ""}`;
+            const version = c.version;
+            if (version !== undefined &&
+                (!post || !Number.isInteger(version) || version < 1 || version > post.version))
+                return `${mock.slug} has no version ${String(version)}${variant ? ` of "${variant}"` : ""}`;
+            let borrow;
+            if (borrowIn !== undefined) {
+                const from = str(borrowIn?.from, 240);
+                const at = from ? /^(.+)@(\d+)$/.exec(from) : null;
+                const source = at && posts.find((p) => p.variant === at[1] && p.state === state);
+                if (!at || !source || Number(at[2]) < 1 || Number(at[2]) > source.version)
+                    return `borrow.from must be variant@version of "${mock.slug}"${state ? ` in "${state}"` : ""}`;
+                if (!post || version === undefined)
+                    return "a borrow names the version it goes into";
+                const borrowed = str(borrowIn?.part, 200);
+                borrow = { from: at[0], ...(borrowed ? { part: borrowed } : {}) };
+            }
             const a = c.anchor && typeof c.anchor === "object" ? c.anchor : null;
             const anchor = a ? sanitizePartAnchor(a) : undefined;
             const next = {
@@ -1828,13 +2051,16 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                 ...(anchor ? { anchor } : {}),
                 ...(reaction ? { reaction: reaction } : {}),
                 ...(variant ? { variant } : {}),
+                ...(version !== undefined ? { version: version } : {}),
+                ...(borrow ? { borrow } : {}),
             };
             // One reaction per target: a later tap on the same part replaces the earlier one.
             if (reaction) {
                 const same = out.findIndex((o) => o.reaction &&
                     o.part === part &&
                     o.state === state &&
-                    (o.variant ?? null) === (variant ?? null));
+                    (o.variant ?? null) === (variant ?? null) &&
+                    (o.version ?? null) === (version ?? null));
                 if (same >= 0)
                     out.splice(same, 1);
             }
@@ -1941,18 +2167,18 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         }
         return out;
     }
-    function sanitizeMix(raw, posts) {
+    function sanitizeBorrowed(raw, posts) {
         if (raw === undefined || raw === null)
             return {};
         if (typeof raw !== "object" || Array.isArray(raw))
-            return '"mix" must be an object';
+            return '"borrowed" must be an object';
         const variants = new Set(posts.map((p) => p.variant));
         const out = {};
         for (const [part, variant] of Object.entries(raw)) {
             if (!part || part.length > 200)
-                return "mix keys are part names";
+                return "borrowed keys are part names";
             if (typeof variant !== "string" || !variants.has(variant)) {
-                return `mix "${part}" names a variant that does not exist`;
+                return `borrowed "${part}" names a variant that does not exist`;
             }
             out[part] = variant;
         }
@@ -1965,9 +2191,9 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         const answers = sanitizeAnswers(pick("answers"), mock, posts);
         if (typeof answers === "string")
             return answers;
-        const mix = sanitizeMix(pick("mix"), posts);
-        if (typeof mix === "string")
-            return mix;
+        const borrowed = sanitizeBorrowed(pick("borrowed"), posts);
+        if (typeof borrowed === "string")
+            return borrowed;
         const tuned = checkKnobValues(pick("tuned"), mock, posts, "tuned");
         if (!tuned.ok)
             return tuned.error;
@@ -2002,7 +2228,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         return {
             version,
             answers,
-            mix,
+            borrowed,
             tuned: tuned.value,
             comments,
             others,
@@ -2047,28 +2273,26 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         bus.broadcast({ type: "draft-updated", mockId: mock.id });
         return ok({ draft: null });
     }
-    function sanitizeDecision(raw, mock, posts) {
+    function sanitizeVerdict(raw, mock, posts) {
         if (raw === undefined || raw === null)
             return undefined;
         const kind = raw.kind;
-        if (kind !== "accept" && kind !== "revise" && kind !== "drop") {
-            return 'decision.kind must be "accept", "revise" or "drop"';
-        }
+        if (kind !== "use" && kind !== "revise")
+            return 'verdict.kind must be "use" or "revise"';
         const chosen = chooseVariant(mock, posts, stateArg(raw.state), str(raw.variant, MAX_LABEL));
         if (isResult(chosen))
             return chosen.body.error;
         return { kind, state: chosen.state, variant: chosen.variant };
     }
-    // Which variants a reply accepts and archives. A variant-bound answer accepts
-    // the chosen variant(s) in every state the ask covers and archives their
-    // siblings there; a part-scoped pick is a mix, not a verdict. The built-in
-    // variant asks flip the same way, per state. Each accepted variant is put in
-    // use at the version the reply was made on (`version`, a mock version), not
+    // Which variants a reply puts in use and archives. A variant-bound answer puts
+    // the chosen variant(s) in use in every state the ask covers and archives
+    // their siblings there; a part-scoped pick is a borrow, not a verdict. The
+    // built-in variant questions flip the same way, per state. Each variant is put
+    // in use at the version the reply was made on (`version`, a mock version), not
     // whatever the agent published since — or, for a version option, at its version.
-    function replyFlips(mock, posts, answers, decision, version) {
+    function replyFlips(mock, posts, answers, verdict, version) {
         const accept = new Map();
         const archive = new Set();
-        const drop = new Set();
         const settle = (inState, chosen, pins) => {
             if (!inState.some((p) => chosen.has(p.variant)))
                 return;
@@ -2080,7 +2304,8 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                 }
                 const pin = pins?.get(p.variant);
                 // A version option outranks a looser pick of the same variant (the
-                // built-in Which one?, a Look) in the same reply.
+                // built-in Which variant?, or the agent's own variant question) in the
+                // same reply.
                 if (pin === undefined && accept.has(p.id))
                     continue;
                 // A pinned version history retention has since dropped falls back to
@@ -2109,21 +2334,12 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             for (const state of states)
                 settle(posts.filter((p) => p.state === state), chosen);
         }
-        if (decision?.kind === "accept") {
-            settle(posts.filter((p) => p.state === decision.state), new Set([decision.variant]));
-        }
-        else if (decision?.kind === "drop") {
-            const post = posts.find((p) => p.state === decision.state && p.variant === decision.variant);
-            if (post)
-                drop.add(post.id);
-        }
-        for (const id of accept.keys()) {
-            archive.delete(id);
-            drop.delete(id);
+        if (verdict?.kind === "use") {
+            settle(posts.filter((p) => p.state === verdict.state), new Set([verdict.variant]));
         }
-        for (const id of drop)
+        for (const id of accept.keys())
             archive.delete(id);
-        return { accept, archive, drop };
+        return { accept, archive };
     }
     // An ask as a reply leaves it. A pick or a write-in replaces whatever was
     // answered before; a note alone keeps that answer and adds to it.
@@ -2170,13 +2386,13 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         if (typeof draft === "string")
             return fail(400, draft);
         const text = str(body?.text, MAX_COMMENT_TEXT);
-        const decision = sanitizeDecision(body?.decision, mock, posts);
-        if (typeof decision === "string")
-            return fail(400, decision);
+        const verdict = sanitizeVerdict(body?.verdict, mock, posts);
+        if (typeof verdict === "string")
+            return fail(400, verdict);
         const empty = !text &&
-            !decision &&
+            !verdict &&
             !Object.keys(draft.answers).length &&
-            !Object.keys(draft.mix).length &&
+            !Object.keys(draft.borrowed).length &&
             !Object.keys(draft.tuned).length &&
             !draft.comments.length &&
             !Object.keys(draft.others ?? {}).length &&
@@ -2191,7 +2407,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             mockId: mock.id,
             version: draft.version,
             answers: draft.answers,
-            mix: draft.mix,
+            borrowed: draft.borrowed,
             tuned: draft.tuned,
             comments: draft.comments,
             ...(Object.keys(draft.others ?? {}).length ? { others: draft.others } : {}),
@@ -2201,11 +2417,11 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             ...(text ? { text } : {}),
         };
         const asks = mock.asks.map((a) => sentAsk(a, draft));
-        const flips = replyFlips(mock, posts, draft.answers, decision, draft.version);
-        if (decision) {
-            const target = posts.find((p) => p.state === decision.state && p.variant === decision.variant);
-            const pinned = decision.kind === "accept" && target ? flips.accept.get(target.id) : undefined;
-            payload.decision = pinned === undefined ? decision : { ...decision, version: pinned };
+        const flips = replyFlips(mock, posts, draft.answers, verdict, draft.version);
+        if (verdict) {
+            const target = posts.find((p) => p.state === verdict.state && p.variant === verdict.variant);
+            const pinned = verdict.kind === "use" && target ? flips.accept.get(target.id) : undefined;
+            payload.verdict = pinned === undefined ? verdict : { ...verdict, version: pinned };
         }
         const comment = await store.commitReply({
             mockId: mock.id,
@@ -2215,7 +2431,6 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             asks,
             accept: [...flips.accept].map(([id, version]) => ({ id, version })),
             archive: [...flips.archive],
-            drop: [...flips.drop],
         });
         if (!comment)
             return fail(409, `${mock.slug} has no agent session to reply to`);
@@ -2225,7 +2440,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         void announceEmbedders(mock).catch((err) => console.warn("[mockpit] embedders", err));
         const after = await store.listPosts({ mockId: mock.id });
         for (const p of after) {
-            if (flips.accept.has(p.id) || flips.archive.has(p.id) || flips.drop.has(p.id)) {
+            if (flips.accept.has(p.id) || flips.archive.has(p.id)) {
                 bus.broadcast({
                     type: "post-updated",
                     id: p.id,
@@ -2240,29 +2455,26 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             event: "decision",
             project: mock.project,
             slug: mock.slug,
-            variant: decision?.variant ?? "",
+            variant: verdict?.variant ?? "",
             version: draft.version,
-            text: text || decision?.kind || "reply",
+            text: text || verdict?.kind || "reply",
             url: mockUrl(ctx.base, mock),
         });
         const [delivered] = await withDelivered([comment]);
         return ok({
             reply: delivered,
-            accepted: after
+            inUse: after
                 .filter((p) => flips.accept.has(p.id))
                 .map((p) => ({ state: p.state, variant: p.variant, version: inUseVersion(p) })),
             archived: after
                 .filter((p) => flips.archive.has(p.id))
                 .map((p) => ({ state: p.state, variant: p.variant })),
-            dropped: after
-                .filter((p) => flips.drop.has(p.id))
-                .map((p) => ({ state: p.state, variant: p.variant })),
         }, 201);
     }
-    // "Use this": the user puts one exact version of a variant in use. It is an
-    // accept, so it archives the variant's live siblings in that state and
-    // reaches the agent once, as a reply carrying the decision, through the same
-    // cursor as a Send; the user's unsent draft is left for their next Send.
+    // "Use this": the user puts one exact version of a variant in use. It
+    // archives the variant's live siblings in that state and reaches the agent
+    // once, as a reply carrying the verdict, through the same cursor as a Send;
+    // the user's unsent draft is left for their next Send.
     async function useFlow(ref, body, ctx) {
         if (!ctx.viewer)
             return viewerOnly();
@@ -2299,10 +2511,10 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                 mockId: mock.id,
                 version,
                 answers: {},
-                mix: {},
+                borrowed: {},
                 tuned: {},
                 comments: [],
-                decision: { kind: "accept", ...inUse },
+                verdict: { kind: "use", ...inUse },
             },
             asks: mock.asks,
             accept: [{ id: chosen.id, version }],
@@ -2330,7 +2542,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             slug: mock.slug,
             variant: chosen.variant,
             version,
-            text: "accept",
+            text: "use",
             url: mockUrl(ctx.base, mock),
         });
         const [delivered] = await withDelivered([comment]);
@@ -2394,15 +2606,15 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     }
     // The user closes a mock from the project list: its open asks are dismissed
     // unanswered, an unsent draft goes with them, and the agent hears it once,
-    // as a resolution through the same cursor as a Send.
-    async function resolveFlow(ref, ctx) {
+    // as a close through the same cursor as a Send.
+    async function closeFlow(ref, ctx) {
         if (!ctx.viewer)
             return viewerOnly();
         const mock = await resolveMock(ref);
         if (isResult(mock))
             return mock;
         const posts = await store.listPosts({ mockId: mock.id });
-        if (mock.resolvedAt)
+        if (mock.closedAt)
             return ok({ mock: mockSummaryView(mock, posts), dismissed: [] });
         const dismissed = [...openAsks(mock).map((a) => a.id), ...builtinAskIds(mock, posts, mock.id)];
         const asks = mock.asks.map((a) => (askAnswered(a) ? a : { ...a, dismissed: true }));
@@ -2419,22 +2631,22 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                     mockId: mock.id,
                     version: Math.max(1, ...posts.map((p) => p.version)),
                     answers: {},
-                    mix: {},
+                    borrowed: {},
                     tuned: {},
                     comments: [],
-                    resolved: { dismissed },
+                    closed: { dismissed },
                 },
                 asks,
                 accept: [],
                 archive: [],
-                resolvedAt: at,
+                closedAt: at,
             })
             : null;
         if (comment)
             announceComment(comment);
         else {
             // No agent to tell: the mock still leaves the open list.
-            await store.updateMock(mock.id, { asks, resolvedAt: at });
+            await store.updateMock(mock.id, { asks, closedAt: at });
             await store.putDraft(mock.id, null);
         }
         bus.broadcast({ type: "mock-updated", id: mock.id, project: mock.project });
@@ -2442,7 +2654,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         const after = (await store.getMock(mock.id)) ?? mock;
         return ok({ mock: mockSummaryView(after, posts), dismissed });
     }
-    // Back from Resolved: the asks it dismissed are open again. The agent was
+    // Back from Closed: the asks it dismissed are open again. The agent was
     // told they were dismissed; answers given now reach it as a normal Send.
     async function reopenFlow(ref, ctx) {
         if (!ctx.viewer)
@@ -2451,10 +2663,10 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         if (isResult(mock))
             return mock;
         const posts = await store.listPosts({ mockId: mock.id });
-        if (!mock.resolvedAt)
+        if (!mock.closedAt)
             return ok({ mock: mockSummaryView(mock, posts) });
         const asks = mock.asks.map(({ dismissed: _, ...a }) => a);
-        const updated = await store.updateMock(mock.id, { asks, resolvedAt: null });
+        const updated = await store.updateMock(mock.id, { asks, closedAt: null });
         if (!updated)
             return fail(404, "mock not found");
         bus.broadcast({ type: "mock-updated", id: mock.id, project: mock.project });
@@ -2479,7 +2691,44 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             version: updated.version,
             by: "user",
         });
-        return ok({ state: updated.state, variant: updated.variant, status: updated.status });
+        return ok({
+            state: updated.state,
+            variant: updated.variant,
+            status: variantStatus(updated.status),
+        });
+    }
+    // The user archives a variant they're done with, short of choosing another:
+    // Studio's × on its last version. Restore is the way back. The variant in
+    // use stays, because archiving it would leave the state with nothing chosen
+    // and no reply saying why.
+    async function archiveFlow(ref, body, ctx) {
+        if (!ctx.viewer)
+            return viewerOnly();
+        const mock = await resolveMock(ref);
+        if (isResult(mock))
+            return mock;
+        const posts = await store.listPosts({ mockId: mock.id });
+        const chosen = chooseVariant(mock, posts, stateArg(body?.state), str(body?.variant, MAX_LABEL));
+        if (isResult(chosen))
+            return chosen;
+        if (variantStatus(chosen.status) === "inUse")
+            return fail(409, `${chosen.variant} is in use`);
+        const updated = await store.setPostStatus(chosen.id, "archived");
+        if (!updated)
+            return fail(404, "variant not found");
+        bus.broadcast({
+            type: "post-updated",
+            id: updated.id,
+            mockId: mock.id,
+            sessionId: updated.sessionId,
+            version: updated.version,
+            by: "user",
+        });
+        return ok({
+            state: updated.state,
+            variant: updated.variant,
+            status: variantStatus(updated.status),
+        });
     }
     // The user stars (or unstars) a variant: a favourite to come back to, which
     // decides nothing. Viewer-only; the agent reads it as `starred`.
@@ -2557,6 +2806,216 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         bus.broadcast({ type: "mock-deleted", id: mock.id, project: mock.project });
         return ok({ ok: true });
     }
+    // A write's feedback for the session that made it, when it named one: an
+    // edit needs no session, so without one there is no cursor to read from.
+    const feedbackFor = async (session, base) => typeof session === "string" && session ? collectFeedback(session, base) : [];
+    // `edit`: a mock's own fields, without a new version. A new slug rewrites
+    // every reference to the old one in the project (store.renameMock), so pages
+    // keep showing it and flows keep walking it.
+    async function editMockFlow(ref, body, ctx) {
+        if (!body || typeof body !== "object")
+            return fail(400, "invalid JSON body");
+        const given = ["slug", "title", "kind", "area", "source"].filter((k) => body[k] !== undefined);
+        if (given.length === 0) {
+            return fail(400, 'provide one of "slug", "title", "kind", "area" or "source"');
+        }
+        const mock = await resolveMock(ref, body.project, body.session);
+        if (isResult(mock))
+            return mock;
+        const slugIn = body.slug === undefined ? undefined : str(body.slug, MAX_TITLE);
+        if (body.slug !== undefined && !slugIn)
+            return fail(400, '"slug" must name the mock, e.g. "onni"');
+        const slug = slugIn === undefined ? undefined : slugify(slugIn);
+        const title = str(body.title, MAX_TITLE);
+        if (body.title !== undefined && !title)
+            return fail(400, '"title" must be non-empty text');
+        if (body.kind !== undefined && !isMockKind(body.kind)) {
+            return fail(400, '"kind" must be page, component or sketch');
+        }
+        const kind = body.kind;
+        const area = labelArg(body, "area", MAX_LABEL);
+        if (isResult(area))
+            return area;
+        const source = labelArg(body, "source", MAX_SOURCE);
+        if (isResult(source))
+            return source;
+        const renaming = slug !== undefined && slug !== mock.slug;
+        if (renaming && (await store.findMock(mock.project, slug))) {
+            return fail(409, `${mock.project} already has a mock "${slug}"; pick another slug`);
+        }
+        // Being embedded is what makes a mock a component: a sketch that is still
+        // embedded would be promoted back on its embedder's next publish.
+        if (kind === "sketch" && mock.kind !== "sketch") {
+            const embedders = await embeddersOf(mock.project, mock.slug);
+            if (embedders.length) {
+                return fail(409, `${mock.slug} is embedded in ${embedders.map((m) => m.slug).join(", ")}; being embedded makes it a component. Take the embeds out first`, { embeddedIn: embedders.map((m) => m.slug) });
+            }
+        }
+        let next = mock;
+        // The rename goes first: it is the part that can still lose a race for the slug.
+        if (renaming) {
+            const renamed = await store.renameMock(mock.id, slug);
+            if (!renamed)
+                return fail(409, `${mock.project} already has a mock "${slug}"`);
+            next = renamed;
+            clearRenderCache();
+        }
+        if (title !== undefined || kind !== undefined || area !== undefined || source !== undefined) {
+            next =
+                (await store.updateMock(mock.id, {
+                    ...(title === undefined ? {} : { title }),
+                    ...(kind === undefined ? {} : { kind }),
+                    ...(area === undefined ? {} : { area }),
+                    ...(source === undefined ? {} : { source }),
+                })) ?? next;
+        }
+        bus.broadcast({ type: "mock-updated", id: next.id, project: next.project });
+        if (renaming)
+            await announceEmbedders(next);
+        if (ctx.viewer)
+            await tellAgentEdited(mock, next);
+        // Flows are declared apart from kind, so a page that stops being one stays
+        // in them until the agent takes it out.
+        const nudges = [...titleNudges(title)];
+        if (kind !== undefined && kind !== "page" && mock.kind === "page") {
+            for (const f of await store.listFlows(next.project)) {
+                if (!f.steps.some((x) => x.mock === next.slug))
+                    continue;
+                nudges.push(`${next.slug} is still a step of flow "${f.name}"; publish it with flow "${f.name}" and step 0 to take it out`);
+            }
+        }
+        return ok({
+            mock: {
+                id: next.id,
+                project: next.project,
+                slug: next.slug,
+                title: next.title,
+                kind: next.kind,
+                ...placeOf(next),
+                states: next.states,
+            },
+            ...(renaming ? { renamed: { from: mock.slug, to: next.slug } } : {}),
+            url: mockUrl(ctx.base, next),
+            ...(nudges.length ? { nudges } : {}),
+            feedback: await feedbackFor(body.session, ctx.base),
+        });
+    }
+    // The user moved a mock from Home (another kind or area): the agent hears it
+    // once, through the same cursor as a Send, on the session driving the mock.
+    // Nothing to tell when no agent has written it.
+    async function tellAgentEdited(before, after) {
+        const edited = {
+            ...(after.kind !== before.kind ? { kind: after.kind } : {}),
+            ...(after.area !== before.area ? { area: after.area } : {}),
+        };
+        if (Object.keys(edited).length === 0)
+            return;
+        const posts = await store.listPosts({ mockId: after.id });
+        const latest = [...posts].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))[0];
+        const sessionId = after.sessionId ?? latest?.sessionId;
+        if (!sessionId)
+            return;
+        const comment = await store.commitReply({
+            mockId: after.id,
+            sessionId,
+            text: "",
+            payload: {
+                mockId: after.id,
+                version: Math.max(1, ...posts.map((p) => p.version)),
+                answers: {},
+                borrowed: {},
+                tuned: {},
+                comments: [],
+                edited,
+            },
+            asks: after.asks,
+            accept: [],
+            archive: [],
+            keepDraft: true,
+        });
+        if (comment)
+            announceComment(comment);
+    }
+    const areaOrderOf = async (project) => {
+        const raw = await store.getSetting(`${AREA_ORDER_SETTING}:${project}`);
+        if (!raw)
+            return [];
+        try {
+            const v = JSON.parse(raw);
+            return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+        }
+        catch {
+            return [];
+        }
+    };
+    // `areaOrder`: the areas in the order Home lists them; [] (or "") hands the
+    // order back to the alphabet.
+    function areaOrderArg(v) {
+        const list = typeof v === "string" ? v.split(",") : v;
+        if (!Array.isArray(list) || list.some((x) => typeof x !== "string")) {
+            return fail(400, '"areaOrder" must be a list of area names, e.g. ["Shell", "Food"]');
+        }
+        const names = [...new Set(list.map((x) => stripNul(x).trim()).filter(Boolean))];
+        if (names.length > MAX_AREAS)
+            return fail(400, `"areaOrder" takes at most ${MAX_AREAS} areas`);
+        if (names.some((x) => x.length > MAX_LABEL)) {
+            return fail(400, `an area name is at most ${MAX_LABEL} characters`);
+        }
+        return names;
+    }
+    // `edit` on a project: a new name for it, carrying its mocks, sessions,
+    // flows and settings (refused onto a project that already has mocks), and
+    // the order Home lists its areas in.
+    async function editProjectFlow(name, body, ctx) {
+        if (!body || typeof body !== "object")
+            return fail(400, "invalid JSON body");
+        const from = str(name, MAX_TITLE);
+        if (!from)
+            return fail(400, "provide the project to edit");
+        if (body.name === undefined && body.areaOrder === undefined) {
+            return fail(400, 'provide "name" (the project\'s new name) or "areaOrder"');
+        }
+        const to = body.name === undefined ? undefined : str(body.name, MAX_TITLE);
+        if (body.name !== undefined && !to)
+            return fail(400, '"name" must be the project\'s new name');
+        if (to === from)
+            return fail(400, `${from} already has that name`);
+        const order = body.areaOrder === undefined ? undefined : areaOrderArg(body.areaOrder);
+        if (isResult(order))
+            return order;
+        const mocks = await store.listMocks(from);
+        if (mocks.length === 0)
+            return fail(404, `no project "${from}" with mocks`);
+        if (to !== undefined) {
+            if (!(await store.renameProject(from, to))) {
+                return fail(409, `${to} already has mocks; pick another name`);
+            }
+            clearRenderCache();
+        }
+        const project = to ?? from;
+        if (order !== undefined) {
+            await store.setSetting(`${AREA_ORDER_SETTING}:${project}`, JSON.stringify(order));
+        }
+        for (const m of mocks)
+            bus.broadcast({ type: "mock-updated", id: m.id, project });
+        const named = new Set(mocks.flatMap((m) => (m.area ? [m.area] : [])));
+        const unnamed = (order ?? []).filter((a) => !named.has(a));
+        return ok({
+            project,
+            ...(to === undefined ? {} : { renamed: { from, to } }),
+            ...(order === undefined ? {} : { areaOrder: order }),
+            mocks: mocks.length,
+            url: `${ctx.base}/project/${encodeURIComponent(project)}`,
+            ...(unnamed.length
+                ? {
+                    nudges: [
+                        `no mock in ${project} has area ${unnamed.map((a) => `"${a}"`).join(", ")} yet; Home lists it once one does`,
+                    ],
+                }
+                : {}),
+            feedback: await feedbackFor(body.session, ctx.base),
+        });
+    }
     // --- comments ---
     function numberInRange(value, min, max) {
         const n = Number(value);
@@ -2883,7 +3342,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     const pendingOf = (mock, posts) => ({
         mock: mock.slug,
         // Closed by the user: nothing there is waiting on them, or on you.
-        ...(mock.resolvedAt ? { resolved: true } : {}),
+        ...(mock.closedAt ? { closed: true } : {}),
         viewerOpen: viewing.has(mock.id),
         draft: mock.draft
             ? {
@@ -3195,6 +3654,17 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     const flag = (c, key) => c.req.query(key) === "1";
     // --- sessions ---
     app.get("/api/sessions", async (c) => {
+        // A watcher started with every conversation finds that conversation's
+        // session without creating one, and never mistakes a sibling's in the same
+        // repo for its own.
+        const key = c.req.query("key");
+        if (key !== undefined) {
+            const session = key ? await store.getSessionByKey(key) : null;
+            if (!session)
+                return c.json([]);
+            const posts = await store.listPosts({ sessionId: session.id });
+            return c.json([sessionRowView(session, posts.length)]);
+        }
         const [sessions, counts] = await Promise.all([
             store.listSessions(),
             store.countPostsBySession(),
@@ -3280,6 +3750,15 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             variant: c.req.query("variant"),
         }, flowCtx(c)));
     });
+    app.patch("/api/mocks/:id", async (c) => {
+        const body = await jsonBody(c);
+        // A slug names its project in the body or, as on the reads, in the query.
+        const project = c.req.query("project");
+        const withProject = body && typeof body === "object" && body.project === undefined && project
+            ? { ...body, project }
+            : body;
+        return send(c, await editMockFlow(c.req.param("id"), withProject, flowCtx(c)));
+    });
     app.delete("/api/mocks/:id", async (c) => send(c, await removeMockFlow(c.req.param("id"), { project: c.req.query("project") })));
     app.post("/api/mocks/:id/asks", async (c) => send(c, await askFlow(c.req.param("id"), await jsonBody(c), flowCtx(c))));
     app.get("/api/mocks/:id/draft", async (c) => send(c, await getDraftFlow(c.req.param("id"), flowCtx(c))));
@@ -3288,9 +3767,10 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     app.post("/api/mocks/:id/reply", async (c) => send(c, await replyFlow(c.req.param("id"), await jsonBody(c), flowCtx(c))));
     app.post("/api/mocks/:id/use", async (c) => send(c, await useFlow(c.req.param("id"), await jsonBody(c), flowCtx(c))));
     app.post("/api/mocks/:id/hide", async (c) => send(c, await hideFlow(c.req.param("id"), await jsonBody(c), flowCtx(c))));
-    app.post("/api/mocks/:id/resolve", async (c) => send(c, await resolveFlow(c.req.param("id"), flowCtx(c))));
+    app.post("/api/mocks/:id/close", async (c) => send(c, await closeFlow(c.req.param("id"), flowCtx(c))));
     app.post("/api/mocks/:id/reopen", async (c) => send(c, await reopenFlow(c.req.param("id"), flowCtx(c))));
     app.post("/api/mocks/:id/star", async (c) => send(c, await starFlow(c.req.param("id"), await jsonBody(c), flowCtx(c))));
+    app.post("/api/mocks/:id/archive", async (c) => send(c, await archiveFlow(c.req.param("id"), await jsonBody(c), flowCtx(c))));
     app.post("/api/mocks/:id/restore", async (c) => send(c, await restoreFlow(c.req.param("id"), await jsonBody(c))));
     app.post("/api/mocks/:id/variants/:postId/restore", async (c) => send(c, await restoreVersionFlow(c.req.param("id"), c.req.param("postId"), await jsonBody(c), flowCtx(c))));
     app.post("/api/mocks/:id/say", async (c) => send(c, await sayFlow(c.req.param("id"), await jsonBody(c), flowCtx(c))));
@@ -3421,7 +3901,14 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     // The project's design system, imported by `mockpit init` and injected into
     // every html surface of the project (see renderHtmlPage).
     app.get("/api/projects/:name/tree", async (c) => send(c, await treeFlow({ project: c.req.param("name") })));
+    app.patch("/api/projects/:name", async (c) => send(c, await editProjectFlow(c.req.param("name"), await jsonBody(c), flowCtx(c))));
     app.get("/api/projects/:name/design", async (c) => c.json(await designFor(c.req.param("name"))));
+    // A project's rules file (.mockpit/rules.md, sent by `mockpit rules` and
+    // `mockpit init`) and the user's own (`mockpit rules --mine`).
+    app.get("/api/projects/:name/rules", async (c) => c.json({ text: (await store.getSetting(`${RULES_SETTING}:${c.req.param("name")}`)) ?? "" }));
+    app.put("/api/projects/:name/rules", async (c) => send(c, await saveRules(`${RULES_SETTING}:${c.req.param("name")}`, await jsonBody(c))));
+    app.get("/api/rules", async (c) => c.json({ text: (await userRulesText()) ?? "" }));
+    app.put("/api/rules", async (c) => send(c, await saveRules(USER_RULES_SETTING, await jsonBody(c))));
     app.put("/api/projects/:name/design", async (c) => {
         const body = await c.req.json().catch(() => null);
         if (!body || typeof body !== "object")
@@ -3737,9 +4224,9 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         // The runtime's module cache makes every later call cheap, so there's no memo
         // here to keep in sync. On the Worker the module is already inside the
         // deployed bundle — the import defers evaluating it, not fetching it — so this
-        // needs no network at runtime. test/workerIntegration covers that on real
-        // workerd, because a dynamic import resolving differently there is exactly the
-        // way this optimization could break in production and nowhere else.
+        // needs no network at runtime. Check it on real workerd (`npm run dev:cloud`):
+        // a dynamic import resolving differently there is exactly the way this
+        // optimization could break in production and nowhere else.
         const { renderCode, renderDiff, renderMarkdown, renderTerminal } = await import("./richRender.js");
         const rendered = surface.kind === "markdown"
             ? await renderMarkdown(surface, { theme: themeId, mode })
@@ -4160,6 +4647,8 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         exportMock: (ref, query, ctx) => exportFlow(ref, query, ctx),
         say: (ref, body, ctx) => sayFlow(ref, body, ctx),
         feedback: (query, ctx) => feedbackFlow(query, ctx),
+        edit: (ref, body, ctx) => editMockFlow(ref, body, ctx),
+        editProject: (name, body, ctx) => editProjectFlow(name, body, ctx),
     };
     const guide = (project, topic) => topic ? (topics[topic] ?? "") : briefFor(project);
     // --- run: an agent script over the same flows (server/run.ts) ---