mockpit 2.0.0 → 3.1.0

package/dist/server/guidance.js

@@ -5,9 +5,9 @@
 // reads is the one that wins.
 //
 // Runtime-agnostic (no node imports): the Worker builds the brief too.
-export const GUIDE_PACKS = ["design-craft"];
+export const GUIDE_PACKS = ["design-craft", "foundations"];
 const isGuidePack = (id) => GUIDE_PACKS.includes(id);
-// `rules:<project>` sits beside `design:<project>` and moves with a project
+// `rules:<project>` is a project setting and moves with a project
 // rename. The user's own rules are not a project, so their key has no colon:
 // a project named "user" can't collide with it.
 export const RULES_SETTING = "rules";

package/dist/server/handoff.d.ts

@@ -1,6 +1,9 @@
 import type { Comment, Session } from "./types.ts";
 export declare const HANDOFF_GRACE_MS: number;
-export declare const HANDOFF_NOTE = "Sent to an earlier agent session in this project that has gone quiet; it is yours now. Read the mock before acting.";
+export declare const HANDOFF_NOTE = "Sent to an earlier agent session in this project that has gone quiet; it is yours now. Read the design before acting.";
+export declare const ROUTED_NOTE = "The agent that asked this wasn't listening, so the user sent it to you; it is yours now. Read the design before acting.";
+export declare const OWNER_BUSY_MS: number;
 export declare const ownerActiveAt: (s: Session) => string;
+export declare const sessionName: (s: Session) => string;
 export declare function supersedes(taker: Session, owner: Session, listening: boolean): boolean;
 export declare function handoffReady(comment: Comment, owner: Session, taker: Session, now: number): boolean;

package/dist/server/handoff.js

@@ -1,4 +1,4 @@
-// Orphaned replies: a Send lands on the session that owns the mock, and when
+// Orphaned replies: a Send lands on the session that owns the design, and when
 // that agent restarts into a new session (a new conversation, /clear, a crash)
 // nobody would ever read it. The rule below decides when a newer session may
 // take such a reply instead. Runtime-agnostic (no node imports).
@@ -20,8 +20,14 @@
 // it got before the taker existed goes at once — the user answered, then
 // restarted. A keyed owner always gets the grace: its conversation may resume.
 export const HANDOFF_GRACE_MS = 2 * 60_000;
-export const HANDOFF_NOTE = "Sent to an earlier agent session in this project that has gone quiet; it is yours now. Read the mock before acting.";
+export const HANDOFF_NOTE = "Sent to an earlier agent session in this project that has gone quiet; it is yours now. Read the design before acting.";
+export const ROUTED_NOTE = "The agent that asked this wasn't listening, so the user sent it to you; it is yours now. Read the design before acting.";
+// A waiter stops between a wake and the end of that turn, so an owner that called
+// this recently is working, not gone, and keeps its replies. Same span as "Agent working".
+export const OWNER_BUSY_MS = 5 * 60_000;
 export const ownerActiveAt = (s) => s.agentActiveAt ?? s.lastActiveAt;
