plotcoder-board 0.1.18 → 0.1.20

package/README.md

@@ -51,10 +51,10 @@ An agent should call the tools, never fake mouse drags. The skill in `.cursor/sk
 A **blind run** is a fresh agent given the on-ramp and a treatment and nothing
 else, asked to build a wall and to keep a log of everything that made the job
 harder than it should have been. The friction log is the product; the wall is
-just what produces it. Fourteen rounds have been run, the first three through a
+just what produces it. Fifteen rounds have been run, the first three through a
 repo checkout and the rest through the account door; every finding from the
-first thirteen is fixed or decided, and round fourteen's forty-nine were
-worked through the day after it ran. [`blind-runs/`](blind-runs/) holds the rules that keep a round honest,
+first fourteen is fixed or decided, and thirty-four of round fifteen's
+forty-five were fixed the same evening, while it ran. [`blind-runs/`](blind-runs/) holds the rules that keep a round honest,
 the table of rounds, and the next round's prompt with the test account filled in.
 
 A round works a **test account** — a throwaway marked on its writer row, and the
@@ -99,4 +99,4 @@ next round into a test of `claim_account` instead of the door it meant to test.
 
 ## Status
 
-Version 0.1.15. A project of boards; sign in with your email and a password from the PlotCoder mark and your projects follow you to every device, share one with another writer by email and write it together live, or stay signed out and work on this device as before. Pages sit beside the wall: a scene's text lives on its card, measures it, paginates to the industry's rules, prints, goes out and comes in as Fountain or Final Draft, and goes out as Markdown or plain text for a collaborator in Google Docs. It installs as a progressive web app and opens offline; plotcoder.com serves over HTTPS. The wall, beats, card length, groups, arrows, pan and zoom, save and open, and the agent surface are in use.
+Version 0.1.20. A project of boards; sign in with your email and a password from the PlotCoder mark and your projects follow you to every device, share one with another writer by email and write it together live, or stay signed out and work on this device as before. Pages sit beside the wall: a scene's text lives on its card, measures it, paginates to the industry's rules, prints, goes out and comes in as Fountain or Final Draft, and goes out as Markdown or plain text for a collaborator in Google Docs. It installs as a progressive web app and opens offline; plotcoder.com serves over HTTPS. The wall, beats, card length, groups, arrows, pan and zoom, save and open, and the agent surface are in use.

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "plotcoder-board",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "type": "module",
   "scripts": {
     "dev": "vite",
     "prebuild": "node scripts/write-agents-text.mjs",
+    "version": "node scripts/write-readme-version.mjs && git add README.md",
     "build": "tsc -b && vite build",
     "preview": "vite preview",
     "test": "vitest run",

package/scripts/plotcoder-mcp-server.mjs

@@ -33,6 +33,7 @@ import {
   NOTE_WIDTH,
   DEFAULT_TARGET_EIGHTHS,
   normalizeState,
+  newId,
   noteEighths,
   NOTE_COLORS,
   NOTE_RANKS,
@@ -564,7 +565,19 @@ async function throughAccount(read) {
   throw new DoorReply(accountRefusal ?? "The account door is shut.");
 }
 
+/** The project as last read, so any reading of the open board can know who is cast on another board (R51) without a second read. */
+let lastHeld = null;
 async function readProject() {
+  const held = await readProjectUncached();
+  lastHeld = held;
+  return held;
+}
+/** People on a card of another board of the project: the ids readWall must not ask about (round fifteen, entries 18 and 21). */
+function elsewhereIds(boardId) {
+  if (!lastHeld?.project) return [];
+  return Object.keys(castElsewhere(lastHeld.project, lastHeld.boards, boardId ?? lastHeld.project.activeBoardId));
+}
+async function readProjectUncached() {
   const viaAccount = await throughAccount(accountReadProject);
   if (viaAccount) return viaAccount;
   const base = await findBridge();
@@ -738,8 +751,13 @@ async function writeBoardRaw(next, rev, base, boardId = null) {
       log("bridge write failed, falling back to file:", error);
     }
   }
-  writeFileBoard(next, rev + 1, boardId);
-  syncProjectFileBoard(boardId, next);
+  // A board file from before the project file has no id of its own; once a
+  // project file exists it is that project's open board, and it has to say so,
+  // or nothing written here reaches the project's copy and open_board later
+  // brings back a stale one (found by round fifteen's cross-board move).
+  const id = boardId ?? readFileProject()?.project.activeBoardId ?? null;
+  writeFileBoard(next, rev + 1, id);
+  syncProjectFileBoard(id, next);
   return false;
 }
 
@@ -765,9 +783,12 @@ const sinceRead = [];
 /** What the last write did to the wall's questions and runtime, said once on that write's tail (round fourteen, entries 18, 19, 42). */
 let lastChange = null;
 const findingKey = (finding) => `${finding.kind}|${finding.ids.join(",")}|${finding.text}`;
-function noteChange(before, after) {
-  const was = readWall(before);
-  const now = readWall(after);
+function noteChange(before, after, boardId = null) {
+  // The same reading read_wall gives: a person cast on another board is not
+  // asked about, so a write's tail never names a question the reading does not.
+  const options = { elsewhere: elsewhereIds(boardId) };
+  const was = readWall(before, options);
+  const now = readWall(after, options);
   const wasKeys = new Set(was.findings.map(findingKey));
   const nowKeys = new Set(now.findings.map(findingKey));
   lastChange = {
@@ -845,7 +866,7 @@ async function commit(command) {
   const live = await writeBoard(next, rev, base, boardId, "exact");
   trail.push({ before: state, after: canon(next), what: describeCommand(command) });
   sinceRead.push(describeCommand(command));
-  noteChange(state, next);
+  noteChange(state, next, boardId);
   if (trail.length > TRAIL_CAP) trail.shift();
   undone.length = 0;
   return { state: next, changed, result, live };
@@ -877,7 +898,7 @@ async function commitAll(what, build) {
   const live = await writeBoard(current, rev, base, boardId, "exact");
   trail.push({ before: state, after: canon(current), what });
   sinceRead.push(what);
-  noteChange(state, current);
+  noteChange(state, current, boardId);
   if (trail.length > TRAIL_CAP) trail.shift();
   undone.length = 0;
   return { state: current, changed: true, value, live };
@@ -932,7 +953,7 @@ const CHECK_WORDS = {
   unlinked: "no card without an arrow",
   duplicate: "no two headlines alike",
   sequence: "no group too long for one sequence (act groups are not asked)",
-  uncast: "nobody in the cast on no card",
+  uncast: "nobody in the cast on no card of the project",
   absent: "nobody gone for a third of the story",
   backwards: "no payoff before its setup",
   unpaid: "no fold without a payoff",
@@ -942,13 +963,23 @@ const SAMPLE_NOTE = "sample: this is the wall PlotCoder starts with (Maya, Tom,
 
 // --- Reporting -------------------------------------------------------------
 
+/** What kinds of number a runtime folds together: measured from text, set by the writer, or the default page (round fifteen, entry 39). */
+function runtimeKinds(state) {
+  const measured = state.notes.filter((note) => isMeasured(note)).length;
+  const sized = state.notes.filter((note) => !isMeasured(note) && note.lengthEighths !== null).length;
+  const unsized = state.notes.length - measured - sized;
+  if (!state.notes.length) return "";
+  return `; of its ${state.notes.length} cards, ${measured} measured from written text, ${sized} sized by the writer, ${unsized} unsized and read as a page each`;
+}
+
 function summarize(state) {
   const nameOf = new Map(state.characters.map((character) => [character.id, character.name]));
   const notes = storyOrder(state)
     .map((note) => {
       const cast = note.characterIds.map((id) => nameOf.get(id) ?? id);
       const who = cast.length ? `, cast: ${cast.join(", ")}` : "";
-      const plant = note.plants ? (note.payoffBoardId ? ", plants → pays off later" : ", plants") : "";
+      // The board it pays off on, named here as read_wall names it (round fifteen, entry 44).
+      const plant = note.plants ? (note.payoffBoardId ? `, plants → pays off later on "${lastHeld?.project?.boards?.find((meta) => meta.id === note.payoffBoardId)?.name ?? note.payoffBoardId}"` : ", plants") : "";
       const snap = state.revision?.snapshot?.[note.id];
       const revised = snap && (snap.headline !== note.headline || snap.change !== note.change || (snap.text ?? "") !== (note.text ?? "") || (snap.location ?? "") !== (note.location ?? "")) ? `, changed in ${state.revision.color}` : "";
       const place = note.location ? `, at: ${note.location}` : "";
@@ -1023,8 +1054,8 @@ function summarize(state) {
     `left, for now: ${leftCount ? `${leftCount} question(s) the writer left; read_wall lists them` : "none"}`,
     `beats: ${beats}, scenes: ${scenes}`,
     state.targetEighths === DEFAULT_TARGET_EIGHTHS
-      ? `runtime: about ${formatPages(runtime)} pages (an estimate from the cards; a page runs about a minute); no target set — set_target for a pilot (60) or a half-hour (30); against the feature default of 120 it would be ${formatPages(-over)} under`
-      : `runtime: about ${formatPages(runtime)} pages of a ${formatPages(state.targetEighths)}-page target — ${over > 0 ? `${formatPages(over)} over` : over < 0 ? `${formatPages(-over)} under` : "on it"} (an estimate from the cards; a page runs about a minute)`,
+      ? `runtime: about ${formatPages(runtime)} pages (an estimate from the cards; a page runs about a minute); no target set — set_target for a pilot (60) or a half-hour (30); against the feature default of 120 it would be ${formatPages(-over)} under${runtimeKinds(state)}`
+      : `runtime: about ${formatPages(runtime)} pages of a ${formatPages(state.targetEighths)}-page target — ${over > 0 ? `${formatPages(over)} over` : over < 0 ? `${formatPages(-over)} under` : "on it"} (an estimate from the cards; a page runs about a minute)${runtimeKinds(state)}`,
     `notes: ${state.notes.length}, groups: ${state.groups.length}, arrows: ${state.arrows.length}, cast: ${state.characters.length}`,
     "cards (in story order — the follows arrows over the rows; each with its id):",
     notes || "  (no cards)",
@@ -1370,7 +1401,11 @@ server.registerTool(
       .map((group) => (group.dissolved ? ` Its group "${group.title}" dissolved: a frame needs two cards.` : ` Left its group "${group.title}", which keeps ${group.remaining} card${group.remaining === 1 ? "" : "s"}.`))
       .join("");
     const joined = result.joined ? ` The chain is joined behind it: "${result.joined.fromHeadline}" → "${result.joined.toHeadline}" (follows).` : "";
-    return ok(`Deleted "${result.headline}"${where(live)}.${arrows}${joined}${groups}`, result);
+    // The fold and where it paid off went with the card (round fifteen, entry 17).
+    const fold = result.plants
+      ? ` Its folded corner went with it${result.payoffBoardId ? ` — it paid off later, on "${(await readProject()).project.boards.find((meta) => meta.id === result.payoffBoardId)?.name ?? result.payoffBoardId}"` : ""}; nothing on the wall plants that now.`
+      : "";
+    return ok(`Deleted "${result.headline}"${where(live)}.${arrows}${joined}${groups}${fold}`, result);
   },
 );
 
@@ -1481,8 +1516,9 @@ server.registerTool(
   async (args) => {
     const wanted = args.questions?.length ? args.questions : args.kind ? [{ kind: args.kind, ids: args.ids, why: args.why }] : [];
     if (!wanted.length) return ok("Say which question: its kind as read_wall names it (and ids when that kind is asked more than once), or a list under questions.");
-    const { state } = await readBoard();
-    const reading = readWall(state);
+    const { state, boardId: leaveBoardId } = await readBoard();
+    const readOptions = { elsewhere: elsewhereIds(leaveBoardId) };
+    const reading = readWall(state, readOptions);
     const replies = [];
     const toLeave = [];
     for (const want of wanted) {
@@ -1522,7 +1558,7 @@ server.registerTool(
       after = out.state;
       for (const item of toLeave) replies.push(`Left, for now: [${item.finding.kind}] ${item.finding.text}${item.why ? ` — "${item.why}"` : ""}`);
     }
-    const still = readWall(after).findings;
+    const still = readWall(after, readOptions).findings;
     const tail = toLeave.length
       ? `${where(live)} ${once("leave-rule", "The wall keeps the writer's word and asks a left question again on its own when it would read differently; ask_again brings one back now. ")}The wall still asks ${still.length === 0 ? "nothing" : `${still.length}: ${still.map((finding) => `[${finding.kind}] ${finding.text}`).join(" ")}`}.`
       : "";
@@ -1542,7 +1578,8 @@ server.registerTool(
     const held = (state.left ?? []).filter((item) => item.kind === args.kind && (!args.ids || sameList(item.ids, args.ids)));
     if (held.length === 0) return ok(`Nothing of kind "${args.kind}"${args.ids ? ` about ids ${args.ids.join(", ")}` : ""} is left. read_wall lists what is, under "left, for now".`);
     const { result, live } = await commit({ type: "ask_again", kind: args.kind, ids: args.ids });
-    const reading = readWall((await readBoard()).state);
+    const again = await readBoard();
+    const reading = readWall(again.state, { elsewhere: elsewhereIds(again.boardId) });
     const back = reading.findings.filter((finding) => held.some((item) => item.kind === finding.kind && sameList(item.ids, finding.ids)));
     return ok(
       `Asked again${where(live)}: ${held.length} question${held.length === 1 ? "" : "s"} of kind "${args.kind}" ${held.length === 1 ? "is" : "are"} no longer left${back.length ? ` — the wall asks ${back.length === 1 ? "it" : `${back.length} of them`} now: ${back.map((finding) => finding.text).join(" ")}` : " — and the wall no longer asks it; the question had already changed"}.`,
@@ -1551,15 +1588,117 @@ server.registerTool(
   },
 );
 
+/**
+ * A scene moves to another board of the project (round fifteen, entry 16: a
+ * writer's "the shim should open episode two" had no tool, and the way round
+ * was a delete and a recreate by hand). Two frames, one per board: the card
+ * leaves the open board with everything a delete takes, and lands on the
+ * target with its own record — cast, place, when, rank, length, text, fold —
+ * wired after or before a card there, or at the head of that board's story.
+ */
+async function moveAcrossBoards(args, target, open, held) {
+  if (args.after && args.before) return ok("Say where: after one card's id, or before one, not both.");
+  const card = open.state.notes.find((note) => note.id === args.id);
+  if (!card) return ok(`No card with id ${args.id}. Call list_board.`);
+  const fromMeta = boardById(held.project, open.boardId ?? held.project.activeBoardId);
+  const targetState = isBoardState(held.boards[target.id]) ? normalizeState(held.boards[target.id]) : emptyState();
+  const anchorId = args.after ?? args.before;
+  const anchor = anchorId ? targetState.notes.find((note) => note.id === anchorId) : null;
+  if (anchorId && !anchor) return ok(`No card with id ${anchorId} on "${target.name}". open_board there and list_board for its ids, or leave after and before out to land at the head of its story.`);
+  // Leave: one frame on the board it is on.
+  let taken = null;
+  await commitAll(`move_scene "${card.headline}" to "${target.name}" (leave)`, (step) => {
+    taken = step({ type: "delete_note", id: card.id }).result;
+  });
+  // Open the board it is going to, everywhere.
+  const now = await readProject();
+  await openBoardEverywhere(now.project, now.boards, now.rev, now.base, target.id);
+  // Land: one frame there.
+  const isFollows = (arrow) => arrow.kind !== "setup";
+  let landedId = card.id;
+  let joinedGroup = null;
+  let headOf = null;
+  let forgotLater = false;
+  const { state: final, live } = await commitAll(`move_scene "${card.headline}" to "${target.name}" (land)`, (step, current) => {
+    const here = current();
+    landedId = here.notes.some((note) => note.id === card.id) ? newId() : card.id;
+    step({
+      type: "create_note",
+      id: landedId,
+      headline: card.headline,
+      change: card.change,
+      color: card.color,
+      rank: card.rank,
+      lengthEighths: card.lengthEighths,
+      characterIds: card.characterIds,
+      plants: card.plants,
+      location: card.location,
+      when: card.when,
+      text: card.text,
+      ...nextPlace(here),
+    });
+    if (card.plants && card.payoffBoardId && card.payoffBoardId !== target.id) step({ type: "set_payoff_board", ids: [landedId], boardId: card.payoffBoardId });
+    if (card.plants && card.payoffBoardId === target.id) forgotLater = true;
+    if (anchor) {
+      const mid = current();
+      if (args.after) {
+        for (const arrow of mid.arrows.filter((item) => isFollows(item) && item.from === anchor.id)) {
+          step({ type: "delete_arrow", id: arrow.id });
+          step({ type: "create_arrow", from: landedId, to: arrow.to, kind: "follows" });
+        }
+        step({ type: "create_arrow", from: anchor.id, to: landedId, kind: "follows" });
+      } else {
+        for (const arrow of mid.arrows.filter((item) => isFollows(item) && item.to === anchor.id)) {
+          step({ type: "delete_arrow", id: arrow.id });
+          step({ type: "create_arrow", from: arrow.from, to: landedId, kind: "follows" });
+        }
+        step({ type: "create_arrow", from: landedId, to: anchor.id, kind: "follows" });
+      }
+      const anchorGroup = current().groups.find((group) => group.noteIds.includes(anchor.id));
+      if (anchorGroup) {
+        step({ type: "add_to_group", id: anchorGroup.id, noteIds: [landedId] });
+        joinedGroup = anchorGroup.title || "an untitled group";
+      }
+    } else {
+      const head = storyOrder(here)[0];
+      if (head && here.arrows.some(isFollows)) {
+        step({ type: "create_arrow", from: landedId, to: head.id, kind: "follows" });
+        headOf = head.headline;
+      }
+    }
+    step({ type: "apply_poses", poses: organizePoses(current(), {}) });
+  });
+  const order = storyOrder(final);
+  const arrows = taken?.arrows?.length
+    ? ` Left behind on "${fromMeta.name}": ${taken.arrows.map((arrow) => `"${arrow.fromHeadline}" → "${arrow.toHeadline}" (${arrow.kind}${arrow.kind === "setup" && arrow.to === card.id ? "; that fold is unpaid again" : ""})`).join(", ")}${taken.joined ? `; the chain is joined behind it, "${taken.joined.fromHeadline}" → "${taken.joined.toHeadline}"` : ""}.`
+    : ` No arrow touched it on "${fromMeta.name}".`;
+  const groups = (taken?.groups ?? []).map((group) => (group.dissolved ? ` Its group "${group.title}" there dissolved: a frame needs two cards.` : ` It left its group "${group.title}" there, which keeps ${group.remaining} card${group.remaining === 1 ? "" : "s"}.`)).join("");
+  const landed = anchor
+    ? `${args.after ? "after" : "before"} "${anchor.headline}"${joinedGroup ? `, in "${joinedGroup}"` : ""}`
+    : headOf ? `at the head of the story, before "${headOf}"` : "as the only card wired to nothing yet";
+  const fold = card.plants ? (forgotLater ? " It paid off later on this board, so that mark is forgotten: draw the setup arrow here." : " Its folded corner came with it; a setup arrow does not cross boards, so draw the payoff here if it is here.") : "";
+  return ok(
+    `Moved "${card.headline}" from "${fromMeta.name}" to "${target.name}", with its cast, place, when, rank, length${card.text ? ", text" : ""} and colour; it is card ${landedId} there${where(live)}.${arrows}${groups} It landed ${landed}, and the wall was tidied.${fold} Story order on "${target.name}" now: ${order.map((note, index) => `${index + 1}. ${note.headline}`).join(", ")}. "${target.name}" is the open board now. Undo is per board: undo here takes back the landing; open_board "${fromMeta.name}" and undo takes back the leaving.`,
+    { id: landedId, board: target.id, order: order.map((note) => note.id) },
+  );
+}
+
 server.registerTool(
   "move_scene",
   {
     title: "Move a scene in the story",
     description:
-      "Move a card to another place in the story order — after one card, or before one — by rewiring its follows arrows and tidying the wall along them, as one step that undo takes back whole. The story order is the follows arrows: the card leaves its place (what pointed at it now points at what it pointed at) and lands between the target and what followed it. A person does this by dragging in the outline. Needs a wall with follows arrows; on a wall without any, create_arrow the sequence first, or move_note by position.",
-    inputSchema: { id: z.string(), after: z.string().optional(), before: z.string().optional() },
+      "Move a card to another place in the story order — after one card, or before one — by rewiring its follows arrows and tidying the wall along them, as one step that undo takes back whole. The story order is the follows arrows: the card leaves its place (what pointed at it now points at what it pointed at) and lands between the target and what followed it. A person does this by dragging in the outline. Needs a wall with follows arrows; on a wall without any, create_arrow the sequence first, or move_note by position. To another board of the project: pass board (name, id or number from list_boards) and, optionally, after or before a card there; with neither the card lands at the head of that board's story. Across boards the card keeps its cast, place, when, rank, length, text and fold; its arrows stay behind, and that board is then the open one. Undo is per board: one step there, one on the board it left.",
+    inputSchema: { id: z.string(), after: z.string().optional(), before: z.string().optional(), board: z.union([z.string().min(1), z.number()]).optional() },
   },
   async (args) => {
+    if (args.board !== undefined) {
+      const held = await readProject();
+      const target = findBoard(held.project, String(args.board));
+      if (!target) return ok(`No board matches "${args.board}". Call list_boards for the real ones.`);
+      const open = await readBoard();
+      if (target.id !== (open.boardId ?? held.project.activeBoardId)) return moveAcrossBoards(args, target, open, held);
+    }
     if (!args.after === !args.before) return ok("Say where: after one card's id, or before one, not both.");
     const { state } = await readBoard();
     const find = (id) => state.notes.find((note) => note.id === id);
@@ -1711,7 +1850,8 @@ server.registerTool(
     const lines = [
       `the writer's own: ${own.length}`,
       ...own.map((structure) => `  - ${structure.id} — "${structure.name}" (${structure.beats.length} beats: ${structure.beats.map((beat) => `${beat.name} at ${Math.round(beat.at * 100)}%`).join(", ")})`),
