plotcoder-board 0.1.16 → 0.1.18

package/src/board/agents.js

@@ -7,7 +7,7 @@
 
 export const AGENTS = {
   lead:
-    "A storyline wall. Cards are scenes, beats are the big turns, arrows say what follows or pays off what. An agent driven by a person has every tool a person here has; the person directs, the agent operates. Call the tools; never fake a mouse. Already have the plotcoder-board tools in front of you? Skip the doors and go to Call these first.",
+    "A storyline wall. Cards are scenes, beats are the big turns, arrows say what follows or pays off what. An agent driven by a person has every tool a person here has; the person directs, the agent operates. Call the tools; never fake a mouse. Already have the plotcoder-board tools in front of you? Then your way in is: read the guide, make the four calls under Call these first, and skip the doors between — they are for wiring a server in.",
   doors: [
     {
       id: "mcp",
@@ -18,7 +18,7 @@ export const AGENTS = {
     {
       id: "shell",
       name: "The shell, for this session",
-      text: "npx -y plotcoder-board@latest call <tool> '{json}' makes one call, with no MCP and no restart. One server per call, so undo and the project you opened do not carry between calls; npx -y plotcoder-board@latest call --batch < calls.jsonl runs a file of calls — one per line, {\"tool\": \"…\", \"arguments\": {…}} — on one server, so they do. With the account door the sign-in is kept in the folder's .plotcoder between calls (PLOTCODER_SESSION=0 to sign in every time). PLOTCODER_PROJECT names the project for each call. The JSON tail is off on this door; PLOTCODER_JSON=1 keeps it. PLOTCODER_ROOT points the server at the folder whose wall you mean; without it, the folder you run it from.",
+      text: "npx -y plotcoder-board@latest call <tool> '{json}' makes one call, with no MCP and no restart. One server per call, so undo and the project you opened do not carry between calls; npx -y plotcoder-board@latest call --batch < calls.jsonl runs a file of calls — one per line, {\"tool\": \"…\", \"arguments\": {…}} — on one server, so they do. With the account door the sign-in is kept in the folder's .plotcoder between calls (PLOTCODER_SESSION=0 to sign in every time). PLOTCODER_PROJECT names the project for each call. The JSON tail is off on every door; PLOTCODER_JSON=1 in the server's environment adds it. PLOTCODER_ROOT points the server at the folder whose wall you mean; without it, the folder you run it from.",
     },
     {
       id: "hosted",
@@ -42,10 +42,10 @@ 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. They are about the wall you will work, so after open_project, open_board, new_project or empty_account, read_wall again. 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, then the four 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, 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.",
   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 — are list_board's. A fresh folder holds a sample wall (Maya, Tom, the letter) and says so; it is not the writer's." },
+    { 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." },
     { tool: "list_workflows", why: "what a writer can ask you for." },
     { tool: "list_reminders", why: "the house principles the app starts with, and the writer's own; read them before you change anything. Reminders live on the project and go with it." },
   ],

package/src/board/fdx.js

@@ -11,9 +11,9 @@
 // tags used, so the MCP server reads the same file the browser does.
 
 import { parseScene, TRANSITION } from "./paginate.js";
-import { readingOrder } from "./readWall.js";
+import { storyOrder } from "./readWall.js";
 import { sceneHeading, standInFor } from "./fountain.js";
-import { sceneNumbers } from "./numbering.js";
+import { REVISION_HEX, revisionLine, revisionMarks, sceneNumbers } from "./numbering.js";
 
 function escapeXml(text) {
   return String(text)
@@ -33,14 +33,16 @@ function unescapeXml(text) {
     .replace(/&/g, "&");
 }
 
-function paragraph(type, text, extra = "") {
-  return `    <Paragraph Type="${type}"${extra}>\n      <Text>${escapeXml(text)}</Text>\n    </Paragraph>\n`;
+function paragraph(type, text, extra = "", revised = false) {
+  // A revised paragraph's text carries the revision's id, as Final Draft marks one.
+  const textAttr = revised ? ' RevisionID="1"' : "";
+  return `    <Paragraph Type="${type}"${extra}>\n      <Text${textAttr}>${escapeXml(text)}</Text>\n    </Paragraph>\n`;
 }
 
-function speechParagraphs(speech) {
-  let out = paragraph("Character", speech.name.toUpperCase());
+function speechParagraphs(speech, revisedAt = () => false) {
+  let out = paragraph("Character", speech.name.toUpperCase(), "", revisedAt(speech.at));
   for (const part of speech.parts) {
-    out += paragraph(part.kind === "parenthetical" ? "Parenthetical" : "Dialogue", part.text);
+    out += paragraph(part.kind === "parenthetical" ? "Parenthetical" : "Dialogue", part.text, "", revisedAt(part.at ?? speech.at));
   }
   return out;
 }
@@ -51,29 +53,34 @@ function speechParagraphs(speech) {
  * when written and the change line as action when not, and a title page.
  */
 export function toFdx(state, options = {}) {
-  const order = readingOrder(state.notes);
+  const order = storyOrder(state);
   const numbers = sceneNumbers(order, state.lock);
+  const marks = revisionMarks(state);
   let content = "";
   order.forEach((note, index) => {
     const number = numbers.get(note.id) ?? index + 1;
-    content += paragraph("Scene Heading", sceneHeading(note).slice(1), ` Number="${number}"`).replace(
-      "<Text>",
-      `<SceneProperties Length="" Page="" Title="${escapeXml(note.headline)}" />\n      <Text>`,
+    const mark = marks.get(note.id);
+    // A changed card with no changed text line (its headline, change or place moved) marks its heading.
+    const headingRevised = Boolean(mark?.revised && mark.lines.size === 0);
+    const revisedAt = (at) => Boolean(mark && typeof at === "number" && mark.lines.has(at));
+    content += paragraph("Scene Heading", sceneHeading(note).slice(1), ` Number="${number}"`, headingRevised).replace(
+      /<Text( RevisionID="1")?>/,
+      (_m, attr) => `<SceneProperties Length="" Page="" Title="${escapeXml(note.headline)}" />\n      <Text${attr ?? ""}>`,
     );
     // Unwritten: the change line stands in as action, marked as every export marks it.
     const elements = parseScene(note.text && note.text.trim() ? note.text : standInFor(note));
     for (let i = 0; i < elements.length; i += 1) {
       const element = elements[i];
-      if (element.kind === "action") content += paragraph("Action", element.text);
-      else if (element.kind === "transition") content += paragraph("Transition", element.text);
-      else if (element.kind === "centered") content += paragraph("General", element.text, ' Alignment="Center"');
+      if (element.kind === "action") content += paragraph("Action", element.text, "", revisedAt(element.at));
+      else if (element.kind === "transition") content += paragraph("Transition", element.text, "", revisedAt(element.at));
+      else if (element.kind === "centered") content += paragraph("General", element.text, ' Alignment="Center"', revisedAt(element.at));
       else if (element.kind === "speech") {
         const next = elements[i + 1];
         if (next && next.kind === "speech" && next.dual) {
-          content += `    <Paragraph>\n      <DualDialogue>\n${speechParagraphs(element)}${speechParagraphs(next)}      </DualDialogue>\n    </Paragraph>\n`;
+          content += `    <Paragraph>\n      <DualDialogue>\n${speechParagraphs(element, revisedAt)}${speechParagraphs(next, revisedAt)}      </DualDialogue>\n    </Paragraph>\n`;
           i += 1;
         } else {
-          content += speechParagraphs(element);
+          content += speechParagraphs(element, revisedAt);
         }
       }
     }
@@ -85,12 +92,18 @@ export function toFdx(state, options = {}) {
   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."));
+  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
+    ? `  <Revisions ActiveSet="1" Location="7.50" RevisionMode="No" RevisionsShown="Active" ShowAllMarks="No" ShowAllSets="No">\n    <Revision Color="${REVISION_HEX[state.revision.color] ?? "#000000"}" FullRevision="No" ID="1" Mark="*" Name="${escapeXml(state.revision.name)}" Style="" />\n  </Revisions>\n`
+    : "";
 
   return (
     `<?xml version="1.0" encoding="UTF-8" standalone="no" ?>\n` +
     `<FinalDraft DocumentType="Script" Template="No" Version="5">\n` +
     `  <Content>\n${content}  </Content>\n` +
     `  <TitlePage>\n    <Content>\n${title.join("")}    </Content>\n  </TitlePage>\n` +
+    revisions +
     `</FinalDraft>\n`
   );
 }

package/src/board/fountain.d.ts

@@ -3,6 +3,8 @@
 import type { BoardNote, BoardState } from "./reducer";
 
 export declare function sceneHeading(note: BoardNote): string;
+/** A heading split back into its place and its when. */
+export declare function splitHeading(heading: string): { place: string; when: string };
 /** The mark every export sets before an unwritten scene's change line. */
 export declare const UNWRITTEN_MARK: string;
 export declare function standInFor(note: Pick<BoardNote, "change">): string;

package/src/board/fountain.js

@@ -13,17 +13,29 @@
 // except the heading and the action.
 
 import { formatPages, boardEighths } from "./reducer.js";
-import { readingOrder } from "./readWall.js";
+import { storyOrder } from "./readWall.js";
+import { revisionLine, revisionMarks } from "./numbering.js";
 
 function upper(text) {
   return text.trim().replace(/\s+/g, " ").toUpperCase();
 }
 
-/** A forced scene heading: the place, or the headline when the card has none. */
+/**
+ * A forced scene heading: the place, or the headline when the card has none,
+ * and the card's when after a dash — THE PIER AT FENIT - NIGHT (R55).
+ */
 export function sceneHeading(note) {
   const place = typeof note.location === "string" ? note.location.trim() : "";
+  const when = typeof note.when === "string" ? note.when.trim() : "";
   const words = place || note.headline || "UNTITLED";
-  return `.${upper(words)}`;
+  return `.${upper(words)}${when ? ` - ${upper(when)}` : ""}`;
+}
+
+/** A heading split back into its place and its when: "THE PIER AT FENIT - NIGHT" → both. */
+export function splitHeading(heading) {
+  const match = /^(.*?)\s+-\s+([^-]+)$/.exec(heading ?? "");
+  if (!match) return { place: (heading ?? "").trim(), when: "" };
+  return { place: match[1].trim(), when: match[2].trim() };
 }
 
 /**
@@ -71,12 +83,14 @@ export function titlePage({ title, credit, author, draftDate, notes }) {
  */
 export function toFountain(state, options = {}) {
   const nameOf = new Map((state.characters ?? []).map((character) => [character.id, character.name]));
-  const order = readingOrder(state.notes);
+  const order = storyOrder(state);
   const beats = order.filter((note) => note.rank === "beat").length;
+  const revisionOf = revisionMarks(state);
 
   const notes = [];
   if (options.premise) notes.push(`Premise: ${options.premise}`);
   if (state.logline) notes.push(`Logline: ${state.logline}`);
+  if (state.revision) notes.push(`Revision: ${revisionLine(state)}; a changed scene carries a [[changed in the revision]] note.`);
   notes.push(
     `From the wall: ${order.length} card${order.length === 1 ? "" : "s"}, ${beats} beat${beats === 1 ? "" : "s"}, about ${formatPages(boardEighths(state))} of ${formatPages(state.targetEighths)} pages.`,
   );
@@ -104,9 +118,11 @@ export function toFountain(state, options = {}) {
       body.push("");
     }
     const marks = [];
+    const revisionMarksFor = (_list, card) => Boolean(revisionOf.get(card.id)?.revised);
     const cast = (note.characterIds ?? []).map((id) => nameOf.get(id)).filter(Boolean);
     if (cast.length) marks.push(`with ${cast.join(", ")}`);
     if (note.plants) marks.push("plants something to pay off later");
+    if (revisionMarksFor(marks, note)) marks.push(`changed in the ${state.revision.color} revision`);
     if (marks.length) {
       body.push(`[[${marks.join(" · ")}]]`);
       body.push("");
@@ -212,7 +228,7 @@ function sameWords(a, b) {
  * its text. Returns commands for the kernel, so every door applies the same.
  */
 export function mergeFountain(state, parsed) {
-  const order = readingOrder(state.notes);
+  const order = storyOrder(state);
   const used = new Set();
   const commands = [];
   let cursor = 0; // where in the wall's order the last match was
@@ -243,6 +259,7 @@ export function mergeFountain(state, parsed) {
     const anchor = order[cursor - 1] ?? order.at(-1);
     const headline = scene.synopsis || titleCase(scene.heading);
     const isPlace = scene.forced && Boolean(scene.synopsis);
+    const parts = splitHeading(scene.heading);
     const id = `scene-${Math.random().toString(36).slice(2, 8)}`;
     // A marked body is an unwritten scene: its words are the change line, not a page.
     const body = unmark(scene.text);
@@ -251,7 +268,8 @@ export function mergeFountain(state, parsed) {
       id,
       headline,
       change: body.marked ? body.text || "What changes?" : scene.text ? firstSentence(scene.text) : "What changes?",
-      location: isPlace ? titleCase(scene.heading) : "",
+      location: isPlace ? titleCase(parts.place) : "",
+      when: isPlace ? parts.when.toLowerCase() : "",
       text: body.marked ? "" : scene.text,
       x: anchor ? anchor.x + 40 : 140,
       y: anchor ? anchor.y + 40 : 140,

package/src/board/markdown.d.ts

@@ -12,4 +12,5 @@ export declare function toPlainText(state: BoardState, options?: TakeOptions): s
 
 export declare const GUTTER: number;
 export declare const COLUMN: Record<"character" | "more" | "parenthetical" | "dialogue", number>;
-export declare function setLine(line: Line): string;
+/** A printed line set with spaces; `star` adds a revision's star in the right margin. */
+export declare function setLine(line: Line, star?: boolean): string;

package/src/board/markdown.js

@@ -17,10 +17,10 @@
 // It pastes into anything and reads as a script wherever the font is
 // monospaced.
 
-import { readingOrder } from "./readWall.js";
-import { sceneHeading, standInFor } from "./fountain.js";
+import { storyOrder } from "./readWall.js";
+import { sceneHeading, standInFor, UNWRITTEN_MARK } from "./fountain.js";
 import { paginate, parseScene, WIDTH } from "./paginate.js";
-import { sceneNumbers } from "./numbering.js";
+import { revisionLine, revisionMarks, sceneNumbers } from "./numbering.js";
 
 function upper(text) {
   return text.trim().replace(/\s+/g, " ").toUpperCase();
@@ -64,11 +64,13 @@ function sceneMarkdown(text) {
  *   when the project has several boards; options.premise
  */
 export function toMarkdown(state, options = {}) {
-  const order = readingOrder(state.notes);
+  const order = storyOrder(state);
   const numbers = sceneNumbers(order, state.lock);
+  const marks = revisionMarks(state);
   const out = [`# ${documentTitle(options)}`, ""];
   if (options.premise) out.push(`*${options.premise}*`, "");
   if (state.logline) out.push(`**${state.logline}**`, "");
+  if (state.revision) out.push(`*${revisionLine(state)} · a scene changed since it began has \\* after its heading*`, "");
   let beat = 0;
   for (const note of order) {
     if (note.rank === "beat") {
@@ -76,12 +78,14 @@ export function toMarkdown(state, options = {}) {
       out.push(`## ${beat}. ${note.headline || "Untitled beat"}`, "");
     }
     const heading = sceneHeading(note).slice(1);
-    out.push(`### ${numbers.get(note.id) ?? ""} · ${heading}`.replace(/^###  · /, "### "), "");
-    if (note.headline && upper(note.headline) !== heading) out.push(`*${note.headline.trim()}*`, "");
+    const star = marks.get(note.id)?.revised ? " \\*" : "";
+    out.push(`### ${numbers.get(note.id) ?? ""} · ${heading}${star}`.replace(/^###  · /, "### "), "");
+    // The headline as a synopsis line — not under a beat, whose heading is the headline already.
+    if (note.rank !== "beat" && note.headline && upper(note.headline) !== heading) out.push(`*${note.headline.trim()}*`, "");
     if (note.text && note.text.trim()) out.push(...sceneMarkdown(note.text));
-    // Unwritten: the change line stands in, marked and in italics, so a reader
-    // in Docs can tell the one written scene from sixteen placeholders.
-    else out.push(`*${standInFor(note)}*`, "");
+    // Unwritten: the change line stands in after the mark in bold, a plain
+    // paragraph so it never reads as a second synopsis line (round fourteen, 30).
+    else out.push(`**${UNWRITTEN_MARK}**${standInFor(note).slice(UNWRITTEN_MARK.length)}`, "");
   }
   return `${out.join("\n").trimEnd()}\n`;
 }
@@ -112,8 +116,15 @@ function columnLine(line) {
   return text;
 }
 
-/** A printed line set with spaces. Exported for the test; the file is `toPlainText`. */
-export function setLine(line) {
+/** A printed line set with spaces, a revision's star in the right margin when `star`. Exported for the test; the file is `toPlainText`. */
+export function setLine(line, star = false) {
+  const set = setLineBare(line);
+  if (!star) return set;
+  if (line.kind === "heading" && line.sceneNumber !== null && line.sceneNumber !== undefined) return `${set} *`;
+  return `${set.padEnd(GUTTER + WIDTH.action + 1)} *`;
+}
+
+function setLineBare(line) {
   const text = line.text ?? "";
   switch (line.kind) {
     case "blank":
@@ -151,8 +162,9 @@ export function setLine(line) {
  *   when the project has several boards
  */
 export function toPlainText(state, options = {}) {
-  const order = readingOrder(state.notes);
+  const order = storyOrder(state);
   const numbers = sceneNumbers(order, state.lock);
+  const marks = revisionMarks(state);
   const result = paginate(
     order.map((note) => ({
       id: note.id,
@@ -170,10 +182,16 @@ export function toPlainText(state, options = {}) {
   } else {
     out.push(centred(upper(title)));
   }
+  if (state.revision) out.push("", centred(revisionLine(state).toUpperCase()));
   out.push("", "");
+  // Pages run on with no gap: a page turn inside a paragraph is not a blank
+  // line in a text file (round fourteen, entry 33).
   for (const page of result.pages) {
-    if (page.number > 1) out.push("");
-    for (const line of page.lines) out.push(setLine(line));
+    for (const line of page.lines) {
+      const mark = marks.get(line.noteId);
+      const star = Boolean(mark) && (line.kind === "heading" ? mark.revised && mark.lines.size === 0 : typeof line.src === "number" && mark.lines.has(line.src));
+      out.push(setLine(line, star));
+    }
   }
   return `${out.join("\n").replace(/\n{4,}/g, "\n\n\n").trimEnd()}\n`;
 }

package/src/board/numbering.d.ts

@@ -1,6 +1,6 @@
 // Type surface for numbering.js — locked scene numbers and revision marks (Roadmap 2, item 8).
 
-import type { BoardNote } from "./reducer";
+import type { BoardNote, BoardState } from "./reducer";
 
 export type Lock = { at: string; numbers: Record<string, string> };
 export type Snapshot = { headline: string; change: string; location: string; text: string };
@@ -11,3 +11,10 @@ export declare function lockFrom(order: ReadonlyArray<Pick<BoardNote, "id">>, ex
 export declare function revisedLines(text: string | undefined, snapshotText: string | null | undefined): number[];
 export declare function isRevised(note: BoardNote, snapshot: Snapshot | undefined): boolean;
 export declare const REVISION_COLORS: readonly string[];
+
+/** The industry's revision colours as Final Draft writes them. */
+export declare const REVISION_HEX: Record<string, string>;
+/** Card id → whether it changed since the revision's snapshot, and which source lines of its text did. Empty when no revision. */
+export declare function revisionMarks(state: BoardState): Map<string, { revised: boolean; lines: Set<number> }>;
+/** "Blue revision · 2026-09-17", or "" when none. */
+export declare function revisionLine(state: BoardState): string;

package/src/board/numbering.js

@@ -3,9 +3,12 @@
 // Until a draft goes out, scene numbers follow the wall's order. Lock them
 // and they stop moving: every scene keeps the number it had, a scene added
 // between 14 and 15 is 14A (then 14B), one added before the first is A1, and
-// moving cards never renumbers what is locked. A revision is a name and a
-// colour over a snapshot of the scenes; a line that differs from the snapshot
-// is marked, so the changed lines print in the revision's colour with a star.
+// moving cards never renumbers what is locked. A scene added after the lock
+// has no number of its own: its letter is its place between two locked
+// numbers, so it follows the scene if the scene moves (round fourteen, 39).
+// A revision is a name and a colour over a snapshot of the scenes; a line
+// that differs from the snapshot is marked, so the changed lines print in the
+// revision's colour with a star — on the page, in plain text, in Final Draft.
 // All pure: the kernel holds the lock and the snapshot, this module reads them.
 
 const LETTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
@@ -87,3 +90,33 @@ export function isRevised(note, snapshot) {
 }
 
 export const REVISION_COLORS = ["white", "blue", "pink", "yellow", "green", "goldenrod", "buff", "salmon", "cherry"];
+
+/** The industry's revision colours as Final Draft writes them. */
+export const REVISION_HEX = { white: "#FFFFFF", blue: "#5B8DEF", pink: "#E879A5", yellow: "#D9B400", green: "#4CAF6A", goldenrod: "#C99A1B", buff: "#C9A978", salmon: "#E28466", cherry: "#C0392B" };
+
+/**
+ * What the revision marks on each card, for every export (round fourteen,
+ * entry 45: the marks lived only on the page). Card id → { revised, lines }:
+ * `revised` when anything on the card differs from the snapshot, `lines` the
+ * source lines of its text that do. Empty when no revision is in progress.
+ */
+export function revisionMarks(state) {
+  const marks = new Map();
+  const revision = state.revision;
+  if (!revision) return marks;
+  for (const note of state.notes) {
+    const snapshot = revision.snapshot?.[note.id];
+    const revised = isRevised(note, snapshot);
+    marks.set(note.id, { revised, lines: new Set(revised ? revisedLines(note.text, snapshot?.text ?? null) : []) });
+  }
+  return marks;
+}
+
+/** One line naming the revision for the head of a document: "Blue revision · 2026-09-17". */
+export function revisionLine(state) {
+  const revision = state.revision;
+  if (!revision) return "";
+  const colour = `${revision.color.charAt(0).toUpperCase()}${revision.color.slice(1)}`;
+  const name = revision.name && revision.name.toLowerCase() !== revision.color ? ` "${revision.name}"` : "";
+  return `${colour} revision${name} · ${String(revision.since).slice(0, 10)}`;
+}

package/src/board/organize.js

@@ -16,7 +16,7 @@
 // Pure and DOM-free like the kernel: the app and the MCP server both call it,
 // and it returns poses for apply_poses rather than touching anything.
 
-import { readingOrder } from "./readWall.js";
+import { readingOrder, storyOrder } from "./readWall.js";
 import { NOTE_HEIGHT, NOTE_WIDTH } from "./reducer.js";
 
 export const ROW_CARDS = 5;
@@ -36,35 +36,8 @@ const STEP_Y = NOTE_HEIGHT + GAP;
  * given (or every card) take part; arrows to cards outside are ignored.
  */
 export function arrowOrder(state, ids) {
-  const scope = ids ? new Set(ids) : null;
-  const notes = state.notes.filter((note) => !scope || scope.has(note.id));
-  const reading = readingOrder(notes).map((note) => note.id);
-  const rank = new Map(reading.map((id, index) => [id, index]));
-  const preds = new Map(reading.map((id) => [id, []]));
-  for (const arrow of state.arrows) {
-    if (arrow.kind === "setup") continue;
-    if (!rank.has(arrow.from) || !rank.has(arrow.to)) continue;
-    preds.get(arrow.to).push(arrow.from);
-  }
-  for (const list of preds.values()) list.sort((a, b) => rank.get(a) - rank.get(b));
-
-  const placed = new Set();
-  const visiting = new Set();
-  const order = [];
-  function visit(id) {
-    if (placed.has(id) || visiting.has(id)) return;
-    visiting.add(id);
-    for (const from of preds.get(id)) {
-      // A pair pointing both ways is a tie: reading order keeps it.
-      if (preds.get(from).includes(id)) continue;
-      visit(from);
-    }
-    visiting.delete(id);
-    placed.add(id);
-    order.push(id);
-  }
-  for (const id of reading) visit(id);
-  return order;
+  // One story order for the whole app: the reading's (R56).
+  return storyOrder(state, ids).map((note) => note.id);
 }
 
 /** Pull each group's members up to its first member, keeping their order. */

package/src/board/readWall.d.ts

@@ -66,11 +66,13 @@ export type WallReading = {
   /** The questions the wall asks now. A left one (R53) is not here while its words hold. */
   findings: Finding[];
   /** Questions the writer has left, for now: the same question, with when it was left. */
-  left: Array<Finding & { since: string }>;
+  left: Array<Finding & { since: string; why?: string }>;
 };
 
 /** Rows top to bottom, cards left to right within a row. */
 export declare function readingOrder(notes: BoardNote[]): BoardNote[];
+/** Story order: reading order with each follows arrow pulling its source in front of its target (R56). */
+export declare function storyOrder(state: Pick<BoardState, "notes" | "arrows">, ids?: string[]): BoardNote[];
 export declare function readWall(
   state: BoardState,
   options?: {

package/src/board/readWall.js

@@ -9,10 +9,13 @@
 // Pure and DOM-free like the reducer, so the Reminders modal, the MCP server and
 // the tests all read the same wall the same way.
 //
-// Order: the wall gives the order, and the wall is free (D20), so order here is
-// reading order — rows top to bottom, cards left to right within a row. Arrows
-// do not yet change the order; that is the first refinement to make once this
-// slice has been used.
+// Order: the wall gives the order, and the wall is free (D20). Reading order is
+// rows top to bottom, cards left to right within a row; story order is reading
+// order with each follows arrow pulling its source in front of its target, the
+// order organize lays the wall out in. Since round fourteen (entry 41) every
+// reading uses story order, so a card wired between two others reads there
+// before any tidy — the arrows are the writer's claim about the order, and
+// where they say nothing the positions decide.
 
 import { boardEighths, EIGHTHS_PER_PAGE, formatPages, NOTE_HEIGHT, noteEighths } from "./reducer.js";
 
@@ -46,6 +49,46 @@ const FILLER = new Set([
  * Cards in reading order: banded into rows by y, then left to right. A free
  * wall has no rows, so this is the order a person's eye takes across it.
  */
+/**
+ * Story order: reading order, with each follows arrow pulling its source in
+ * front of its target; a pair pointing both ways is a tie and reading order
+ * keeps it. The order organize lays the wall out in, and the order every
+ * reading, numbering and page uses (R56). Returns the notes.
+ */
+export function storyOrder(state, ids) {
+  const scope = ids ? new Set(ids) : null;
+  const notes = state.notes.filter((note) => !scope || scope.has(note.id));
+  const reading = readingOrder(notes);
+  const byId = new Map(reading.map((note) => [note.id, note]));
+  const rank = new Map(reading.map((note, index) => [note.id, index]));
+  const preds = new Map(reading.map((note) => [note.id, []]));
+  for (const arrow of state.arrows ?? []) {
+    if (arrow.kind === "setup") continue;
+    if (!rank.has(arrow.from) || !rank.has(arrow.to)) continue;
+    preds.get(arrow.to).push(arrow.from);
+  }
+  for (const list of preds.values()) list.sort((a, b) => rank.get(a) - rank.get(b));
+  const placed = new Set();
+  const visiting = new Set();
+  const order = [];
+  function visit(id) {
+    if (placed.has(id) || visiting.has(id)) return;
+    visiting.add(id);
+    for (const from of preds.get(id)) {
+      if (preds.get(from).includes(id)) continue;
+      visit(from);
+    }
+    visiting.delete(id);
+    placed.add(id);
+    order.push(byId.get(id));
+  }
+  for (const note of reading) visit(note.id);
+  return order;
+}
+
+/** The leading "Day three, night." of a headline, the convention the guide asks for until a card has a when: not a scene's words. */
+const DAY_PREFIX = /^\s*day\s+[\w-]+(?:\s*,\s*[\w\s-]+?)?\s*[.:]\s*/i;
+
 export function readingOrder(notes) {
   const byTop = [...notes].sort((a, b) => a.y - b.y || a.x - b.x);
   const rows = [];
@@ -98,6 +141,14 @@ function pages(eighths) {
   return formatPages(Math.round(eighths));
 }
 
+/** "1 page", "3 pages", "4/8 of a page" — never "1 pages" (round thirteen, entry 15). */
+function pagesWord(eighths) {
+  const n = pages(eighths);
+  if (n === "1") return "1 page";
+  if (/^\d+\/8$/.test(n)) return `${n} of a page`;
+  return `${n} pages`;
+}
+
 function quote(note) {
   return `"${note.headline}"`;
 }
@@ -114,7 +165,7 @@ export function readWall(state, options = {}) {
   // People on a card of another board of the project (R51) are cast, and
   // are not asked about here.
   const elsewhere = new Set(Array.isArray(options.elsewhere) ? options.elsewhere : []);
-  const order = readingOrder(state.notes);
+  const order = storyOrder(state);
   const beats = order.filter((note) => note.rank === "beat");
 
   // Runs: the scene pages strictly between consecutive beats, plus the opening
@@ -172,14 +223,21 @@ export function readWall(state, options = {}) {
 
   // The sag detector (R25): one run out of proportion with the others.
   const between = runs.filter((run) => run.from !== null && run.to !== null);
-  if (between.length >= 2) {
+  // A run of unsized, unwritten cards is the default page each, so a wall
+  // where every run is defaults measures nothing but card counts; the sag
+  // waits until some card in some run is sized or written (round fourteen, 12).
+  const claimed = between.some((run) => run.ids.some((id) => {
+    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));
     if (typical > 0 && longest.eighths > SAG_RATIO * typical) {
       findings.push({
         kind: "sag",
         ids: [longest.from, longest.to],
-        text: `About ${pages(longest.eighths)} pages run between "${headline(longest.from)}" and "${headline(longest.to)}"; the median run here is about ${pages(typical)} (a beat's own pages are in no run). Is something sagging there, or is it one long set piece?`,
+        text: `About ${pagesWord(longest.eighths)} run between "${headline(longest.from)}" and "${headline(longest.to)}"; the median run here is about ${pagesWord(typical)} (a beat's own pages are in no run). Is something sagging there, or is it one long set piece?`,
       });
     }
   }
@@ -267,7 +325,9 @@ export function readWall(state, options = {}) {
     for (let j = i + 1; j < order.length; j += 1) {
       const a = order[i];
       const b = order[j];
-      if (sameScene(a.headline, b.headline)) {
+      // A leading "Day three." is the guide's convention for when a scene
+      // happens, not the scene's words (round fourteen, entry 13).
+      if (sameScene(a.headline.replace(DAY_PREFIX, ""), b.headline.replace(DAY_PREFIX, ""))) {
         findings.push({
           kind: "duplicate",
           ids: [a.id, b.id],
@@ -387,7 +447,7 @@ export function readWall(state, options = {}) {
       (item) => item.kind === finding.kind && sameList(item.ids, finding.ids) && item.text === finding.text,
     );
     if (!entry) return true;
-    left.push({ ...finding, since: entry.since });
+    left.push({ ...finding, since: entry.since, ...(entry.why ? { why: entry.why } : {}) });
     return false;
   });