mockpit 1.2.0 → 2.0.0

package/bin/mockpit.js

@@ -9,7 +9,7 @@ import {
   writeFileSync,
   writeSync,
 } from "node:fs";
-import { tmpdir, userInfo } from "node:os";
+import { homedir, tmpdir, userInfo } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
@@ -29,23 +29,23 @@ const HEADERS = {
 const HELP = `mockpit — a live visual surface for terminal coding agents
 
 vocabulary: project › mock › state › variant › version. A project is a repo; a
-mock is the page or component on stage; a state is one moment of it ("Lab
+mock is a sketch, page or component, by slug; a state is one thing the user sees in it ("Lab
 open"); a variant is a parallel design of a state; a version is its history.
-Mark the parts you want feedback on with data-part="name" in the html.
+Declare the parts you want feedback on with data-part="name" in the html.
 
 the loop (never blocks on the user):
   1. mockpit init once per repo; read the brief (mockpit guide).
-  2. mockpit publish once per variant; mark parts with data-part.
-  3. A choice is several variants plus one ask that binds them: mockpit ask
+  2. mockpit publish once per variant; declare parts with data-part.
+  3. A choice is several variants plus one question that binds them: mockpit ask
      with options bound to variants. A variant decides everything it differs
      on; don't re-ask it. Visual options carry a variant or knob set. One
      render plus a control: --knobs.
   4. Tell the user in one line where to look, then end your turn. The question
-     itself lives in the mock (ask), never in chat. The user answers in the
+     itself lives in the mock, never in chat. The user answers in the
      browser at their own pace. Never poll.
   5. When the user says they answered (or a mockpit watch line wakes you), run
      mockpit feedback. Every write also returns feedback; read it.
-  6. mockpit publish the revision; mockpit export once a variant is accepted.
+  6. mockpit publish the revision; mockpit export once a variant is in use.
   In Claude Code, arm mockpit watch under Monitor after asking, then end the
   turn; elsewhere the user's next message is the wake-up.
 
@@ -56,32 +56,45 @@ verbs:
   mockpit publish --mock <slug> --html <file> [options]
                                           create or version one variant of one state
       --state <label>   state, in the user's words (omit for a single-state mock)
+      --situation <s>   another render of that state ("Couldn't save", "Loading")
       --variant <name>  variant label (default "default")
       --html <file|->   the html body (or a positional file)
       --surfaces <json|file>  instead: the full ordered surface list; {"id"}
                         alone keeps a surface, a missing id removes it
       --parts <name=file|->  instead: replace just that data-part's element in
                         the latest version (repeatable; name#key targets one instance)
+      --fills <part#fill=file|->  instead: replace or add one fill of a part in
+                        the latest version (repeatable)
       --title <t>       mock title
-      --kind <k>        component|page (default component)
+      --kind <k>        page|component, only for an app's screens (default sketch)
+      --area <name>     where in the product it belongs ("Shell"); Home groups by it
+      --source <path>   the code path that implements it
       --knobs <json|file>  knobs in tunekit usePane shape, keyed by path
       --from <N>        branch from version N
       --prompt <text>   what prompted this version
+      --note <text>     one line on what this variant is, shown beside it
+      --widths <list>   device widths to show it at, e.g. 390,1280
+      --flow <name> [--step <N>]  make this state step N of a flow (0 takes
+                        it out); with no html it only places the state
       --project <name>  project (default: git remote, else directory name)
       --kit <id>        opt the html surface into a kit (repeatable; see "mockpit kits")
+      --poster <file>   a still of the page (png, jpg); Studio and Home show it
+                        instead of running the page. Send one with every version
+                        that changes the page, or it goes
       --md/--mermaid/--diff/--terminal/--data/--code/--image <file|->
                         add a surface of that kind after the html (repeatable;
                         --data is a JSON tree)
   mockpit ask --mock <slug> "<question>" --option <label[=variant]> ...
                                           ask the user; bind options to variants
       --option <l[=v]>  an option (repeatable); "=variant" binds it to a variant,
-                        "=knob:path=value" sets one knob
+                        "=variant@3" to its version 3, "=knob:path=value" sets one knob
+      --recommend <l>   the option you would pick, by label; a quiet mark on it
       --scope <s>       mock|state|part (default mock)
-      --state <label>   the state a state-scoped ask is about
-      --part <name>     the part a part-scoped ask is about
+      --state <label>   the state a state-scoped question is about
+      --part <name>     the part a part-scoped question is about
       --multi           allow several answers
-      --id <id>         stable id; reusing one replaces that ask
-      --asks <json|file>  several asks at once, full shape
+      --id <id>         stable id; reusing one replaces that question
+      --asks <json|file>  several questions at once, full shape
   mockpit read [slug] [--body] [--history]
                                           no slug: every mock plus what the user
                                           is doing now; a slug: that mock
@@ -89,12 +102,20 @@ verbs:
                                           plus pending; returns at once
   mockpit say "<text>" --mock <slug> [--state s] [--variant v]
                                           a plain-text message in a mock's thread
+  mockpit edit --mock <slug> [--slug s] [--title t] [--kind k] [--area a] [--source p]
+                                          change a mock without a new version ("" clears)
+  mockpit edit --project <name> --rename <new>
+                                          rename a project
+  mockpit edit --project <name> --area-order "Shell,Food"
+                                          the order Home lists areas in
   mockpit export --mock <slug> [--state s] [--variant v] [--out <dir>]
-                                          write the accepted html + history per state
+                                          write the html in use + history per state
                                           to .mockpit/accepted/<mock>/<state>/
   mockpit upload <file> [--kind image|file]
                                           upload an asset, print its id and URL
   mockpit guide [--topic <id>]           the project-aware brief, or one reference topic
+  mockpit rules [--mine]                 send .mockpit/rules.md (or, with --mine, your
+                                          ~/.mockpit/rules.md) to the server for the brief
   mockpit run <file|->                   run a script against the mockpit API on the
                                           server (mockpit guide --topic scripts)
   mockpit watch [--session <id>]         stream user feedback, one line per Send
@@ -142,6 +163,15 @@ const COMMAND_HELP = {
   (gitignored). --kit makes a bundled or project kit the default for every html
   surface. --kit-url defines the project's own kit (id from --kit, else
   "project") and makes it the default; the doc is the cheat sheet the brief prints.`,
+  rules: `mockpit rules [--project <name>]
+mockpit rules --mine
+  Guidance on top of the core brief, highest first: the project's
+  .mockpit/rules.md (committed with the repo), your ~/.mockpit/rules.md, then
+  the packs either names (\`packs: [design-craft]\` in its frontmatter). A file
+  has "## Rules" (always followed) and "## Suggestions" (aimed for).
+  This sends the file as it is on disk; a missing file clears the stored copy.
+  init sends the project's too. A local server reads yours live, so --mine is
+  for a deployed one.`,
   kit: `mockpit kit add <id> --url <https url> --doc <file.md|text> [--script <url>]
 mockpit kit remove <id>
   A project kit is a stylesheet (and optional script) on the CDN allowlist plus a
@@ -156,42 +186,84 @@ mockpit icons remove <set> [<set>...]
   publish: `mockpit publish --mock <slug> --html <file> [options]
 mockpit publish --mock <slug> --surfaces <json|file> [options]
 mockpit publish --mock <slug> --parts <name=file|-> ... [options]
+mockpit publish --mock <slug> --fills <part#fill=file|-> ... [options]
   Creates the mock, state or variant, or the next version of an existing one.
   --state <label>    state in the user's words (omit for a single-state mock)
+  --situation <s>    another render of that state ("Couldn't save", "Loading"),
+                     after the state itself is published
   --variant <name>   variant label (default "default")
   --surfaces <json|file>  the full ordered list: {"id"} alone keeps a surface,
                      a missing id removes it, order is the list order
   --parts <name=file|->   replace only the element carrying data-part="name"
                      (name#key for one instance) in the latest version; repeatable
+  --fills <part#fill=file|->  replace the element carrying data-part="part"
+                     data-fill="fill" in the latest version, or add it after
+                     that part's other fills; the marks are added if missing
   --title <t>        mock title
-  --kind <k>         component|page (default component)
+  --kind <k>         page|component|sketch: page for a screen of the product,
+                     component for a piece pages embed (embedding makes one);
+                     omit for sketches, diagrams, reviews (default sketch)
+  --area <name>      where in the product it belongs, in the project's words
+                     ("Shell", "Food"); Home groups each tab by it. "" clears
+  --source <path>    the code path that implements it (apps/web/src/shell). "" clears
   --knobs <json|file>  knobs in tunekit usePane shape
   --from <N>         branch from version N
+  --fork <v[@N]>     start this new variant from sibling v (its version N, else
+                     its latest); alone it copies v, with --parts/--fills it
+                     edits the copy
   --prompt <text>    what prompted this version
+  --note <text>      one line on what this variant is, shown beside it (never
+                     inside the design)
+  --widths <list>    device widths the mock is judged at, side by side, e.g.
+                     390,1280 (the ones the user ships to)
+  --flow <name>      a flow this state is a step of: the states the user moves
+                     between, in order, across mocks; without html it only
+                     places the existing state
+  --step <N>         its 1-based place in the flow (moves it if it is there);
+                     0 takes it out; omitted, it joins at the end
   --project <name>   project (default: git remote, else directory name)
+  --poster <file>    a still of the page (png, jpg) that Studio and Home show
+                     instead of running it; with --parts or --fills it is the
+                     still of the spliced page. A version that changes the page
+                     without one drops the old still
   --md/--mermaid/--diff/--terminal/--data/--code/--image <file>  more surfaces
   --json / --quiet
   Prints the parts found per state, parts that vanished or were renamed,
-  nudges, a ready-to-run "mockpit ask" when variants have no ask, and feedback.`,
+  nudges, a ready-to-run "mockpit ask" when variants have no question, and feedback.`,
   ask: `mockpit ask --mock <slug> "<question>" --option <label[=variant]> ... [--scope mock|state|part]
-  [--state s] [--part p] [--multi] [--id id]
+  [--state s] [--part p] [--multi] [--id id] [--after <ask id>] [--recommend <label>]
   mockpit ask --mock <slug> --asks <json|file>
-  Ask the user. A choice is several variants plus one ask that binds them.
+  Ask the user. A choice is several variants plus one question that binds them.
   Then tell the user where to look and end your turn.`,
-  read: `mockpit read [slug] [--project <name>] [--body] [--history]
-  No slug: one line per mock (states, variants, open asks) plus pending, what
-  the user is doing now. A slug: the mock's states, variants, asks with
-  answers, parts, knobs and last tuned values, plus its pending, as JSON.
-  --body includes surfaces, --history version rows. Never consumes feedback.`,
+  read: `mockpit read [slug] [--project <name>] [--body] [--history] [--tree]
+  No slug: one line per mock (states, variants, open questions), one per flow, plus pending, what
+  the user is doing now. A slug: the mock's states, variants, questions with
+  answers, parts, knobs and settled values, plus its pending, as JSON.
+  --body includes surfaces, --history version rows. --tree (no slug): the
+  project as a tree, each mock's variants with status and forkedFrom, and the
+  mocks it embeds and is embedded in, as JSON. Never consumes feedback.`,
   feedback: `mockpit feedback [--project <name>] [--session <id>]
   Returns at once with {feedback, pending} as JSON: one batch per mock the user
-  sent since you last heard ({mock, reply: {asks, mix, tuned, comments},
-  comments, accepted, archived}), delivered once across feedback, watch and
+  sent since you last heard ({mock, reply: {asks, borrowed, tuned, comments,
+  verdict}, messages, inUse, archived}, or {mock, closed: true, dismissed} when the
+  user closed it unanswered), delivered once across feedback, watch and
   every write; and pending ({mock, viewerOpen, draft}) so you can tell the
   user "take your time" or "2 of 3 answered". Run it when the user says they
   answered.`,
   say: `mockpit say "<text>" --mock <slug> [--state s] [--variant v]
   A plain-text message in the mock's thread, as your session's agent.`,
+  edit: `mockpit edit --mock <slug> [--slug <new>] [--title <t>] [--kind page|component|sketch]
+  [--area <name>|""] [--source <path>|""] [--project <name>]
+mockpit edit --project <name> --rename <new name>
+mockpit edit --project <name> --area-order "Shell,Food,Chat"
+  Change a mock without publishing a new version; "" clears area or source. A new
+  slug rewrites every embed, data-goto and flow step that names the old one, in
+  every version. A mock still embedded somewhere stays a component, not a sketch.
+  --rename moves the project's mocks, sessions, flows and design settings to the
+  new name (refused if that project has mocks); pass --project <new> or set
+  MOCKPIT_PROJECT afterwards if the repo still resolves to the old name.
+  --area-order lists the project's areas in the order Home shows them; areas it
+  leaves out follow alphabetically, "" goes back to alphabetical.`,
   run: `mockpit run <file|-> [--session <id>] [--project <name>] [--json]
   Run a script (the body of an async function, plain JavaScript) in the server's
   sandbox against the mockpit API; see mockpit guide --topic scripts. Prints each
@@ -203,11 +275,12 @@ mockpit publish --mock <slug> --parts <name=file|-> ... [options]
   Claude Code, arm it under Monitor after asking, then end the turn).
   Delivery is shared with feedback and every write: each Send arrives once.`,
   export: `mockpit export --mock <slug> [--state s] [--variant v] [--out <dir>]
-  Write index.html + history.json per state to .mockpit/accepted/<mock>/<state>/.`,
+  Write index.html + history.json per state to .mockpit/accepted/<mock>/<state>/;
+  with fills, index.html is the chosen state, plus all-fills.html and decisions.json.`,
   upload: `mockpit upload <file> [--kind image|file] [--session <id>]
   Upload an asset; prints its id and URL. Use the id as an image surface's assetId.`,
   guide: `mockpit guide [--topic <id>] [--project <name>]
-  No flag prints the brief: the loop, parts, asks and knobs, feedback, and
+  No flag prints the brief: the loop, parts, questions and knobs, feedback, and
   this project's palette, kit and icons. --topic prints one reference topic
   (knobs, asks, surfaces, html, feedback, http, scripts).`,
 };
@@ -396,6 +469,19 @@ async function resolveSession(flags, { create = false } = {}) {
   return session.id;
 }
 
+// The harness's conversation id names exactly one session, where the cwd can
+// match several agents working in one repo; the watcher would then take a
+// sibling's replies. Never creates one: most conversations never use mockpit.
+async function resolveSessionByKey(key) {
+  try {
+    const res = await fetch(`${BASE}/api/sessions${query({ key })}`, { headers: HEADERS });
+    if (!res.ok) return null;
+    return (await res.json())[0]?.id ?? null;
+  } catch {
+    return null;
+  }
+}
+
 // A monitor process (e.g. the Claude Code plugin) may not share the local
 // state file written by the agent's CLI calls — different spawn tree, so
 // `agentPid()` can hash to a different key. Fall back to asking the server for
@@ -810,6 +896,7 @@ function printPublished(result, flags) {
     console.log(`parts${state ? ` (${state})` : ""}: ${parts.map((p) => p.name).join(", ")}`);
   }
   if (result.applied?.length) console.log(`applied: ${result.applied.join(", ")}`);
+  if (result.flow) console.log(flowLine(result.flow));
   const changes = result.partChanges;
   if (changes?.renamed?.length) {
     console.log(`renamed: ${changes.renamed.map((r) => `${r.from} → ${r.to}`).join(", ")}`);
@@ -822,6 +909,11 @@ function printPublished(result, flags) {
   printFeedback(result.feedback);
 }
 
+function flowLine(flow) {
+  const steps = flow.steps.map((x) => (x.state === null ? x.mock : `${x.mock}/${x.state}`));
+  return `flow ${flow.name}: ${steps.length ? steps.join(" → ") : "empty, removed"}`;
+}
+
 // Only speak when there IS feedback: an empty line per write is pure token
 // cost, and the cursor guarantees anything pending arrives on some write.
 function printFeedback(feedback) {
@@ -847,14 +939,24 @@ function parsePublishFlags() {
     allowPositionals: true,
     options: {
       ...MOCK_FLAGS,
+      situation: { type: "string" },
       title: { type: "string" },
       kind: { type: "string" },
+      area: { type: "string" },
+      source: { type: "string" },
       html: { type: "string" },
+      poster: { type: "string" },
       surfaces: { type: "string" },
       parts: { type: "string", multiple: true },
+      fills: { type: "string", multiple: true },
       knobs: { type: "string" },
       from: { type: "string" },
+      fork: { type: "string" },
       prompt: { type: "string" },
+      note: { type: "string" },
+      widths: { type: "string" },
+      flow: { type: "string" },
+      step: { type: "string" },
       kit: { type: "string", multiple: true },
       layout: { type: "string" },
       md: { type: "string", multiple: true },
@@ -873,18 +975,27 @@ function parsePublishFlags() {
 
 // `--parts name=file` (repeatable; `name#key` targets one instance): the new
 // outer html of one part, spliced server-side into the latest version.
-function readPartFlags(values, slug) {
+// `--fills part#fill=file` is the same for one fill of a part.
+function readPartFlags(values, slug, flag = "parts") {
   if (!values?.length) return undefined;
-  const example = `mockpit publish --mock ${slug} --parts body=body.html`;
+  const example =
+    flag === "parts"
+      ? `mockpit publish --mock ${slug} --parts body=body.html`
+      : `mockpit publish --mock ${slug} --fills entry#skeleton=skeleton.html`;
   const parts = {};
   let stdin = false;
   for (const raw of values) {
     const at = raw.indexOf("=");
-    if (at <= 0 || at === raw.length - 1) die(`--parts needs name=file (got "${raw}")`, example);
+    if (at <= 0 || at === raw.length - 1) {
+      die(
+        `--${flag} needs ${flag === "parts" ? "name" : "part#fill"}=file (got "${raw}")`,
+        example,
+      );
+    }
     const name = raw.slice(0, at);
     const file = raw.slice(at + 1);
     if (file === "-") {
-      if (stdin) die("only one --parts can read stdin", example);
+      if (stdin) die(`only one --${flag} can read stdin`, example);
       stdin = true;
     } else if (!existsSync(file)) die(`cannot read ${file}`, `ls ${file}`);
     parts[name] = readContent(file);
@@ -900,6 +1011,13 @@ async function publishMock() {
   if (from !== undefined && !Number.isInteger(from)) {
     die(`--from must be a version number (got "${flags.from}")`, `mockpit read ${slug} --history`);
   }
+  const step = flags.step === undefined ? undefined : Number(flags.step);
+  if (step !== undefined && !(Number.isInteger(step) && step >= 0)) {
+    die(
+      `--step must be a place in the flow, 1 or more, or 0 (got "${flags.step}")`,
+      `mockpit read`,
+    );
+  }
   const file = flags.html ?? positionals[0];
   const composed =
     file !== undefined || tokens.some((t) => t.kind === "option" && SURFACE_FLAGS.has(t.name));
@@ -907,16 +1025,21 @@ async function publishMock() {
     composed && "--html",
     flags.surfaces !== undefined && "--surfaces",
     flags.parts?.length && "--parts",
+    flags.fills?.length && "--fills",
   ].filter(Boolean);
   if (given.length > 1) {
     die(
-      `pass one of --html, --surfaces or --parts, not ${given.join(" and ")}`,
+      `pass one of --html, --surfaces, --parts or --fills, not ${given.join(" and ")}`,
       `mockpit publish --help`,
     );
   }
   // Checked before the session exists so a typo'd path leaves nothing behind on the server.
   if (file && file !== "-" && !existsSync(file)) die(`cannot read ${file}`, `ls ${file}`);
+  if (flags.poster !== undefined && !existsSync(flags.poster)) {
+    die(`cannot read ${flags.poster}`, `ls ${flags.poster}`);
+  }
   const parts = readPartFlags(flags.parts, slug);
+  const fills = readPartFlags(flags.fills, slug, "fills");
   let surfaces =
     flags.surfaces === undefined ? undefined : readJsonFlag("surfaces", flags.surfaces);
   if (surfaces !== undefined && !Array.isArray(surfaces)) {
@@ -936,21 +1059,38 @@ async function publishMock() {
     }
     surfaces.push(...(await surfacesFromFlags(flags, tokens, { session, layout: flags.layout })));
   }
-  if (!surfaces && !parts)
+  if (!surfaces && !parts && !fills && !flags.fork && flags.flow === undefined)
     die(`no html for ${slug}`, `mockpit publish --mock ${slug} --html <file>`);
+  const poster =
+    flags.poster === undefined ? undefined : (await uploadFile(flags.poster, { session })).id;
   const body = {
     session,
     project,
     mock: slug,
     state: flags.state,
+    situation: flags.situation,
     variant: flags.variant,
     title: flags.title,
     kind: flags.kind,
+    area: flags.area,
+    source: flags.source,
     ...(flags.knobs !== undefined && { knobs: readJsonFlag("knobs", flags.knobs) }),
     ...(from !== undefined && { from }),
+    ...(flags.fork !== undefined && { fork: flags.fork }),
     prompt: flags.prompt,
+    note: flags.note,
+    ...(flags.widths !== undefined && {
+      widths: flags.widths
+        .split(",")
+        .filter((w) => w.trim())
+        .map((w) => Number(w)),
+    }),
+    ...(flags.flow !== undefined && { flow: flags.flow }),
+    ...(step !== undefined && { step }),
     ...(surfaces && { surfaces }),
     ...(parts && { parts }),
+    ...(fills && { fills }),
+    ...(poster && { poster }),
   };
   const result = await api(
     "/api/mocks",
@@ -962,6 +1102,7 @@ async function publishMock() {
 }
 
 // "Quiet" is an unbound option; "Quiet=quiet" binds it to the quiet variant;
+// "Before=quiet@2" to its version 2 ("=@2" names the state's only variant);
 // "Above=knob:trim.position=top" sets one knob. The value is JSON when it
 // parses (17, true), else a string, so slider and toggle values keep their type.
 function parseOption(raw) {
@@ -980,7 +1121,11 @@ function parseOption(raw) {
   }
   const at = raw.lastIndexOf("=");
   if (at <= 0) return { label: raw };
-  return { label: raw.slice(0, at), variant: raw.slice(at + 1) };
+  const label = raw.slice(0, at);
+  const bound = raw.slice(at + 1);
+  const pin = /^(.*)@(\d+)$/.exec(bound);
+  if (!pin) return { label, variant: bound };
+  return { label, ...(pin[1] ? { variant: pin[1] } : {}), version: Number(pin[2]) };
 }
 
 // One feedback batch, one line — for a background monitor's notifications.
@@ -1005,6 +1150,20 @@ function watchLines(batch) {
   const lines = [];
   const name = batch.mock ?? "a mock";
   if (batch.handoff) lines.push(`mockpit handoff on ${name}: ${batch.handoff}`);
+  if (batch.closed) {
+    const n = batch.dismissed?.length ?? 0;
+    lines.push(
+      `mockpit closed ${name}: ${n ? `${n} question${n === 1 ? "" : "s"} dismissed unanswered (${batch.dismissed.map((d) => d.text || d.ask).join("; ")}); don't ask again` : "closed by the user"}`,
+    );
+  }
+  if (batch.edited) {
+    const e = batch.edited;
+    const bits = [
+      e.kind ? `now a ${e.kind}` : "",
+      e.area !== undefined ? (e.area ? `area ${e.area}` : "no area") : "",
+    ].filter(Boolean);
+    lines.push(`mockpit edited ${name}: the user moved it (${bits.join(", ")})`);
+  }
   if (batch.reply) {
     const r = batch.reply;
     const bits = [
@@ -1017,21 +1176,30 @@ function watchLines(batch) {
             .join("; ")
         : "",
       Object.keys(r.tuned ?? {}).length ? `${Object.keys(r.tuned).length} tuned` : "",
-      Object.keys(r.mix ?? {}).length
-        ? `mix ${Object.entries(r.mix)
+      Object.keys(r.borrowed ?? {}).length
+        ? `borrowed ${Object.entries(r.borrowed)
             .map(([p, v]) => `${p}←${v}`)
             .join(", ")}`
         : "",
-      r.comments?.length ? `${r.comments.length} comment${r.comments.length === 1 ? "" : "s"}` : "",
+      ...(r.comments ?? [])
+        .filter((c) => c.borrow)
+        .map(
+          (c) =>
+            `borrow ${c.borrow.part ? `${c.borrow.part} ` : ""}from ${c.borrow.from} into ${c.variant}@${c.version}${c.text ? ` (“${c.text}”)` : ""}`,
+        ),
+      (() => {
+        const n = (r.comments ?? []).filter((c) => !c.borrow).length;
+        return n ? `${n} comment${n === 1 ? "" : "s"}` : "";
+      })(),
       r.reactions?.length ? r.reactions.join(", ") : "",
-      r.decision ? r.decision.kind : "",
+      r.verdict ? `${r.verdict.kind} ${r.verdict.variant}` : "",
       r.text ?? "",
     ].filter(Boolean);
     lines.push(`mockpit reply on ${name}: ${bits.join(" · ").replace(/\s+/g, " ")}`);
   }
-  for (const c of batch.comments ?? []) {
+  for (const c of batch.messages ?? []) {
     lines.push(
-      `mockpit comment on ${name}: “${String(c.text ?? "")
+      `mockpit message on ${name}: “${String(c.text ?? "")
         .replace(/\s+/g, " ")
         .trim()}”`,
     );
@@ -1054,8 +1222,13 @@ async function apiSoft(path) {
   return res.json().catch(() => null);
 }
 
-// Keep the scratch directory out of the repo. Returns true when .gitignore was
-// touched, so init can report it.
+// Keep the scratch directory out of the repo, all but the project's rules
+// file, which is meant to be committed. Git can't re-include a file under an
+// ignored directory, so the ignore has to name the directory's contents, and
+// the `.mockpit/` line older versions wrote is upgraded in place. Returns true
+// when .gitignore was touched, so init can report it.
+const MOCKPIT_IGNORE = ".mockpit/*\n!.mockpit/rules.md";
+
 function ignoreMockpitDir() {
   const file = join(process.cwd(), ".gitignore");
   let current = "";
@@ -1064,14 +1237,56 @@ function ignoreMockpitDir() {
   } catch {
     // no .gitignore yet — create one
   }
-  if (/^\.mockpit\/?$/m.test(current)) return false;
+  if (/^\.mockpit\/\*$/m.test(current) && /^!\.mockpit\/rules\.md$/m.test(current)) return false;
+  if (/^\.mockpit\/?$/m.test(current)) {
+    writeFileSync(file, current.replace(/^\.mockpit\/?$/m, MOCKPIT_IGNORE));
+    return true;
+  }
+  const lines = /^\.mockpit\/\*$/m.test(current) ? "!.mockpit/rules.md" : MOCKPIT_IGNORE;
   writeFileSync(
     file,
-    current && !current.endsWith("\n") ? `${current}\n.mockpit/\n` : `${current}.mockpit/\n`,
+    current && !current.endsWith("\n") ? `${current}\n${lines}\n` : `${current}${lines}\n`,
   );
   return true;
 }
 
+function repoRoot() {
+  try {
+    const top = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (top) return top;
+  } catch {}
+  return process.cwd();
+}
+
+// Where `mockpit serve` reads the user's own rules: next to its database.
+const myRulesFile = () =>
+  join(dirname(process.env.MOCKPIT_DB ?? join(homedir(), ".mockpit", "mockpit.db")), "rules.md");
+
+// Sends a rules file as it is on disk: a missing file clears the stored copy,
+// so deleting the file and re-running is how rules are switched off.
+async function sendRules(file, path) {
+  const text = existsSync(file) ? readFileSync(file, "utf8") : "";
+  const result = await api(
+    path,
+    { method: "PUT", body: JSON.stringify({ text }) },
+    { report: "die", fix: "mockpit rules --help" },
+  );
+  return { ...result, missing: !text };
+}
+
+function rulesSummary(r) {
+  if (r.cleared) return "none (cleared)";
+  const bits = [
+    r.packs?.length ? `packs ${r.packs.join(", ")}` : null,
+    r.rules ? "own rules" : null,
+  ].filter(Boolean);
+  const unknown = r.unknown?.length ? ` · unknown pack ${r.unknown.join(", ")}` : "";
+  return `${bits.join(" · ") || "empty"}${unknown}`;
+}
+
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
 // Semver greater-than for plain x.y.z (mirrors server/app.ts versionGt).
@@ -1318,7 +1533,11 @@ const commands = {
     mkdirSync(dirname(starter), { recursive: true });
     writeFileSync(starter, renderStarter({ ...design, kit }, iconSets));
     say("wrote:", ".mockpit/starter.html");
-    if (ignoreMockpitDir()) say("wrote:", ".gitignore (+ .mockpit/)");
+    if (ignoreMockpitDir()) say("wrote:", ".gitignore (+ .mockpit/, keeping .mockpit/rules.md)");
+    const rulesFile = join(repoRoot(), ".mockpit", "rules.md");
+    if (existsSync(rulesFile)) {
+      say("rules:", rulesSummary(await sendRules(rulesFile, `${projectPath(project)}/rules`)));
+    }
     say("next:", "mockpit guide");
     if (flags.json) out({ project, design: stored, starter });
   },
@@ -1335,15 +1554,20 @@ const commands = {
         project: { type: "string" },
         session: { type: "string" },
         option: { type: "string", multiple: true },
+        recommend: { type: "string" },
         scope: { type: "string" },
         state: { type: "string" },
         part: { type: "string" },
         multi: { type: "boolean" },
         id: { type: "string" },
+        after: { type: "string" },
         asks: { type: "string" },
       },
     });
-    const slug = requireMock(flags, 'mockpit ask --mock writer "Which look?" --option Quiet=quiet');
+    const slug = requireMock(
+      flags,
+      'mockpit ask --mock writer "Quiet or dark?" --option Quiet=quiet',
+    );
     let asks;
     if (flags.asks !== undefined) {
       if (positionals.length > 0) {
@@ -1359,7 +1583,7 @@ const commands = {
       if (!text)
         die(
           "ask needs a question",
-          `mockpit ask --mock ${slug} "Which look?" --option Quiet=quiet`,
+          `mockpit ask --mock ${slug} "Quiet or dark?" --option Quiet=quiet`,
         );
       const options = (flags.option ?? []).map(parseOption);
       if (options.length === 0) {
@@ -1368,6 +1592,17 @@ const commands = {
           `mockpit ask --mock ${slug} "${text}" --option Quiet=quiet --option Dark=dark`,
         );
       }
+      if (flags.recommend !== undefined) {
+        const pick = options.find(
+          (o) => o.label.toLowerCase() === flags.recommend.trim().toLowerCase(),
+        );
+        if (!pick)
+          die(
+            `--recommend "${flags.recommend}" names no option`,
+            `mockpit ask --mock ${slug} "${text}" --option Quiet=quiet --option Dark=dark --recommend Quiet`,
+          );
+        pick.recommended = true;
+      }
       asks = [
         {
           text,
@@ -1377,6 +1612,7 @@ const commands = {
           ...(flags.state && { state: flags.state }),
           ...(flags.part && { part: flags.part }),
           ...(flags.multi && { multi: true }),
+          ...(flags.after && { after: flags.after }),
         },
       ];
     }
@@ -1414,10 +1650,20 @@ const commands = {
         project: { type: "string" },
         body: { type: "boolean" },
         history: { type: "boolean" },
+        tree: { type: "boolean" },
       },
     });
     const project = resolveProject(flags).name;
     if (positionals.length > 1) die("read takes one mock slug", "mockpit read writer");
+    if (flags.tree) {
+      return out(
+        await api(
+          `/api/projects/${encodeURIComponent(project)}/tree`,
+          {},
+          { report: "die", fix: `mockpit read --project ${project}` },
+        ),
+      );
+    }
     if (positionals.length === 1) {
       const slug = slugify(positionals[0]);
       return out(
@@ -1439,15 +1685,16 @@ const commands = {
     console.log(
       `${project} · ${mocks.length} mock${mocks.length === 1 ? "" : "s"}` +
         (list.open
-          ? ` · ${list.open} open ask${list.open === 1 ? "" : "s"}`
+          ? ` · ${list.open} open question${list.open === 1 ? "" : "s"}`
           : " · nothing waiting on the user"),
     );
     for (const m of mocks) {
       const states = m.states.length ? m.states.join(" / ") : "single state";
       console.log(
-        `  ${m.slug} · ${m.kind} · ${states} · ${m.variants} variant${m.variants === 1 ? "" : "s"}${m.open ? ` · ${m.open} open` : ""}`,
+        `  ${m.slug} · ${m.kind}${m.area ? ` · ${m.area}` : ""} · ${states} · ${m.variants} variant${m.variants === 1 ? "" : "s"}${m.closedAt ? " · closed" : m.open ? ` · ${m.open} open` : ""}`,
       );
     }
+    for (const flow of list.flows ?? []) console.log(`  ${flowLine(flow)}`);
     for (const line of pendingLines(list.pending)) console.log(line);
   },
   async export() {
@@ -1473,6 +1720,15 @@ const commands = {
       const dir = join(root, entry.state === null ? "default" : slugify(entry.state));
       mkdirSync(dir, { recursive: true });
       writeFileSync(join(dir, "index.html"), entry.html ?? "");
+      // The state with every fill, when index.html is the composed choice.
+      if (entry.allFills) writeFileSync(join(dir, "all-fills.html"), entry.allFills);
+      const decided = data.decisions?.states?.[entry.state ?? ""];
+      if (decided) {
+        writeFileSync(
+          join(dir, "decisions.json"),
+          JSON.stringify({ ...decided, knobs: data.decisions.knobs }, null, 2) + "\n",
+        );
+      }
       writeFileSync(
         join(dir, "history.json"),
         JSON.stringify(
@@ -1560,9 +1816,13 @@ const commands = {
     // feedback is delivered exactly once across watch, feedback, and piggyback.
     let firstAfter = flags.after;
     for (;;) {
-      const session = (await resolveSession(flags)) ?? (await resolveSessionByCwd());
+      const key = harnessKey();
+      const session =
+        (await resolveSession(flags)) ??
+        (key ? await resolveSessionByKey(key) : await resolveSessionByCwd());
       if (!session) {
-        await sleep(2000);
+        // A conversation that hasn't used mockpit yet may never; ask rarely.
+        await sleep(key ? 10_000 : 2000);
         continue;
       }
       let result;
@@ -1612,6 +1872,102 @@ const commands = {
     console.log(`said on ${slug}`);
     printFeedback(result.feedback);
   },
+  async edit() {
+    const { values: flags } = parse({
+      options: {
+        mock: { type: "string" },
+        project: { type: "string" },
+        session: { type: "string" },
+        slug: { type: "string" },
+        title: { type: "string" },
+        kind: { type: "string" },
+        area: { type: "string" },
+        source: { type: "string" },
+        rename: { type: "string" },
+        "area-order": { type: "string" },
+      },
+    });
+    const project = resolveProject(flags).name;
+    const session = (await resolveSession(flags)) ?? undefined;
+    const areaOrder = flags["area-order"];
+    if (flags.rename !== undefined || areaOrder !== undefined) {
+      if (flags.mock) {
+        die(
+          "--rename and --area-order edit the project; edit the mock without them",
+          "mockpit edit --help",
+        );
+      }
+      if (flags.rename !== undefined && !flags.rename.trim()) {
+        die("--rename needs the new name", `mockpit edit --rename <name>`);
+      }
+      const result = await api(
+        projectPath(project),
+        {
+          method: "PATCH",
+          body: JSON.stringify({
+            name: flags.rename,
+            ...(areaOrder === undefined ? {} : { areaOrder: areaOrder.split(",") }),
+            session,
+          }),
+        },
+        { report: "die", fix: "mockpit read" },
+      );
+      if (flags.json) return out(result);
+      if (flags.quiet) return;
+      if (result.areaOrder) {
+        console.log(
+          `area order ${result.areaOrder.length ? result.areaOrder.join(", ") : "alphabetical"} · ${result.url}`,
+        );
+      }
+      for (const nudge of result.nudges ?? []) console.log(`nudge: ${nudge}`);
+      if (!result.renamed) return printFeedback(result.feedback);
+      console.log(
+        `renamed project ${result.renamed.from} → ${result.renamed.to} · ${result.mocks} mock${result.mocks === 1 ? "" : "s"} · ${result.url}`,
+      );
+      if (!flags.project && !process.env.MOCKPIT_PROJECT) {
+        console.log(
+          `note: this repo still resolves to "${project}"; pass --project ${shq(result.project)} or set MOCKPIT_PROJECT`,
+        );
+      }
+      printFeedback(result.feedback);
+      return;
+    }
+    const slug = requireMock(flags, "mockpit edit --mock writer --area Shell");
+    const fields = ["slug", "title", "kind", "area", "source"].filter(
+      (k) => flags[k] !== undefined,
+    );
+    if (!fields.length) {
+      die("edit needs --slug, --title, --kind, --area or --source", "mockpit edit --help");
+    }
+    const result = await api(
+      mockPath(slug),
+      {
+        method: "PATCH",
+        body: JSON.stringify({
+          project,
+          session,
+          ...Object.fromEntries(fields.map((k) => [k, flags[k]])),
+        }),
+      },
+      { report: "die", fix: `mockpit read ${slug}` },
+    );
+    if (flags.json) return out(result);
+    if (flags.quiet) return;
+    const m = result.mock;
+    console.log(
+      [
+        result.renamed ? `${result.renamed.from} → ${m.slug}` : m.slug,
+        m.kind,
+        m.area && `area ${m.area}`,
+        m.source && `source ${m.source}`,
+        result.url,
+      ]
+        .filter(Boolean)
+        .join(" · "),
+    );
+    for (const nudge of result.nudges ?? []) console.log(`nudge: ${nudge}`);
+    printFeedback(result.feedback);
+  },
   async demo() {
     parse();
     const { DEMO } = await import("./demoData.js");
@@ -1629,6 +1985,7 @@ const commands = {
             session: session.id,
             project: DEMO.project,
             mock: DEMO.slug,
+            kind: "page",
             title: DEMO.title,
             state: state.label,
             variant: variant.name,
@@ -1760,6 +2117,24 @@ const commands = {
     return printBrief(flags);
   },
 
+  // A rules file is the user's or the project's own guidance on top of the
+  // core brief; the brief prints it, so this only has to put it on the server.
+  async rules() {
+    const { values: flags } = parse({
+      options: { mine: { type: "boolean" }, project: { type: "string" } },
+    });
+    const mine = !!flags.mine;
+    const file = mine ? myRulesFile() : join(repoRoot(), ".mockpit", "rules.md");
+    const project = mine ? null : resolveProject(flags).name;
+    const result = await sendRules(file, mine ? "/api/rules" : `${projectPath(project)}/rules`);
+    if (flags.json) return out(result);
+    if (flags.quiet) return;
+    const where = mine ? "your rules" : `project ${project}`;
+    const from = result.missing ? `no ${file}` : file;
+    console.log(`${where}: ${rulesSummary(result)} (from ${from})`);
+    if (!result.missing) console.log("next:", "mockpit guide");
+  },
+
   async setup() {
     parse();
     console.log(await fetchTextWithFallback("/setup", join(ROOT, "guide", "AGENT_SETUP.md")));