-      `built in: ${TEMPLATES.length} — ${TEMPLATES.map((template) => `${template.id} "${template.name}" (${template.beats.length} beats)`).join(", ")}; each beat's name, prompt and place in the story are in the JSON`,
+      `built in: ${TEMPLATES.length}`,
+      ...TEMPLATES.map((template) => `  - ${template.id} — "${template.name}" (${template.beats.length} beats: ${template.beats.map((beat) => `${beat.name} at ${Math.round(beat.at * 100)}%`).join(", ")})`),
       "compare_structure sets one of these beside this wall's beats, page by page, and lays nothing",
     ];
     return ok(lines.join("\n"), { builtIn: TEMPLATES.map((template) => ({ id: template.id, name: template.name, beats: template.beats })), own });
@@ -1737,12 +1877,15 @@ server.registerTool(
     if (!chosen) return ok(`No structure called "${args.structure}". list_structures names the built-in five and the writer's own.`);
     const comparison = compareStructure(state, chosen.beats);
     const beats = state.notes.filter((note) => note.rank === "beat").length;
+    const allMeasured = state.notes.length > 0 && state.notes.every((note) => isMeasured(note));
+    const short = state.targetEighths > 0 && boardEighths(state) * 2 < state.targetEighths;
     const lines = [
-      `"${chosen.name}" beside this wall's ${beats} beat${beats === 1 ? "" : "s"}, of ${formatPages(state.targetEighths)} pages (the story so far runs to p. ${comparison.soFar}); a match is the nearest of the wall's beats within ${MATCH_PAGES} pages, one to one and in order:`,
+      `"${chosen.name}" beside this wall's ${beats} beat${beats === 1 ? "" : "s"}, of ${formatPages(state.targetEighths)} pages (the story so far runs to p. ${comparison.soFar}${allMeasured ? ", measured" : ", an estimate: unsized cards read as a page each"}); a match is the nearest of the wall's beats within ${MATCH_PAGES} pages, one to one and in order:`,
       ...describeComparison(comparison).map((line) => `  - ${line}`),
       comparison.unmatched.length
         ? `beats of the wall no beat of the structure answers: ${comparison.unmatched.map((beat) => `"${beat.headline}" (p. ${beat.page})`).join(", ")}`
         : "every beat of the wall answers one of the structure's",
+      ...(short ? [`the wall runs to less than half its target, so its beats sit early and the ${MATCH_PAGES}-page window pairs them with the structure's first beats by arithmetic; the pairing says more once the cards are sized or written, and whether a turn is missing is the writer's call, not this reading's`] : []),
       beats === 0 ? "No card on this board is marked as a beat (set_rank), so there is nothing to compare; apply_template lays the structure's beats to fill." : "Nothing moved and nothing was made: this is a reading. apply_template lays the beats as cards when the writer wants them.",
     ];
     return ok(lines.join("\n"), { structure: { id: chosen.id, name: chosen.name }, ...comparison });
@@ -1870,7 +2013,7 @@ server.registerTool(
     }
     const printed = sceneLineCount(args.text);
     return ok(
-      `Wrote "${result.headline}": ${printed} line(s) as they print (headings, blank lines and wrapped dialogue counted), measured at ${formatPages(noteEighths(result))} of a 55-line page, rounded to the nearest eighth and never below one${where(live)}.${revisionMark(state, result.id)}${once("heading-from-place", " The heading comes from the card's place and when, so the text starts with the action.")} While the text stands the card is measured, not estimated; the estimate underneath is untouched.`,
+      `Wrote "${result.headline}": ${printed} line(s) as they print (headings, blank lines and wrapped dialogue counted), measured at ${formatPages(noteEighths(result))} of a 55-line page, rounded to the nearest eighth and never below one eighth${where(live)}.${revisionMark(state, result.id)}${once("heading-from-place", " The heading comes from the card's place and when, so the text starts with the action.")} While the text stands the wall reads the measure, not the estimate${result.lengthEighths !== null ? ` (the writer's ${formatPages(result.lengthEighths)} pages)` : ""}; the estimate is kept for when the text goes, and set_length changes it.`,
       { ...result, eighths: noteEighths(result), measured: true, printedLines: printed },
     );
   },
@@ -2026,7 +2169,7 @@ server.registerTool(
   {
     title: "Export as Final Draft",
     description:
-      "The open board as a Final Draft .fdx: a heading per card with its scene number by wall order, the scene's text as script paragraphs (action, character, parenthetical, dialogue, dual dialogue, transition) or the change line as action after the mark [Unwritten] when unwritten, and a title page for the project (a one-board film is its project). Pass a path to write the file; otherwise the XML comes back.",
+      "The open board as a Final Draft .fdx: a heading per card with its scene number by wall order, the scene's text as script paragraphs (action, character, parenthetical, dialogue, dual dialogue, transition) or the change line as action after the mark [Unwritten] when unwritten, and a title page: the project's name, and for a series the episode line (Episode 2 of 6 · its name). One board per file; a series is one file per episode. Pass a path to write the file; otherwise the XML comes back with the file's name in a comment on its second line.",
     inputSchema: { path: z.string().optional() },
   },
   async (args) => {
@@ -2035,12 +2178,14 @@ server.registerTool(
     const board = project.boards.find((item) => item.id === project.activeBoardId);
     const titles = scriptTitles(project, board);
     const xml = toFdx(state, { ...titles, draftDate: new Date().toISOString() });
+    // The file's name, so an agent writing it by hand has one (round fifteen, entry 34).
+    const filename = `${titles.title}${titles.episode ? ` - ${board?.name ?? ""}` : ""}`.replace(/[\\/:*?"<>|]+/g, " ").replace(/\s+/g, " ").trim() + ".fdx";
     if (args.path) {
       fs.mkdirSync(path.dirname(path.resolve(args.path)), { recursive: true });
       fs.writeFileSync(args.path, xml);
-      return ok(`Wrote a Final Draft file with ${state.notes.length} scene(s), titled "${titles.title}", to ${args.path}.`);
+      return ok(`Wrote a Final Draft file with ${state.notes.length} scene(s), titled "${titles.title}"${titles.episode ? ` (${titles.episode})` : ""}, to ${args.path}.`);
     }
-    return ok(xml);
+    return ok(xml.replace(/^(<\?xml[^>]*\?>\n)/, `$1<!-- Save as: ${filename.replace(/--/g, "- -")} -->\n`));
   },
 );
 
@@ -2467,7 +2612,7 @@ server.registerTool(
         ? ok(`Already in the cast as "${result.name}" (${result.id}). Use that id.`, result)
         : ok("No character added: the name was empty.");
     }
-    return ok(`Added "${result.name}" to the project's cast${where(live)}; every board of the project casts from it.`, result);
+    return ok(`Added "${result.name}" (id ${result.id}) to the project's cast${where(live)}; every board of the project casts from it.`, result);
   },
 );
 
@@ -2505,22 +2650,37 @@ server.registerTool(
   {
     title: "Read a person's page",
     description:
-      "Read one person's page back, by id or by name: the five lines — looks, voice, wants, needs, notes — as they stand, and which cards the person is on. list_board says only which lines are written; this says what they say.",
+      "Read one person's page back, by id or by name: the five lines — looks, voice, wants, needs, notes — as they stand, and every card the person is on across every board of the project, in story order, each with its place, when and rank. The cast is the project's (one record, one page), so this reads all of it; list_board says only which lines are written.",
     inputSchema: { id: z.string().optional(), name: z.string().optional() },
   },
   async (args) => {
     const key = (args.id ?? args.name ?? "").trim();
     if (!key) return ok("Say who: the person's id or name from list_board.");
-    const { state } = await readBoard();
+    const { state, boardId } = await readBoard();
+    const { project, boards } = await readProject();
     const wanted = key.toLowerCase();
     const person = state.characters.find((item) => item.id === key) ?? state.characters.find((item) => item.name.trim().toLowerCase() === wanted);
     if (!person) return ok(`Nobody called "${key}" in the cast. Call list_board for the cast, or add_character.`);
-    const on = storyOrder(state).filter((note) => note.characterIds.includes(person.id));
+    // The person's part is the project's, not one board's (R51; round fifteen,
+    // entries 22 and 23): every board, in the project's order, the open one read live.
+    const openId = boardId ?? project.activeBoardId;
+    const parts = project.boards.map((meta) => {
+      const held = meta.id === openId ? state : isBoardState(boards[meta.id]) ? normalizeState(boards[meta.id]) : emptyState();
+      const on = storyOrder(held).filter((note) => (note.characterIds ?? []).includes(person.id));
+      return { meta, on };
+    });
+    const total = parts.reduce((sum, part) => sum + part.on.length, 0);
+    const where_ = (note) => [note.location ? `at ${note.location}` : "", note.when ? note.when : "", note.rank === "beat" ? "beat" : ""].filter(Boolean).join(" · ");
     const lines = [
-      `${person.name} (${person.id}) — on ${on.length} card${on.length === 1 ? "" : "s"}${on.length ? `, in story order: ${on.map((note) => `"${note.headline}"`).join(", ")}` : ""}`,
+      `${person.name} (${person.id}) — on ${total} card${total === 1 ? "" : "s"} across ${project.boards.length} board${project.boards.length === 1 ? "" : "s"} of the project`,
       ...CHARACTER_FIELDS.map((field) => `  ${field}: ${(person[field] ?? "").trim() || "(empty)"}`),
+      ...parts.map((part) =>
+        part.on.length
+          ? `  "${part.meta.name}", ${part.on.length} card${part.on.length === 1 ? "" : "s"} in story order: ${part.on.map((note, index) => `${index + 1}. "${note.headline}"${where_(note) ? ` (${where_(note)})` : ""}`).join("; ")}`
+          : `  "${part.meta.name}": on no card`,
+      ),
     ];
-    return ok(lines.join("\n"), { ...person, cards: on.map((note) => note.id) });
+    return ok(lines.join("\n"), { ...person, cards: parts.flatMap((part) => part.on.map((note) => note.id)), boards: parts.map((part) => ({ id: part.meta.id, name: part.meta.name, cards: part.on.map((note) => note.id) })) });
   },
 );
 
@@ -2706,7 +2866,7 @@ server.registerTool(
           : "No group made: a group needs at least two cards.",
       );
     }
-    return ok(`Grouped ${result.noteIds.length} cards as "${result.title}"${where(live)}.`, result);
+    return ok(`Grouped ${result.noteIds.length} cards as "${result.title}" (group id ${result.id})${where(live)}.`, result);
   },
 );
 