+// All the user can recognise a session by: most have no title, and ids mean nothing.
+export const sessionName = (s) => s.cwd?.split(/[\\/]/).filter(Boolean).pop() ?? s.agent;
 export function supersedes(taker, owner, listening) {
     return (owner.id !== taker.id &&
         owner.project !== null &&

package/dist/server/icons.js

@@ -4,7 +4,7 @@
 // imports): it runs inside renderHtmlPage on the Worker too.
 // Served with the server rather than installed per project: lucide (ISC) is
 // what agents reach for by default, mage (Apache-2.0) is what `mockpit init`
-// used to upload as a sprite, so mocks written against it keep rendering.
+// used to upload as a sprite, so designs written against it keep rendering.
 export const BUNDLED_ICON_PREFIXES = ["lucide", "mage"];
 const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
 export const isIconName = (s) => typeof s === "string" && NAME_RE.test(s);

package/dist/server/index.js

@@ -1,7 +1,9 @@
 import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+import { compress } from "hono/compress";
 import { createHash } from "node:crypto";
 import { readdir, readFile } from "node:fs/promises";
-import { homedir } from "node:os";
+import { homedir, networkInterfaces } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createApp } from "./app.js";
@@ -40,6 +42,10 @@ for (const name of (await readdir(serverDir)).sort()) {
         renderHash.update(await readFile(join(serverDir, name)));
 }
 renderHash.update(await readFile(join(root, "package-lock.json")).catch(() => pkgJson));
+// Browsers keep a version's document for a year, so a version changed outside
+// the API (a direct store edit) stays stale in them; a new salt on restart
+// re-fetches every document without touching code.
+renderHash.update(process.env.MOCKPIT_RENDER_SALT ?? "");
 const renderRev = renderHash.digest("hex").slice(0, 10);
 const pr = process.env.MOCKPIT_PUBLIC_READ;
 const publicRead = pr === "session" || pr === "full" ? pr : undefined;
@@ -48,7 +54,9 @@ const publicRead = pr === "session" || pr === "full" ? pr : undefined;
 // default lives in ~/.mockpit/, a user-owned dir that survives reinstalls and
 // is writable however the package was installed.
 const dbPath = process.env.MOCKPIT_DB ?? join(homedir(), ".mockpit", "mockpit.db");
-const store = new SqlStore(createSqliteStorage(dbPath));
+// Far past the Durable Object's budget: one lab of inlined pages can be 70 MB,
+// and a design that doesn't fit is re-read and re-parsed on every request.
+const store = new SqlStore(createSqliteStorage(dbPath), { postCacheBytes: 256 * 1024 * 1024 });
 console.log(`mockpit store: SQLite at ${dbPath}`);
 // The event log is on by default, next to the database, so a session can be
 // diagnosed after the fact without having planned to (`scripts/inspect.ts`).
@@ -64,6 +72,27 @@ if (logPath)
 // database never picks up the real ones.
 const rulesPath = dbPath === ":memory:" ? undefined : join(dirname(dbPath), "rules.md");
 const userRules = rulesPath ? () => readFile(rulesPath, "utf8").catch(() => null) : undefined;
+const port = Number(process.env.PORT ?? 8228);
+// MOCKPIT_HOST (or `serve --host`) restricts the listener to one address.
+// Unset keeps the previous behaviour — node's default, every interface — because
+// that is what a container or a LAN-shared instance needs. Set it to 127.0.0.1
+// when the server shares a host with anything you don't want reaching it; that
+// is stronger than the token, which is a single shared secret by design.
+const hostname = process.env.MOCKPIT_HOST || undefined;
+// The addresses a phone might open this server at. Read when asked, since a laptop
+// changes networks while it runs.
+const networkHosts = () => {
+    if (hostname === "127.0.0.1" || hostname === "::1" || hostname === "localhost") {
+        return { localOnly: true, hosts: [] };
+    }
+    if (hostname && hostname !== "0.0.0.0" && hostname !== "::") {
+        return { localOnly: false, hosts: [`${hostname}:${port}`] };
+    }
+    const hosts = Object.values(networkInterfaces())
+        .flat()
+        .flatMap((a) => (a && a.family === "IPv4" && !a.internal ? [`${a.address}:${port}`] : []));
+    return { localOnly: false, hosts: hosts.slice(0, 3) };
+};
 const app = createApp({
     store,
     viewerHtml,
@@ -80,16 +109,16 @@ const app = createApp({
     renderRev,
     // `run` scripts execute in QuickJS inside a worker thread per run.
     executor: createNodeExecutor(),
+    networkHosts,
     log: logPath ? createFileLog(logPath) : undefined,
 });
-const port = Number(process.env.PORT ?? 8228);
-// MOCKPIT_HOST (or `serve --host`) restricts the listener to one address.
-// Unset keeps the previous behaviour — node's default, every interface — because
-// that is what a container or a LAN-shared instance needs. Set it to 127.0.0.1
-// when the server shares a host with anything you don't want reaching it; that
-// is stronger than the token, which is a single shared secret by design.
-const hostname = process.env.MOCKPIT_HOST || undefined;
-serve({ fetch: app.fetch, port, hostname }, (info) => {
+// Cloudflare compresses at its edge; a Node server reached over a network
+// (a tailnet, a LAN) would otherwise send the viewer and every list uncompressed.
+// Hono's filter leaves SSE streams alone.
+const outer = new Hono();
+outer.use(compress());
+outer.all("*", (c) => app.fetch(c.req.raw, c.env));
+serve({ fetch: outer.fetch, port, hostname }, (info) => {
     // Report the address actually bound. Printing "localhost" unconditionally hid
     // the fact that the default listens on every interface.
     const shown = hostname ?? "localhost";

package/dist/server/jump.d.ts

@@ -0,0 +1,21 @@
+import { type JumpRows, type DesignKind } from "./types.ts";
+export type JumpMatch = "title" | "state" | "variant" | "area" | "question" | "description";
+export interface JumpHit {
+    project: string;
+    id: string | null;
+    slug: string | null;
+    title: string;
+    kind: DesignKind | null;
+    width: number | null;
+    area: string | null;
+    match: JumpMatch;
+    text: string | null;
+    state: string | null;
+    variant: string | null;
+    archived: boolean;
+    open: number;
+    designArchived: boolean;
+    inUse: boolean;
+}
+export declare function jumpHits(rows: JumpRows, query: string, project: string | null): JumpHit[];
+export declare function recentHits(rows: JumpRows, ids: string[]): JumpHit[];

package/dist/server/jump.js

@@ -0,0 +1,175 @@
+// Search to jump: find a design by anything the user might remember it by, its
+// title, a state, a variant's name or note, a question, or its area. It reads
+// what `listJumpRows` hands it, which never includes surfaces, so a big
+// workspace costs its metadata and not its pages. This project comes first, then
+// the others. Runtime-agnostic (no node imports).
+import { isLive, openAsks } from "./types.js";
+const MAX_HERE = 20;
+const MAX_ELSEWHERE = 12;
+// A design whose variants all carry the word shouldn't push every other design off the list.
+const MAX_PER_DESIGN = 3;
+const SNIPPET = 90;
+// Precision before recall: what a design is called beats what was once said about it.
+const RANK = {
+    exact: 0,
+    prefix: 1,
+    word: 2,
+    title: 3,
+    state: 4,
+    variant: 5,
+    area: 6,
+    question: 7,
+    description: 8,
+};
+// "Cafe" finds "Café", and "food" finds "Food".
+const fold = (s) => s.normalize("NFD").replace(/\p{M}/gu, "").toLowerCase();
+function clip(text, term) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    if (flat.length <= SNIPPET)
+        return flat;
+    const at = Math.max(0, fold(flat).indexOf(term));
+    const start = at < SNIPPET / 3 ? 0 : at - Math.floor(SNIPPET / 3);
+    const cut = flat.slice(start, start + SNIPPET).trim();
+    return `${start > 0 ? "…" : ""}${cut}${start + SNIPPET < flat.length ? "…" : ""}`;
+}
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function allHits(rows, terms, whole) {
+    const byDesign = new Map();
+    for (const v of rows.variants) {
+        const list = byDesign.get(v.designId);
+        if (list)
+            list.push(v);
+        else
+            byDesign.set(v.designId, [v]);
+    }
+    const has = (text) => {
+        const f = fold(text);
+        return terms.every((t) => f.includes(t));
+    };
+    const out = [];
+    const areasSeen = new Set();
+    for (const m of rows.designs) {
+        const variants = byDesign.get(m.id) ?? [];
+        const base = {
+            project: m.project,
+            id: m.id,
+            slug: m.slug,
+            title: m.title,
+            kind: m.kind,
+            width: m.widths[0] ?? null,
+            area: m.area,
+            open: openAsks(m).length,
+            designArchived: !!m.archivedAt,
+            inUse: variants.some((v) => v.status === "accepted"),
+            text: null,
+            state: null,
+            variant: null,
+            archived: false,
+        };
+        const mine = [];
+        const add = (rank, match, extra = {}) => mine.push({ hit: { ...base, match, ...extra }, rank, updatedAt: m.updatedAt });
+        const title = fold(m.title);
+        if (title === whole)
+            add(RANK.exact, "title");
+        else if (title.startsWith(whole))
+            add(RANK.prefix, "title");
+        else if (terms.every((t) => new RegExp(`(^|[^\\p{L}\\p{N}])${escapeRe(t)}`, "u").test(title)))
+            add(RANK.word, "title");
+        else if (has(m.title) || has(m.slug))
+            add(RANK.title, "title");
+        for (const state of m.states) {
+            if (has(state))
+                add(RANK.state, "state", { text: state, state });
+        }
+        const namesSeen = new Set();
+        for (const v of variants) {
+            const gone = !isLive(v.status);
+            const tail = gone ? 0.5 : 0;
+            // A variant named "default" says nothing the design's title doesn't.
+            if (v.variant !== "default" && !namesSeen.has(v.variant) && has(v.variant)) {
+                namesSeen.add(v.variant);
+                add(RANK.variant + tail, "variant", {
+                    text: v.variant,
+                    state: v.state,
+                    variant: v.variant,
+                    archived: gone,
+                });
+            }
+            if (v.description && has(v.description)) {
+                add(RANK.description + tail, "description", {
+                    text: clip(v.description, terms[0]),
+                    state: v.state,
+                    variant: v.variant,
+                    archived: gone,
+                });
+            }
+        }
+        for (const ask of m.asks) {
+            if (has(ask.text)) {
+                add(RANK.question, "question", {
+                    text: clip(ask.text, terms[0]),
+                    state: ask.state ?? null,
+                });
+            }
+        }
+        mine.sort((a, b) => a.rank - b.rank);
+        out.push(...mine.slice(0, MAX_PER_DESIGN));
+        if (m.area && has(m.area) && !areasSeen.has(`${m.project}\n${m.area}`)) {
+            areasSeen.add(`${m.project}\n${m.area}`);
+            out.push({
+                hit: {
+                    ...base,
+                    id: null,
+                    slug: null,
+                    title: m.area,
+                    kind: null,
+                    width: null,
+                    match: "area",
+                    open: 0,
+                    designArchived: false,
+                    inUse: false,
+                },
+                rank: RANK.area,
+                updatedAt: m.updatedAt,
+            });
+        }
+    }
+    return out;
+}
+export function jumpHits(rows, query, project) {
+    const whole = fold(query).trim().replace(/\s+/g, " ");
+    const terms = whole.split(" ").filter(Boolean);
+    if (!terms.length)
+        return [];
+    const order = (a, b) => a.rank - b.rank || b.updatedAt.localeCompare(a.updatedAt);
+    const all = allHits(rows, terms, whole);
+    const here = all.filter((h) => h.hit.project === project).sort(order);
+    const elsewhere = all.filter((h) => h.hit.project !== project).sort(order);
+    return [...here.slice(0, MAX_HERE), ...elsewhere.slice(0, MAX_ELSEWHERE)].map((h) => h.hit);
+}
+// The designs this browser opened last, in that order, as they are called now: a
+// renamed one follows, and a deleted one drops out.
+export function recentHits(rows, ids) {
+    const wanted = new Map(ids.map((id, i) => [id, i]));
+    const inUse = new Set(rows.variants.filter((v) => v.status === "accepted").map((v) => v.designId));
+    return rows.designs
+        .filter((m) => wanted.has(m.id))
+        .sort((a, b) => wanted.get(a.id) - wanted.get(b.id))
+        .map((m) => ({
+        project: m.project,
+        id: m.id,
+        slug: m.slug,
+        title: m.title,
+        kind: m.kind,
+        width: m.widths[0] ?? null,
+        area: m.area,
+        match: "title",
+        text: null,
+        state: null,
+        variant: null,
+        archived: false,
+        open: openAsks(m).length,
+        designArchived: !!m.archivedAt,
+        inUse: inUse.has(m.id),
+    }));
+}

package/dist/server/kits.d.ts

@@ -14,18 +14,18 @@ export declare const KITS: Kit[];
 export declare const isKnownKit: (id: unknown) => id is string;
 export declare const KIT_IDS: string[];
 export declare const kitSummaries: (projectKits?: readonly ProjectKit[]) => ({
-    href?: string | undefined;
     id: string;
     source: "bundled";
     label: string;
     summary: string;
     classes: string;
+    href?: string | undefined;
 } | {
-    source: "project";
     id: string;
     href: string;
     script?: string;
     doc: string;
+    source: "project";
 })[];
 export declare const RESERVED_KIT_IDS: string[];
 export declare const PROJECT_KIT_DOC_MAX = 1200;

package/dist/server/kits.js

@@ -165,6 +165,52 @@ const BUILTIN_CSS = `
 const BASECOAT_THEME_CSS = `
 :root{--radius:var(--border-radius-md);--background:var(--color-background-primary);--foreground:var(--color-text-primary);--card:var(--color-background-primary);--card-foreground:var(--color-text-primary);--popover:var(--color-background-primary);--popover-foreground:var(--color-text-primary);--primary:var(--color-text-primary);--primary-foreground:var(--color-background-primary);--secondary:var(--color-background-secondary);--secondary-foreground:var(--color-text-primary);--muted:var(--color-background-secondary);--muted-foreground:var(--color-text-secondary);--accent:var(--color-background-secondary);--accent-foreground:var(--color-text-primary);--destructive:var(--color-text-danger);--border:var(--color-border-secondary);--input:var(--color-border-secondary);--ring:var(--color-border-info)}
 `;
+// layout: composition primitives that say how boxes relate, never how they look. Every
+// gap is `--space`, which falls back to `--layout-space`: the base step of the
+// project's space scale when its system has one (system.ts), else 1rem. Each takes
+// its measure from a custom property on the element (`style="--space: var(--space-l)"`),
+// so a page sets a step without a new class. Those properties don't inherit, so a
+// layout nested in another starts from the defaults, not its parent's measure; what
+// a primitive's children read, it passes down as its own `--l-*`.
+//
+// A cover fills the screen, but a frame is sized from its content, so 100vh grows with
+// the cover it sizes: the cap ends that, and border-box keeps the padding inside.
+const LAYOUT_CSS = `
+@property --space{syntax:"*";inherits:false}
+@property --measure{syntax:"*";inherits:false}
+@property --side{syntax:"*";inherits:false}
+@property --threshold{syntax:"*";inherits:false}
+@property --min{syntax:"*";inherits:false}
+@property --item{syntax:"*";inherits:false}
+.l-stack,.l-cluster,.l-sidebar,.l-switcher,.l-grid,.l-reel{gap:var(--space,var(--layout-space,1rem))}
+.l-stack{display:flex;flex-direction:column}
+.l-stack>*{margin-block:0}
+.l-box{padding:var(--space,var(--layout-space,1rem))}
+.l-center{box-sizing:content-box;max-inline-size:var(--measure,65ch);margin-inline:auto;padding-inline:var(--gutter,0)}
+.l-cluster{display:flex;flex-wrap:wrap;justify-content:var(--justify,flex-start);align-items:var(--align,center)}
+.l-sidebar{display:flex;flex-wrap:wrap;align-items:var(--align,stretch);--l-side:var(--side,16rem)}
+.l-sidebar>*{flex-grow:1}
+.l-sidebar>:first-child{flex-basis:var(--l-side)}
+.l-sidebar>:last-child{flex-basis:0;flex-grow:999;min-inline-size:var(--content-min,55%)}
+.l-sidebar.end>:first-child{flex-basis:0;flex-grow:999;min-inline-size:var(--content-min,55%)}
+.l-sidebar.end>:last-child{flex-basis:var(--l-side);flex-grow:1;min-inline-size:0}
+.l-switcher{display:flex;flex-wrap:wrap;--l-threshold:var(--threshold,32rem)}
+.l-switcher>*{flex-grow:1;flex-basis:calc((var(--l-threshold) - 100%) * 999)}
+.l-cover{display:flex;flex-direction:column;box-sizing:border-box;min-block-size:var(--min-height,min(100vh,50rem));--l-space:var(--space,var(--layout-space,1rem));padding:var(--l-space)}
+.l-cover>*{margin-block:var(--l-space)}
+.l-cover>:first-child{margin-block-start:0}
+.l-cover>:last-child{margin-block-end:0}
+.l-cover>.main{margin-block:auto}
+.l-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(var(--min,14rem),100%),1fr))}
+.l-frame{aspect-ratio:var(--ratio,16 / 9);overflow:hidden;display:flex;align-items:center;justify-content:center}
+.l-frame>img,.l-frame>video{inline-size:100%;block-size:100%;object-fit:cover}
+.l-reel{display:flex;overflow-x:auto;overflow-y:hidden;scroll-snap-type:x proximity;padding-block-end:var(--scroll-room,0);--l-item:var(--item,auto)}
+.l-reel>*{flex:0 0 var(--l-item);scroll-snap-align:start}
+.l-imposter{position:absolute;inset-block-start:50%;inset-inline-start:50%;translate:-50% -50%;max-inline-size:calc(100% - 2 * var(--margin,0px));max-block-size:calc(100% - 2 * var(--margin,0px));overflow:auto}
+.l-imposter.fixed{position:fixed}
+.l-icon{inline-size:.75em;block-size:.75em;inline-size:1cap;block-size:1cap;flex:none}
+.l-with-icon{display:inline-flex;align-items:baseline;gap:var(--icon-space,.5ch)}
+`;
 // Pinned to a major so fixes arrive without a server release. 1.x moved
 // variants from `.btn-primary` classes to `data-variant`.
 const BASECOAT_CDN = "https://cdn.jsdelivr.net/npm/basecoat-css@1/dist";
@@ -172,7 +218,7 @@ export const KITS = [
     {
         id: "builtin",
         label: "Builtin",
-        summary: "shadcn-shaped components (CSS only) for projects with no design system",
+        summary: "shadcn-shaped components (CSS only) for projects with no components of their own",
         classes: "btn · card · input · label · badge · tabs · dialog · table",
         css: BUILTIN_CSS,
     },
@@ -202,6 +248,13 @@ export const KITS = [
         // also drives dropdown-menu, select and popover markup.
         script: `${BASECOAT_CDN}/js/all.min.js`,
     },
+    {
+        id: "layout",
+        label: "Layout",
+        summary: 'composition primitives on the space scale; set a step with style="--space: var(--space-l)"',
+        classes: "l-stack · l-box · l-center (--measure) · l-cluster · l-sidebar[.end] (--side) · l-switcher (--threshold) · l-cover (>.main) · l-grid (--min) · l-frame (--ratio) · l-reel (--item) · l-imposter[.fixed] · l-icon · l-with-icon",
+        css: LAYOUT_CSS,
+    },
 ];
 const KIT_BY_ID = new Map(KITS.map((k) => [k.id, k]));
 export const isKnownKit = (id) => typeof id === "string" && KIT_BY_ID.has(id);

package/dist/server/knobs.d.ts

@@ -1,4 +1,4 @@
-import type { ExplicitKnob, KnobConfig, Knobs, KnobValue, Mock, Post } from "./types.ts";
+import type { ExplicitKnob, KnobConfig, Knobs, KnobValue, Design, Post } from "./types.ts";
 export type Checked<T> = {
     ok: true;
     value: T;
@@ -10,10 +10,10 @@ export declare function explicitKnob(config: KnobConfig): ExplicitKnob;
 export declare function checkKnobConfig(path: string, raw: unknown): Checked<KnobConfig>;
 export declare function checkKnobs(raw: unknown): Checked<Knobs>;
 export declare function checkKnobValue(path: string, config: KnobConfig, value: unknown): Checked<KnobValue>;
-export declare function knobFor(path: string, mock: Pick<Mock, "knobs">, posts: (Pick<Post, "knobs"> & {
+export declare function knobFor(path: string, design: Pick<Design, "knobs">, posts: (Pick<Post, "knobs"> & {
     surfaces?: Post["surfaces"];
 })[]): KnobConfig | undefined;
-export declare function checkKnobValues(raw: unknown, mock: Pick<Mock, "knobs">, posts: (Pick<Post, "knobs"> & {
+export declare function checkKnobValues(raw: unknown, design: Pick<Design, "knobs">, posts: (Pick<Post, "knobs"> & {
     surfaces?: Post["surfaces"];
 })[], what: string): Checked<Record<string, KnobValue>>;
 export declare function discreteChoices(config: KnobConfig): number | null;

package/dist/server/knobs.js

@@ -293,12 +293,12 @@ export function checkKnobValue(path, config, value) {
         }
     }
 }
-// The declared knob for a path: the mock's own, else a variant's override,
+// The declared knob for a path: the design's own, else a variant's override,
 // else the knob a variant's slot implies (fills.ts), so an option can `set` a
 // slot's fill without the agent declaring anything.
-export function knobFor(path, mock, posts) {
-    if (Object.hasOwn(mock.knobs, path))
-        return mock.knobs[path];
+export function knobFor(path, design, posts) {
+    if (Object.hasOwn(design.knobs, path))
+        return design.knobs[path];
     for (const p of posts)
         if (p.knobs && Object.hasOwn(p.knobs, path))
             return p.knobs[path];
@@ -311,7 +311,7 @@ export function knobFor(path, mock, posts) {
     }
     return undefined;
 }
-export function checkKnobValues(raw, mock, posts, what) {
+export function checkKnobValues(raw, design, posts, what) {
     if (raw === undefined || raw === null)
         return { ok: true, value: {} };
     if (typeof raw !== "object" || Array.isArray(raw)) {
@@ -319,7 +319,7 @@ export function checkKnobValues(raw, mock, posts, what) {
     }
     const out = {};
     for (const [path, value] of Object.entries(raw)) {
-        const config = knobFor(path, mock, posts);
+        const config = knobFor(path, design, posts);
         if (config === undefined)
             return { ok: false, error: `${what}: no knob "${path}" is declared` };
         const checked = checkKnobValue(path, config, value);

package/dist/server/mcpHttp.d.ts

@@ -11,13 +11,16 @@ export interface McpFlows {
     tree: Flow<[query: {
         project?: string;
     }]>;
+    decisions: Flow<[query: {
+        project?: string;
+    }]>;
     get: Flow<[ref: unknown, query: {
         project?: unknown;
         body?: boolean;
         history?: boolean;
     }]>;
     ask: Flow<[ref: unknown, body: any, ctx: FlowContext]>;
-    exportMock: Flow<[
+    exportDesign: Flow<[
         ref: unknown,
         query: {
             project?: unknown;
@@ -27,12 +30,15 @@ export interface McpFlows {
         ctx: FlowContext
     ]>;
     say: Flow<[ref: unknown, body: any, ctx: FlowContext]>;
+    move: Flow<[ref: unknown, body: any, ctx: FlowContext]>;
     feedback: Flow<[query: {
         session?: unknown;
         project?: unknown;
     }, ctx: FlowContext]>;
     edit: Flow<[ref: unknown, body: any, ctx: FlowContext]>;
     editProject: Flow<[name: unknown, body: any, ctx: FlowContext]>;
+    system: Flow<[project: unknown, body: any, ctx: FlowContext]>;
+    exportSystem: Flow<[project: unknown]>;
 }
 export interface McpDeps {
     store: Store;

package/dist/server/mcpHttp.js

@@ -12,16 +12,16 @@ export function unwrap(result) {
     return result.body;
 }
 // `edit` is one verb with two shapes: `rename` or `areaOrder` edits the
-// project, anything else edits the mock. Shared by both MCP transports' HTTP
+// project, anything else edits the design. Shared by both MCP transports' HTTP
 // side and `run`.
 export function editCall(flows, args, ctx, project) {
     if (args.rename === undefined && args.areaOrder === undefined) {
-        return flows.edit(args.mock, args, ctx);
+        return flows.edit(args.design, args, ctx);
     }
-    if (args.mock !== undefined) {
+    if (args.design !== undefined) {
         return Promise.resolve({
             status: 400,
-            body: { error: '"rename" and "areaOrder" edit the project; edit the mock without them' },
+            body: { error: '"rename" and "areaOrder" edit the project; edit the design without them' },
         });
     }
     if (!project) {
@@ -63,14 +63,17 @@ export function registerMcp(app, deps) {
             case "publish":
                 return unwrap(await flows.publish(args, ctx));
             case "ask":
-                return unwrap(await flows.ask(args.mock, args, ctx));
+                return unwrap(await flows.ask(args.design, args, ctx));
             case "read":
-                if (args.mock === undefined && args.tree === true) {
+                if (args.decisions === true) {
+                    return unwrap(await flows.decisions({ project: args.project }));
+                }
+                if (args.design === undefined && args.tree === true) {
                     return unwrap(await flows.tree({ project: args.project }));
                 }
-                if (args.mock === undefined)
+                if (args.design === undefined)
                     return unwrap(await flows.list({ project: args.project }));
-                return unwrap(await flows.get(args.mock, {
+                return unwrap(await flows.get(args.design, {
                     project: args.project,
                     body: args.body === true,
                     history: args.history === true,
@@ -78,11 +81,25 @@ export function registerMcp(app, deps) {
             case "feedback":
                 return unwrap(await flows.feedback({ session: args.session, project: args.project }, ctx));
             case "say":
-                return unwrap(await flows.say(args.mock, args, ctx));
+                return unwrap(await flows.say(args.design, args, ctx));
+            case "move":
+                return unwrap(await flows.move(args.design, args, ctx));
             case "export":
-                return unwrap(await flows.exportMock(args.mock, args, ctx));
+                if (args.design === undefined) {
+                    return unwrap(await flows.exportSystem(await projectOf(args)));
+                }
+                return unwrap(await flows.exportDesign(args.design, args, ctx));
             case "edit":
                 return unwrap(await editCall(flows, args, ctx, await namedProject(args)));
+            case "system": {
+                const writing = Object.keys(args).some((k) => !["session", "project", "agent"].includes(k));
+                if (!writing)
+                    return unwrap(await flows.system(await projectOf(args), args, ctx));
+                const project = await namedProject(args);
+                if (!project)
+                    throw new Error("system writes need a project: pass project, or call from a session that has one");
+                return unwrap(await flows.system(project, args, ctx));
+            }
             case "upload": {
                 if (typeof args.data !== "string" || args.data.length === 0) {
                     throw new Error("upload needs base64 `data`");
@@ -110,7 +127,7 @@ export function registerMcp(app, deps) {
                     return await deps.guide(await projectOf(args));
                 if (!isGuideTopic(args.topic))
                     throw new Error(unknownTopicMessage(String(args.topic)));
-                return await deps.guide("", args.topic);
+                return await deps.guide(args.topic === "system" ? await projectOf(args) : "", args.topic);
             }
             default:
                 throw new Error(`unknown tool: ${name}`);
@@ -119,7 +136,7 @@ export function registerMcp(app, deps) {
     app.post("/mcp", async (c) => {
         const rpc = (id, result) => c.json({ jsonrpc: "2.0", id, result });
         // `?mode=code` is the opt-in codemode catalog for clients without a
-        // harness of their own: one `run` tool instead of the mock tools.
+        // harness of their own: one `run` tool instead of the design tools.
         const code = c.req.query("mode") === "code";
         const rpcError = (id, code, message, status = 200) => c.json({ jsonrpc: "2.0", id, error: { code, message } }, status);
         let msg;