@@ -2876,6 +3036,16 @@ server.registerTool(
         `premise: ${project.premise ? `"${project.premise}"` : "(not set)"}`,
         `boards: ${project.boards.length}`,
         describeBoards(project, boards, changedAt),
+        // The project's length as one line, so a series is not arithmetic by hand (round fifteen, entry 38).
+        ...(project.boards.length > 1
+          ? (() => {
+              const states = project.boards.map((meta) => (isBoardState(boards[meta.id]) ? normalizeState(boards[meta.id]) : null)).filter(Boolean);
+              const pages = states.reduce((sum, state) => sum + boardEighths(state), 0);
+              const target = states.reduce((sum, state) => sum + state.targetEighths, 0);
+              const cards = states.reduce((sum, state) => sum + state.notes.length, 0);
+              return [`the whole project: ${cards} cards, about ${formatPages(pages)} of ${formatPages(target)} pages across ${states.length} boards (each board's runtime is an estimate unless every scene is written)`];
+            })()
+          : []),
       ].join("\n"),
       project,
     );
@@ -2911,7 +3081,11 @@ server.registerTool(
     const next = renameProject(project, args.name);
     if (next === project) return ok("Project name unchanged.");
     await writeProject(next, boards, rev, base);
-    return ok(`Project renamed to "${next.name}"${where(live)}.`, next);
+    // The line at the head of every reply names the project it works; it must
+    // follow the rename (round fifteen, entry 40).
+    if (accountDoor) workingProject(next.id, next.name);
+    const several = (next.boards ?? []).length > 1;
+    return ok(`Project renamed to "${next.name}"${where(live)}. It shows at the head of every reply, in list_boards and read_wall, and as the title of every script out${several ? `, where each board follows it as an episode line (Episode 1 of ${next.boards.length} · ${next.boards[0].name})` : ""}. The boards keep their names.`, next);
   },
 );
 

package/src/board/agents.js

@@ -42,7 +42,7 @@ export const AGENTS = {
       text: "Skip this when the account is the wall. Without an account, a wall is a folder: any folder, empty is fine — choose one that will outlive your session, never a scratch one. The app run from that folder shows the wall, and the server writes it there (PLOTCODER_ROOT, or the folder it is run from). A fresh folder holds the sample; new_board for the writer's wall, then rename_project. No app running? export_fountain is the wall in order, as text.",
     },
   ],
-  firstNote: "Make these four before anything else; none depends on another, so any order is fine. list_words and list_workflows are the app's and read no project; read_wall and list_reminders are about the wall you will work, so after open_project, open_board, new_project or empty_account, make those two again. Every reply's first line names the project it read and how many the account holds; list_projects lists them. On an account with no project yet, read_wall has nothing to read and says so, and list_reminders gives the house principles every project starts with; new_project (name, pages, and board for the first board's name), then read_wall and list_reminders again. No server in front of you, and no shell to take the shell door? Nothing gets you in from inside the session: say so, and ask the person to wire the server and start a new session.",
+  firstNote: "Make these four before anything else; none depends on another, so any order is fine. list_words and list_workflows are the app's and read no project; read_wall and list_reminders are about the wall you will work, so after open_project or open_board make those two again, and after new_project read the wall once it holds cards. An emptied account has nothing to read: go straight to new_project. Every reply's first line names the project it read and how many the account holds; list_projects lists them. On an account with no project yet, read_wall has nothing to read and says so, and list_reminders gives the house principles every project starts with; new_project (name, pages, and board for the first board's name). The reading holds the beats and the runs; the ids of every card, the cast and the places are list_board's, so make that your fifth call before you touch anything. No server in front of you, and no shell to take the shell door? Nothing gets you in from inside the session: say so, and ask the person to wire the server and start a new session.",
   first: [
     { tool: "list_words", why: "the room's words, the app's meaning." },
     { tool: "read_wall", why: "the reading: the beats, the runs, the setups, and what the wall asks. The records — every card, the cast, the places, the rows — are list_board's. A fresh folder holds a sample wall (Maya, Tom, the letter) and the reading says so only when it is the sample; it is not the writer's." },
@@ -64,16 +64,19 @@ export const AGENTS = {
 
 /** The on-ramp as one text: the file at /llms.txt, and what an agent reads. */
 export function agentsAsText() {
-  const lines = ["# PlotCoder — for agents", "", AGENTS.lead, "", `The guide: ${AGENTS.guide}. Read it once, before your first call if you can; it is the whole and this page is its first page, and where the two differ, the guide wins. Then Call these first, below. The doors between are for wiring a server in; skip them when the tools are already in front of you.`, "", "## Doors"];
-  for (const door of AGENTS.doors) {
-    lines.push(`- ${door.name}: ${door.text}`);
-    if (door.code) lines.push("", "```", door.code, "```", "");
-  }
-  lines.push("## Call these first");
+  // The calls and the rules first, the doors after: an agent with the tools in
+  // front of it reads two pages of wiring it was told to skip before it reached
+  // the first call (round fifteen, entry 1).
+  const lines = ["# PlotCoder — for agents", "", AGENTS.lead, "", `The guide: ${AGENTS.guide}. Read it once, before your first call if you can; it is the whole and this page is its first page, and where the two differ, the guide wins. Then Call these first, below. The doors at the end are for wiring a server in; skip them when the tools are already in front of you.`, "", "## Call these first"];
   AGENTS.first.forEach((item, index) => lines.push(`${index + 1}. ${item.tool} — ${item.why}`));
   lines.push("", AGENTS.firstNote);
   lines.push("", "## Rules");
   for (const rule of AGENTS.rules) lines.push(`- ${rule}`);
-  lines.push("", "## For the person", AGENTS.person, "", "## The guide", AGENTS.guide, "");
+  lines.push("", "## Doors");
+  for (const door of AGENTS.doors) {
+    lines.push(`- ${door.name}: ${door.text}`);
+    if (door.code) lines.push("", "```", door.code, "```", "");
+  }
+  lines.push("## For the person", AGENTS.person, "", "## The guide", AGENTS.guide, "");
   return lines.join("\n");
 }

package/src/board/fdx.d.ts

@@ -5,7 +5,7 @@ import type { FountainScene } from "./fountain";
 
 export declare function toFdx(
   state: BoardState,
-  options?: { title?: string; project?: string; author?: string; draftDate?: string },
+  options?: { title?: string; episode?: string; author?: string; draftDate?: string },
 ): string;
 
 export type SetAside = {

package/src/board/fdx.js

@@ -88,10 +88,11 @@ export function toFdx(state, options = {}) {
 
   const title = [];
   if (options.title) title.push(paragraph("General", options.title, ' Alignment="Center"'));
-  if (options.project && options.project !== options.title) title.push(paragraph("General", `An episode of ${options.project}`, ' Alignment="Center"'));
+  if (options.episode) title.push(paragraph("General", options.episode, ' Alignment="Center"'));
   if (options.author) title.push(paragraph("General", `Written by ${options.author}`, ' Alignment="Center"'));
   if (options.draftDate) title.push(paragraph("General", options.draftDate.slice(0, 10)));
-  title.push(paragraph("General", state.lock ? `Scene numbers locked ${String(state.lock.at).slice(0, 10)}.` : "Scene numbers follow the wall's order and are not locked."));
+  // A lock is a fact about the document; that there is none is the app's business, not the title page's (round fifteen, entry 36).
+  if (state.lock) title.push(paragraph("General", `Scene numbers locked ${String(state.lock.at).slice(0, 10)}.`));
   if (state.revision) title.push(paragraph("General", `${revisionLine(state)}; changed paragraphs are marked.`));
   // The revision set Final Draft shows its marks from (round fourteen, entry 45).
   const revisions = state.revision

package/src/board/fountain.d.ts

@@ -12,6 +12,7 @@ export declare function unmark(text: string | null | undefined): { text: string;
 
 export declare function titlePage(titles: {
   title?: string;
+  episode?: string;
   credit?: string;
   author?: string;
   draftDate?: string;
@@ -22,7 +23,7 @@ export type FountainOptions = {
   /** The board's name. */
   title?: string;
   /** The project's name, when the board is one of several. */
-  project?: string;
+  episode?: string;
   premise?: string;
   author?: string;
   /** ISO date string; only the date is printed. */

package/src/board/fountain.js

@@ -61,9 +61,10 @@ export function unmark(text) {
 }
 
 /** The title page block. `titles` is what the writer would put above the script. */
-export function titlePage({ title, credit, author, draftDate, notes }) {
+export function titlePage({ title, episode, credit, author, draftDate, notes }) {
   const lines = [];
   if (title) lines.push(`Title: ${title}`);
+  if (episode) lines.push(`Episode: ${episode}`);
   if (credit) lines.push(`Credit: ${credit}`);
   if (author) lines.push(`Author: ${author}`);
   if (draftDate) lines.push(`Draft date: ${draftDate}`);
@@ -97,7 +98,7 @@ export function toFountain(state, options = {}) {
 
   const head = titlePage({
     title: options.title || "Untitled",
-    credit: options.project && options.project !== options.title ? `An episode of ${options.project}` : undefined,
+    episode: options.episode,
     author: options.author,
     draftDate: options.draftDate ? options.draftDate.slice(0, 10) : undefined,
     notes,

package/src/board/markdown.d.ts

@@ -2,7 +2,7 @@ import type { Line } from "./paginate";
 import type { BoardState } from "./reducer";
 
 /** What a document carries above the script: the board's name, the project's when it has several boards, the premise. */
-export type TakeOptions = { title?: string; project?: string; premise?: string };
+export type TakeOptions = { title?: string; episode?: string; premise?: string };
 
 /** The wall as Markdown (R54): title, premise, logline, beats as headings, a heading per scene, the text or the change line. */
 export declare function toMarkdown(state: BoardState, options?: TakeOptions): string;

package/src/board/markdown.js

@@ -28,7 +28,7 @@ function upper(text) {
 
 function documentTitle(options) {
   const title = options.title || "Untitled";
-  return options.project && options.project !== title ? `${options.project} · ${title}` : title;
+  return options.episode ? `${title} · ${options.episode}` : title;
 }
 
 /** A scene's text as Markdown paragraphs: action as it is, a speech as its cue in bold with the lines hard-broken under it. */
@@ -177,8 +177,8 @@ export function toPlainText(state, options = {}) {
   );
   const title = options.title || "Untitled";
   const out = [];
-  if (options.project && options.project !== title) {
-    out.push(centred(upper(options.project)), "", centred(title));
+  if (options.episode) {
+    out.push(centred(upper(title)), "", centred(options.episode));
   } else {
     out.push(centred(upper(title)));
   }

package/src/board/project.d.ts

@@ -68,7 +68,7 @@ export declare function renameProject(project: ProjectRecord, name: string, now?
 export declare function setPremise(project: ProjectRecord, premise: string, now?: string): ProjectRecord;
 export declare function boardById(project: ProjectRecord, id: string): BoardMeta | null;
 /** What a script going out is called: a named project is the title, its board beside it only when the project has several. */
-export declare function scriptTitles(project: ProjectRecord, board: BoardMeta | null | undefined): { title: string; project?: string };
+export declare function scriptTitles(project: ProjectRecord, board: BoardMeta | null | undefined): { title: string; episode?: string };
 export declare function findBoard(project: ProjectRecord, key: string): BoardMeta | null;
 export declare function reidentifyProject(
   project: ProjectRecord,

package/src/board/project.js

@@ -300,7 +300,15 @@ export function scriptTitles(project, board) {
   const boardName = (board?.name ?? "").trim() || "Untitled";
   const named = typeof project?.name === "string" && project.name.trim() && project.name !== DEFAULT_PROJECT_NAME;
   if (!named) return { title: boardName };
-  if ((project.boards ?? []).length > 1) return { title: boardName, project: project.name };
+  const boards = project.boards ?? [];
+  if (boards.length > 1) {
+    // A series: the project is the title and the board is the episode line,
+    // numbered in the project's order, so one file says which episode it is
+    // (round fifteen, entries 32 and 37).
+    const index = boards.findIndex((item) => item.id === board?.id);
+    const number = index >= 0 ? `Episode ${index + 1} of ${boards.length}` : "An episode";
+    return { title: project.name, episode: `${number} · ${boardName}` };
+  }
   return { title: project.name };
 }
 

package/src/board/readWall.js

@@ -230,9 +230,14 @@ export function readWall(state, options = {}) {
     const note = byId.get(id);
     return note && (note.lengthEighths !== null || (note.text ?? "").trim());
   }));
-  if (between.length >= 2 && claimed) {
-    const typical = median(between.map((run) => run.eighths));
-    const longest = between.reduce((top, run) => (run.eighths > top.eighths ? run : top));
+  // The typical run is the median of the runs that hold a card: an empty run
+  // is a question of its own ("empty"), and counting it here made a small
+  // wall's one ordinary scene read as a sag against a median of an eighth
+  // (round fifteen, entry 10).
+  const filled = between.filter((run) => run.ids.length > 0);
+  if (filled.length >= 2 && claimed) {
+    const typical = median(filled.map((run) => run.eighths));
+    const longest = filled.reduce((top, run) => (run.eighths > top.eighths ? run : top));
     if (typical > 0 && longest.eighths > SAG_RATIO * typical) {
       findings.push({
         kind: "sag",

package/src/board/reducer.js

@@ -620,6 +620,10 @@ export function applyCommand(state, command, now = nowIso()) {
         result: {
           id: command.id,
           headline: gone.headline,
+          // The fold and where it paid off go with the card too; a door that
+          // says what went should say these (round fifteen, entry 17).
+          plants: gone.plants === true,
+          payoffBoardId: gone.payoffBoardId ?? null,
           arrows: taken.map((arrow) => ({ ...arrow, fromHeadline: headlineOf(arrow.from), toHeadline: headlineOf(arrow.to) })),
           joined: joined ? { ...joined, fromHeadline: headlineOf(joined.from), toHeadline: headlineOf(joined.to) } : null,
           groups: left,

package/src/board/workflows.js

@@ -28,7 +28,7 @@ export const WORKFLOWS = [
       { question: "Which scenes are the turns?", hint: "Name them, or say \"propose them and I will strike\".", tool: "set_rank" },
       { question: "Does it have acts?", hint: "If so, where does each break fall?", tool: "create_group" },
       { question: "Where does each scene happen?", hint: "In your own words. A scene that moves through one location is still one place.", tool: "set_location" },
-      { question: "When does a scene happen, where that matters?", hint: "That night; the fourth of October. It goes in the headline for now.", tool: "the headline" },
+      { question: "When does a scene happen, where that matters?", hint: "That night; the fourth of October. It goes beside the place, never in the headline.", tool: "set_when" },
       { question: "Who is in each scene, and what do we call them?", hint: "A full name, or a role for someone unnamed — the man in 42. And who is only spoken of, never in a scene? They go in someone's notes, not the cast.", tool: "add_character, cast, update_character" },
       { question: "What is planted, and where does it pay off?", hint: "Name the episode when it pays off outside this one, so the fold is deliberate and the wall knows where to look.", tool: "set_plant with later, create_arrow" },
       { question: "Which scenes do you already know run long or short?", hint: "A day in the story is not a page count; leave the rest unsized.", tool: "set_length" },