plotcoder-board 0.1.15 → 0.1.16

package/README.md

@@ -41,7 +41,7 @@ Every board verb goes through one command kernel, `src/board/reducer.js`, and th
 
 - **The wall.** Tap the words to type, drag the paper to move. Lasso to select, then Group. Drag a card's handle onto another card for an arrow. ⌘Z takes back any change, whichever door made it.
 - **`window.plotcoder`** on the page, for a console or a CDP session.
-- **The MCP server**, published to npm as `plotcoder-board`: `npx -y plotcoder-board@latest` is the server, `npx -y plotcoder-board@latest call <tool> '{json}'` one call from a shell, `npx -y plotcoder-board@latest serve` the hosted door on a port (a `Dockerfile` is here too). Inside the repo it is `scripts/plotcoder-mcp.mjs`, wired for Cursor in `.cursor/mcp.json` and for Claude Code in `.mcp.json` (run `npm ci` once first). A version tag (`v0.2.0`) publishes it, with `NPM_TOKEN` in the repo's secrets. Seventy-seven tools: reading (`list_board`, `read_wall`, `read_pages`, `read_character`, `page_count`, `list_words`, `list_workflows`, `segment_brief`, `compare_structure`); the card, cast, place, group and arrow verbs, `set_logline`, `set_target`, `set_rank`, `set_plant`, `write_scene`, `move_scene`, `organize`, `apply_template` with `list_structures`, `save_structure`, `remove_structure`; `leave_question` and `ask_again`; `undo` and `redo`; the project's `list_boards`, `open_board`, `new_board`, `rename_board`, `delete_board`, `set_premise`, `rename_project` and the reminders; Fountain and Final Draft both ways, Markdown and plain text out (`export_markdown`, `export_text`); the production half (`lock_numbers`, `unlock_numbers`, `start_revision`, `end_revision`); the project as a file both ways (`export_project`, `import_project`); and, through the account door, `list_projects`, `open_project`, `new_project`, `delete_project`, `empty_account`, `delete_account`, `add_picture`, `add_take`, `list_takes`, `list_files`, `remove_file`, `build_segment`. If the dev app is open, a tool call lands on the wall within a second; if not, it edits the board file and the wall catches up on the next load.
+- **The MCP server**, published to npm as `plotcoder-board`: `npx -y plotcoder-board@latest` is the server, `npx -y plotcoder-board@latest call <tool> '{json}'` one call from a shell, `npx -y plotcoder-board@latest serve` the hosted door on a port (a `Dockerfile` is here too). Inside the repo it is `scripts/plotcoder-mcp.mjs`, wired for Cursor in `.cursor/mcp.json` and for Claude Code in `.mcp.json` (run `npm ci` once first). A version tag (`v0.2.0`) publishes it, with `NPM_TOKEN` in the repo's secrets. Seventy-eight tools: reading (`list_board`, `read_wall`, `read_pages`, `read_character`, `page_count`, `list_words`, `list_workflows`, `segment_brief`, `compare_structure`); the card, cast, place, group (with `add_to_group`) and arrow verbs, `set_logline`, `set_target`, `set_rank`, `set_plant`, `write_scene`, `move_scene`, `organize`, `apply_template` with `list_structures`, `save_structure`, `remove_structure`; `leave_question` and `ask_again`; `undo` and `redo`; the project's `list_boards`, `open_board`, `new_board`, `rename_board`, `delete_board`, `set_premise`, `rename_project` and the reminders; Fountain and Final Draft both ways, Markdown and plain text out (`export_markdown`, `export_text`); the production half (`lock_numbers`, `unlock_numbers`, `start_revision`, `end_revision`); the project as a file both ways (`export_project`, `import_project`); and, through the account door, `list_projects`, `open_project`, `new_project`, `delete_project`, `empty_account`, `delete_account`, `add_picture`, `add_take`, `list_takes`, `list_files`, `remove_file`, `build_segment`. If the dev app is open, a tool call lands on the wall within a second; if not, it edits the board file and the wall catches up on the next load.
 - **The account door.** With `PLOTCODER_EMAIL` and `PLOTCODER_PASSWORD` in the agent's environment — the writer's own — and no dev app answering, the same server works the writer's project on the account directly, and every change lands live on every open wall. `PLOTCODER_PROJECT` picks a project by name or id. No account yet? `claim_account` makes one with the writer's email and a password they chose. The on-ramp — the doors, what to call first, the rules — is in the app behind *Are you an agent? Start here* and served at [plotcoder.com/llms.txt](https://plotcoder.com/llms.txt), both from `src/board/agents.js`.
 
 An agent should call the tools, never fake mouse drags. The skill in `.cursor/skills/plotcoder-board/SKILL.md` says how; `.claude/skills/plotcoder-board` is a symlink to the same file.
@@ -51,9 +51,9 @@ 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. Twelve rounds have been run, the first three through a
-repo checkout and the rest through the account door, and every finding they
-logged is fixed. [`blind-runs/`](blind-runs/) holds the rules that keep a round honest,
+just what produces it. Thirteen rounds have been run, the first three through a
+repo checkout and the rest through the account door; every finding from the
+first twelve is fixed, and round thirteen's six chosen first are too. [`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
@@ -96,4 +96,4 @@ next round into a test of `claim_account` instead of the door it meant to test.
 
 ## Status
 
-Version 0.1.14. 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.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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plotcoder-board",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "type": "module",
   "scripts": {
     "dev": "vite",

package/scripts/plotcoder-mcp-server.mjs

@@ -75,6 +75,7 @@ import {
   liftCast,
   mergeRoster,
   sameRoster,
+  scriptTitles,
   withRoster,
 } from "../src/board/project.js";
 
@@ -758,6 +759,9 @@ const TRAIL_CAP = 50;
 const trail = [];
 /** What undo took back, newest last; a new change of this server's clears it. */
 const undone = [];
+/** The last read_wall's questions, and what changed since: a leave answers the reading in front of the agent (round thirteen, entry 19). */
+let lastReading = null;
+const sinceRead = [];
 
 function describeCommand(command) {
   switch (command.type) {
@@ -799,6 +803,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));
   if (trail.length > TRAIL_CAP) trail.shift();
   undone.length = 0;
   return { state: next, changed, result, live };
@@ -828,6 +833,7 @@ async function commitAll(what, build) {
   if (!changed) return { state: current, changed: false, value, live: base !== null };
   const live = await writeBoard(current, rev, base, boardId, "exact");
   trail.push({ before: state, after: canon(current), what });
+  sinceRead.push(what);
   if (trail.length > TRAIL_CAP) trail.shift();
   undone.length = 0;
   return { state: current, changed: true, value, live };
@@ -1086,22 +1092,37 @@ server.registerTool(
   {
     title: "Set card length",
     description:
-      "Set how long cards run, in pages. An ordinary scene is about 1; a quick beat might be 0.25; a set piece might be 3 or 4. This is an estimate the writer owns — set it when you are told a length or when the card plainly describes one, and do not silently re-estimate a card someone has already sized.",
+      "Set how long cards run, in pages. An ordinary scene is about 1; a quick beat might be 0.25; a set piece might be 3 or 4. This is an estimate the writer owns — set it when you are told a length or when the card plainly describes one, and do not silently re-estimate a card someone has already sized. Pass pages \"unsized\" (or 0) to take a length away: the card claims nothing again and reads as about a page, the way a new card does.",
     inputSchema: {
       ids: z.array(z.string()).min(1),
-      pages: pagesSchema,
+      pages: z
+        .union([pagesSchema, z.literal(0), z.literal("unsized"), z.null()])
+        .describe('Pages; a fraction is fine. "unsized" (or 0) takes the length away.'),
     },
   },
   async (args) => {
-    const { state, result, live } = await commit({
+    const unsizing = args.pages === "unsized" || args.pages === 0 || args.pages === null;
+    const { state, changed, result, live } = await commit({
       type: "set_length",
       ids: args.ids,
-      lengthEighths: toEighths(args.pages),
+      lengthEighths: unsizing ? null : toEighths(args.pages),
     });
-    return ok(
-      `${result?.length ?? 0} card(s) now run ${args.pages} page(s), the writer's estimate${where(live)}. The board runs about ${formatPages(boardEighths(state))} pages against a ${formatPages(state.targetEighths)}-page target.`,
-      result,
-    );
+    if (!changed) {
+      const these = args.ids.length === 1 ? "the card is" : "those cards are";
+      return ok(
+        unsizing
+          ? `Nothing to unsize: ${these} unsized already, or not on the board (list_board for the ids).`
+          : `Nothing changed: ${these} at ${args.pages} page(s) already, or not on the board (list_board for the ids).`,
+      );
+    }
+    const runtime = `The board runs about ${formatPages(boardEighths(state))} pages against a ${formatPages(state.targetEighths)}-page target.`;
+    if (unsizing) {
+      return ok(
+        `${result.length} card(s) unsized${where(live)}: no length claimed, so each reads as about a page until someone sizes it, and list_board says "unsized". ${runtime}`,
+        result,
+      );
+    }
+    return ok(`${result.length} card(s) now run ${args.pages} page(s), the writer's estimate${where(live)}. ${runtime}`, result);
   },
 );
 
@@ -1265,13 +1286,20 @@ server.registerTool(
   {
     title: "Delete note",
     description:
-      "Remove a card from the board. Also removes any arrows touching it and drops it from groups.",
+      "Remove a card from the board. Its arrows go with it and it leaves its group; the reply names each arrow by its cards and says what the group kept, and undo brings all of it back.",
     inputSchema: { id: z.string() },
   },
   async (args) => {
-    const { result } = await commit({ type: "delete_note", id: args.id });
+    const { result, live } = await commit({ type: "delete_note", id: args.id });
     if (result === undefined) return ok(`No card with id ${args.id}.`);
-    return ok("Deleted card.", result);
+    // Say what went with the card (round thirteen, entry 17).
+    const arrows = result.arrows.length
+      ? ` Took ${result.arrows.length === 1 ? "its arrow" : `its ${result.arrows.length} arrows`} with it: ${result.arrows.map((arrow) => `"${arrow.fromHeadline}" → "${arrow.toHeadline}" (${arrow.kind})`).join(", ")}.`
+      : " No arrow touched it.";
+    const groups = result.groups
+      .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("");
+    return ok(`Deleted "${result.headline}"${where(live)}.${arrows}${groups}`, result);
   },
 );
 
@@ -1292,6 +1320,8 @@ server.registerTool(
     const { boards: boardsForRead } = await readProject();
     const elsewhereForRead = castElsewhere(projectForRead, boardsForRead, readBoardId ?? projectForRead.activeBoardId);
     const reading = readWall(state, { elsewhere: Object.keys(elsewhereForRead) });
+    lastReading = { findings: reading.findings };
+    sinceRead.length = 0;
     const runs = describeRuns(reading, state).map((line, index) => {
       const ids = reading.runs[index]?.ids ?? [];
       return ids.length ? `${line} — ${ids.map((id) => `"${state.notes.find((note) => note.id === id)?.headline ?? id}"`).join(", ")}` : line;
@@ -1369,7 +1399,7 @@ server.registerTool(
   {
     title: "Leave a question, for now",
     description:
-      "Write the writer's word on a question the wall asks — \"leave it\" — so the reading stops asking it. Pass the question's kind as read_wall names it (sag, empty, unpaid, …) and, when that kind is asked more than once, its ids as read_wall lists them. The wall keeps the question and asks it again on its own the moment it would read differently — a card in it changes, a page moves, the median shifts — so a left question is never a dismissal; ask_again brings one back now. Only on the writer's word: never leave a question unasked.",
+      "Write the writer's word on a question the wall asks — \"leave it\" — so the reading stops asking it. Pass the question's kind as read_wall names it (sag, empty, unpaid, …) and, when that kind is asked more than once, its ids as read_wall lists them. A leave answers the reading in front of you: edits change the questions, so make the writer's changes first, read_wall, then leave what they still want left — a question that changed or went since the last reading is refused, with what it was. The wall keeps a left question and asks it again on its own the moment it would read differently — a card in it changes, a page moves, the median shifts — so a left question is never a dismissal; ask_again brings one back now. Only on the writer's word: never leave a question unasked.",
     inputSchema: { kind: z.string().min(1), ids: z.array(z.string()).optional() },
   },
   async (args) => {
@@ -1379,7 +1409,21 @@ server.registerTool(
     const matches = reading.findings.filter((finding) => finding.kind === args.kind && (!args.ids || sameList(finding.ids, args.ids)));
     if (matches.length === 0) {
       if (already.length) return ok(`Already left: [${args.kind}] ${already[0].text} It stays left until the question would read differently; ask_again brings it back.`);
-      return ok(`The wall is not asking a question of kind "${args.kind}"${args.ids ? ` about ids ${args.ids.join(", ")}` : ""}. read_wall lists the questions it asks now, each with its kind and ids.`);
+      // The reading the agent was answering, when the last read_wall had this question (round thirteen, entry 19).
+      const earlier = lastReading?.findings.find((finding) => finding.kind === args.kind && (!args.ids || sameList(finding.ids, args.ids)));
+      const now = reading.findings.filter((finding) => finding.kind === args.kind);
+      if (earlier) {
+        const since = sinceRead.length
+          ? `${sinceRead.length} change${sinceRead.length === 1 ? "" : "s"} landed since (${[...new Set(sinceRead)].join(", ")})`
+          : "the wall changed elsewhere since";
+        const state_ = now.length
+          ? `the wall now asks ${now.length === 1 ? "it differently" : `${now.length} questions of that kind`}: ${now.map((finding) => `${finding.text} (ids: ${finding.ids.join(", ")})`).join("; ")}`
+          : "the wall no longer asks it — the cards answered it";
+        return ok(
+          `Not left. When you last read the wall it asked [${earlier.kind}] ${earlier.text}${earlier.ids.length ? ` (ids: ${earlier.ids.join(", ")})` : ""}; ${since}, and ${state_}. A leave answers the reading in front of you: make the writer's edits first, read_wall, then leave what they still want left.`,
+        );
+      }
+      return ok(`The wall is not asking a question of kind "${args.kind}"${args.ids ? ` about ids ${args.ids.join(", ")}` : ""}. read_wall lists the questions it asks now, each with its kind and ids.${sinceRead.length ? ` ${sinceRead.length} change(s) landed since the last read_wall, so read it again first.` : ""}`);
     }
     if (matches.length > 1) {
       return ok(`The wall asks ${matches.length} questions of kind "${args.kind}"; pass ids to say which:\n${matches.map((finding) => `  - ${finding.text} (ids: ${finding.ids.join(", ")})`).join("\n")}`);
@@ -1643,23 +1687,19 @@ server.registerTool(
   {
     title: "Export the wall as Fountain",
     description:
-      "The open board as a Fountain screenplay: a title page (with the premise and logline in its notes), beats as sections, one scene per card in wall order — a forced heading from the card's place (or its headline), the headline as a synopsis, the cast and the fold as notes, the change line as action. Plain text a writer can open in any Fountain editor. Pass a path to write a .fountain file; otherwise the text comes back.",
+      "The open board as a Fountain screenplay: a title page (with the premise and logline in its notes), beats as sections, one scene per card in wall order — a forced heading from the card's place (or its headline), the headline as a synopsis, the cast and the fold as notes, the change line as action after the mark [Unwritten] until the scene is written. Titled for the project, a one-board film being its project. Plain text a writer can open in any Fountain editor. Pass a path to write a .fountain file; otherwise the text comes back.",
     inputSchema: { path: z.string().optional() },
   },
   async (args) => {
     const { state } = await readBoard();
     const { project } = await readProject();
     const board = project.boards.find((item) => item.id === project.activeBoardId);
-    const text = toFountain(state, {
-      title: board?.name,
-      project: project.boards.length > 1 && project.name !== "Untitled project" ? project.name : undefined,
-      premise: project.premise || undefined,
-      draftDate: new Date().toISOString(),
-    });
+    const titles = scriptTitles(project, board);
+    const text = toFountain(state, { ...titles, premise: project.premise || undefined, draftDate: new Date().toISOString() });
     if (args.path) {
       fs.mkdirSync(path.dirname(path.resolve(args.path)), { recursive: true });
       fs.writeFileSync(args.path, text);
-      return ok(`Wrote ${text.split("\n").length} lines of Fountain to ${args.path}.`);
+      return ok(`Wrote ${text.split("\n").length} lines of Fountain, titled "${titles.title}", to ${args.path}.`);
     }
     return ok(text);
   },
@@ -1670,22 +1710,19 @@ server.registerTool(
   {
     title: "Export the wall as Markdown",
     description:
-      "The open board as Markdown, for a collaborator who lives in Google Docs or the like: the board as the title (the project's name before it when the project has several boards), the premise and the logline under it, beats as second-level headings, a third-level heading per scene from its place with its scene number, the headline as a synopsis line, then the scene's text — a speech as its cue in bold with the lines under it — or, unwritten, its change line. Pass a path to write a .md file; otherwise the text comes back.",
+      "The open board as Markdown, for a collaborator who lives in Google Docs or the like: titled for the project — a one-board film is its project, and the board's name follows only when the project has several boards — the premise and the logline under it, beats as second-level headings, a third-level heading per scene from its place with its scene number, the headline as a synopsis line, then the scene's text — a speech as its cue in bold with the lines under it — or, unwritten, its change line in italics after the mark [Unwritten], so a reader can tell a placeholder from a page. Pass a path to write a .md file; otherwise the text comes back.",
     inputSchema: { path: z.string().optional() },
   },
   async (args) => {
     const { state } = await readBoard();
     const { project } = await readProject();
     const board = project.boards.find((item) => item.id === project.activeBoardId);
-    const text = toMarkdown(state, {
-      title: board?.name,
-      project: project.boards.length > 1 && project.name !== "Untitled project" ? project.name : undefined,
-      premise: project.premise || undefined,
-    });
+    const titles = scriptTitles(project, board);
+    const text = toMarkdown(state, { ...titles, premise: project.premise || undefined });
     if (args.path) {
       fs.mkdirSync(path.dirname(path.resolve(args.path)), { recursive: true });
       fs.writeFileSync(args.path, text);
-      return ok(`Wrote ${text.split("\n").length} lines of Markdown to ${path.resolve(args.path)}.`);
+      return ok(`Wrote ${text.split("\n").length} lines of Markdown, titled "${titles.title}", to ${path.resolve(args.path)}.`);
     }
     return ok(text);
   },
@@ -1696,21 +1733,19 @@ server.registerTool(
   {
     title: "Export the script as plain text",
     description:
-      "The open board's script as plain text, set as it prints: the paginator's lines at Courier's columns kept with spaces, scene numbers in both margins (the wall's order, or as locked), no page numbers. Pastes into anything and reads as a script wherever the font is monospaced. Pass a path to write a .txt file; otherwise the text comes back.",
+      "The open board's script as plain text, set as it prints: the paginator's lines at Courier's columns kept with spaces, scene numbers in both margins (the wall's order, or as locked), no page numbers, an unwritten scene's change line as action after the mark [Unwritten]. Titled for the project, a one-board film being its project. Pastes into anything and reads as a script wherever the font is monospaced. Pass a path to write a .txt file; otherwise the text comes back.",
     inputSchema: { path: z.string().optional() },
   },
   async (args) => {
     const { state } = await readBoard();
     const { project } = await readProject();
     const board = project.boards.find((item) => item.id === project.activeBoardId);
-    const text = toPlainText(state, {
-      title: board?.name,
-      project: project.boards.length > 1 && project.name !== "Untitled project" ? project.name : undefined,
-    });
+    const titles = scriptTitles(project, board);
+    const text = toPlainText(state, titles);
     if (args.path) {
       fs.mkdirSync(path.dirname(path.resolve(args.path)), { recursive: true });
       fs.writeFileSync(args.path, text);
-      return ok(`Wrote ${text.split("\n").length} lines of plain text to ${path.resolve(args.path)}.`);
+      return ok(`Wrote ${text.split("\n").length} lines of plain text, titled "${titles.title}", to ${path.resolve(args.path)}.`);
     }
     return ok(text);
   },
@@ -1853,18 +1888,19 @@ 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 when unwritten, and a title page. 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 for the project (a one-board film is its project). Pass a path to write the file; otherwise the XML comes back.",
     inputSchema: { path: z.string().optional() },
   },
   async (args) => {
     const { state } = await readBoard();
     const { project } = await readProject();
     const board = project.boards.find((item) => item.id === project.activeBoardId);
-    const xml = toFdx(state, { title: board?.name, project: project.boards.length > 1 ? project.name : undefined, draftDate: new Date().toISOString() });
+    const titles = scriptTitles(project, board);
+    const xml = toFdx(state, { ...titles, draftDate: new Date().toISOString() });
     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) to ${args.path}.`);
+      return ok(`Wrote a Final Draft file with ${state.notes.length} scene(s), titled "${titles.title}", to ${args.path}.`);
     }
     return ok(xml);
   },
@@ -2505,6 +2541,29 @@ server.registerTool(
   },
 );
 
+server.registerTool(
+  "add_to_group",
+  {
+    title: "Add cards to a group",
+    description:
+      "Put one or more cards into a group that already exists — the agent's side of dragging a card into a frame. The frame reaches the cards where they are; nothing moves. A card is in one group at a time, so it leaves any other frame on the way, and a frame left with one card dissolves. Needs the group's id and the cards' ids from list_board; organize keeps a group together as a block.",
+    inputSchema: { id: z.string(), noteIds: z.array(z.string()).min(1) },
+  },
+  async (args) => {
+    const { state, changed, result, live } = await commit({ type: "add_to_group", id: args.id, noteIds: args.noteIds });
+    if (!changed) {
+      if (!state.groups.some((group) => group.id === args.id)) return ok(`No group with id ${args.id}. Call list_board for the real ids; create_group makes a new frame.`);
+      const missing = args.noteIds.filter((id) => !state.notes.some((note) => note.id === id));
+      return ok(missing.length ? `Nothing added: not on the board — ${missing.join(", ")}. Call list_board to check the ids.` : "Nothing added: those cards are in that group already.");
+    }
+    const names = result.added.map((id) => `"${state.notes.find((note) => note.id === id)?.headline ?? id}"`).join(", ");
+    const left = result.left
+      .map((group) => (group.dissolved ? ` "${group.title}" dissolved on the way: a frame needs two cards.` : ` Left "${group.title}", which keeps ${group.remaining} card${group.remaining === 1 ? "" : "s"}.`))
+      .join("");
+    return ok(`Added ${names} to "${result.group.title}", which now holds ${result.group.noteIds.length} cards${where(live)}. The frame reaches them where they are; organize lays the group out as a block.${left}`, result);
+  },
+);
+
 server.registerTool(
   "rename_group",
   {

package/src/board/fdx.js

@@ -12,7 +12,7 @@
 
 import { parseScene, TRANSITION } from "./paginate.js";
 import { readingOrder } from "./readWall.js";
-import { sceneHeading } from "./fountain.js";
+import { sceneHeading, standInFor } from "./fountain.js";
 import { sceneNumbers } from "./numbering.js";
 
 function escapeXml(text) {
@@ -60,7 +60,8 @@ export function toFdx(state, options = {}) {
       "<Text>",
       `<SceneProperties Length="" Page="" Title="${escapeXml(note.headline)}" />\n      <Text>`,
     );
-    const elements = parseScene(note.text && note.text.trim() ? note.text : note.change || "");
+    // 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);

package/src/board/fountain.d.ts

@@ -3,6 +3,10 @@
 import type { BoardNote, BoardState } from "./reducer";
 
 export declare function sceneHeading(note: BoardNote): 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;
+export declare function unmark(text: string | null | undefined): { text: string; marked: boolean };
 
 export declare function titlePage(titles: {
   title?: string;

package/src/board/fountain.js

@@ -26,6 +26,28 @@ export function sceneHeading(note) {
   return `.${upper(words)}`;
 }
 
+/**
+ * The mark every export sets before an unwritten scene's change line, so a
+ * reader can tell a placeholder from a page (round thirteen, entry 27). One
+ * mark, the same words in Markdown, plain text, Fountain and Final Draft;
+ * coming back in, a body that is the mark and the card's change line is
+ * still unwritten.
+ */
+export const UNWRITTEN_MARK = "[Unwritten]";
+
+/** What stands in for an unwritten scene's body: the mark, then the change line. */
+export function standInFor(note) {
+  const change = (note.change ?? "").trim();
+  return change ? `${UNWRITTEN_MARK} ${change}` : UNWRITTEN_MARK;
+}
+
+/** A body without its mark, and whether it carried one. */
+export function unmark(text) {
+  const trimmed = (text ?? "").trim();
+  if (!trimmed.startsWith(UNWRITTEN_MARK)) return { text: trimmed, marked: false };
+  return { text: trimmed.slice(UNWRITTEN_MARK.length).trim(), marked: true };
+}
+
 /** The title page block. `titles` is what the writer would put above the script. */
 export function titlePage({ title, credit, author, draftDate, notes }) {
   const lines = [];
@@ -89,8 +111,9 @@ export function toFountain(state, options = {}) {
       body.push(`[[${marks.join(" · ")}]]`);
       body.push("");
     }
-    // The scene's text when it is written; the change line stands in until then.
-    body.push(note.text && note.text.trim() ? note.text.trim() : note.change || "");
+    // The scene's text when it is written; the change line stands in until
+    // then, marked so a printed page never passes a placeholder off as a scene.
+    body.push(note.text && note.text.trim() ? note.text.trim() : standInFor(note));
     body.push("");
   }
 
@@ -206,9 +229,10 @@ export function mergeFountain(state, parsed) {
     if (found) {
       used.add(found.id);
       cursor = order.indexOf(found) + 1;
-      // A scene whose body is the card's own change line is the export of an
-      // unwritten card coming back: still unwritten, not a page.
-      const standIn = !(found.text ?? "").trim() && sameWords(scene.text, found.change ?? "");
+      // A scene whose body is the mark, or the card's own change line, is the
+      // export of an unwritten card coming back: still unwritten, not a page.
+      const body = unmark(scene.text);
+      const standIn = !(found.text ?? "").trim() && (body.marked || sameWords(body.text, found.change ?? ""));
       if ((found.text ?? "") !== scene.text && !standIn) {
         commands.push({ type: "set_text", id: found.id, text: scene.text });
       }
@@ -220,13 +244,15 @@ export function mergeFountain(state, parsed) {
     const headline = scene.synopsis || titleCase(scene.heading);
     const isPlace = scene.forced && Boolean(scene.synopsis);
     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);
     commands.push({
       type: "create_note",
       id,
       headline,
-      change: scene.text ? firstSentence(scene.text) : "What changes?",
+      change: body.marked ? body.text || "What changes?" : scene.text ? firstSentence(scene.text) : "What changes?",
       location: isPlace ? titleCase(scene.heading) : "",
-      text: scene.text,
+      text: body.marked ? "" : scene.text,
       x: anchor ? anchor.x + 40 : 140,
       y: anchor ? anchor.y + 40 : 140,
     });

package/src/board/markdown.js

@@ -18,7 +18,7 @@
 // monospaced.
 
 import { readingOrder } from "./readWall.js";
-import { sceneHeading } from "./fountain.js";
+import { sceneHeading, standInFor } from "./fountain.js";
 import { paginate, parseScene, WIDTH } from "./paginate.js";
 import { sceneNumbers } from "./numbering.js";
 
@@ -79,7 +79,9 @@ export function toMarkdown(state, options = {}) {
     out.push(`### ${numbers.get(note.id) ?? ""} · ${heading}`.replace(/^###  · /, "### "), "");
     if (note.headline && upper(note.headline) !== heading) out.push(`*${note.headline.trim()}*`, "");
     if (note.text && note.text.trim()) out.push(...sceneMarkdown(note.text));
-    else if (note.change && note.change.trim()) out.push(note.change.trim(), "");
+    // 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)}*`, "");
   }
   return `${out.join("\n").trimEnd()}\n`;
 }
@@ -156,7 +158,7 @@ export function toPlainText(state, options = {}) {
       id: note.id,
       heading: sceneHeading(note).slice(1),
       text: note.text,
-      change: note.change,
+      change: standInFor(note),
       written: Boolean(note.text && note.text.trim()),
       number: numbers.get(note.id) ?? undefined,
     })),

package/src/board/project.d.ts

@@ -67,6 +67,8 @@ export declare function setActiveBoard(project: ProjectRecord, id: string, now?:
 export declare function renameProject(project: ProjectRecord, name: string, now?: string): ProjectRecord;
 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 findBoard(project: ProjectRecord, key: string): BoardMeta | null;
 export declare function reidentifyProject(
   project: ProjectRecord,

package/src/board/project.js

@@ -289,6 +289,21 @@ export function setPremise(project, premise, now = nowIso()) {
   return touch(project, { premise: next }, now);
 }
 
+/**
+ * What a script going out is called (round thirteen, entry 26): a named
+ * project is the title — a one-board film is its project — with the board's
+ * name beside it only when the project has several boards; an untitled
+ * project's board is the title. One rule for Markdown, plain text, Fountain
+ * and Final Draft, through every door.
+ */
+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 };
+  return { title: project.name };
+}
+
 export function boardById(project, id) {
   return project.boards.find((board) => board.id === id) ?? null;
 }

package/src/board/reducer.d.ts

@@ -139,7 +139,7 @@ export declare function sameName(a: string, b: string): boolean;
 export type Command =
   | { type: "set_logline"; logline: string }
   | { type: "set_rank"; ids: string[]; rank: NoteRank }
-  | { type: "set_length"; ids: string[]; lengthEighths: number }
+  | { type: "set_length"; ids: string[]; lengthEighths: number | null }
   | { type: "set_target"; targetEighths: number }
   | {
       type: "create_note";
@@ -167,6 +167,7 @@ export type Command =
   | { type: "settle_note"; id: string }
   | { type: "create_group"; title?: string; noteIds: string[] }
   | { type: "ungroup"; id: string }
+  | { type: "add_to_group"; id: string; noteIds: string[] }
   | { type: "rename_group"; id: string; title: string }
   | { type: "create_arrow"; from: string; to: string; kind?: ArrowKind }
   | { type: "delete_arrow"; id: string }

package/src/board/reducer.js

@@ -497,11 +497,12 @@ export function applyCommand(state, command, now = nowIso()) {
     case "set_length": {
       const ids = new Set(command.ids);
       if (ids.size === 0) return { state, changed: false };
-      const lengthEighths = clampEighths(
-        command.lengthEighths,
-        DEFAULT_NOTE_EIGHTHS,
-        MAX_NOTE_EIGHTHS,
-      );
+      // null unsizes: the card claims nothing again and reads as about a page
+      // (round thirteen, entry 16: there was no way back from a length).
+      const lengthEighths =
+        command.lengthEighths === null
+          ? null
+          : clampEighths(command.lengthEighths, DEFAULT_NOTE_EIGHTHS, MAX_NOTE_EIGHTHS);
       const touched = [];
       const notes = state.notes.map((note) => {
         if (!ids.has(note.id) || note.lengthEighths === lengthEighths) return note;
@@ -575,23 +576,32 @@ export function applyCommand(state, command, now = nowIso()) {
     }
 
     case "delete_note": {
-      if (!state.notes.some((note) => note.id === command.id)) {
-        return { state, changed: false };
-      }
+      const gone = state.notes.find((note) => note.id === command.id);
+      if (!gone) return { state, changed: false };
+      const headlineOf = (id) => state.notes.find((note) => note.id === id)?.headline ?? id;
       const notes = state.notes.filter((note) => note.id !== command.id);
-      const arrows = state.arrows.filter(
-        (arrow) => arrow.from !== command.id && arrow.to !== command.id,
-      );
+      const taken = state.arrows.filter((arrow) => arrow.from === command.id || arrow.to === command.id);
+      const arrows = state.arrows.filter((arrow) => !taken.includes(arrow));
+      const left = [];
       const groups = pruneGroups(
-        state.groups.map((group) => ({
-          ...group,
-          noteIds: group.noteIds.filter((id) => id !== command.id),
-        })),
+        state.groups.map((group) => {
+          if (!group.noteIds.includes(command.id)) return group;
+          const noteIds = group.noteIds.filter((id) => id !== command.id);
+          left.push({ id: group.id, title: group.title, remaining: noteIds.length, dissolved: noteIds.length < 2 });
+          return { ...group, noteIds };
+        }),
       );
+      // The result says what went with the card, so a door can say it too
+      // (round thirteen, entry 17: "Deleted card." and nothing of the arrows).
       return {
         state: { ...state, notes, arrows, groups },
         changed: true,
-        result: { id: command.id },
+        result: {
+          id: command.id,
+          headline: gone.headline,
+          arrows: taken.map((arrow) => ({ ...arrow, fromHeadline: headlineOf(arrow.from), toHeadline: headlineOf(arrow.to) })),
+          groups: left,
+        },
       };
     }
 
@@ -672,6 +682,34 @@ export function applyCommand(state, command, now = nowIso()) {
       };
     }
 
+    case "add_to_group": {
+      // The agent's twin of dragging a card into a frame (round thirteen,
+      // entry 18). Membership only: the frame reaches the card where it is,
+      // and a card leaves any other group on the way, as create_group does.
+      const group = state.groups.find((item) => item.id === command.id);
+      if (!group) return { state, changed: false };
+      const joining = command.noteIds.filter(
+        (id, index) =>
+          command.noteIds.indexOf(id) === index &&
+          !group.noteIds.includes(id) &&
+          state.notes.some((note) => note.id === id),
+      );
+      if (joining.length === 0) return { state, changed: false };
+      const idSet = new Set(joining);
+      const left = [];
+      const groups = pruneGroups(
+        state.groups.map((existing) => {
+          if (existing.id === group.id) return { ...existing, noteIds: [...existing.noteIds, ...joining] };
+          if (!existing.noteIds.some((id) => idSet.has(id))) return existing;
+          const noteIds = existing.noteIds.filter((id) => !idSet.has(id));
+          left.push({ id: existing.id, title: existing.title, remaining: noteIds.length, dissolved: noteIds.length < 2 });
+          return { ...existing, noteIds };
+        }),
+      );
+      const joined = groups.find((item) => item.id === group.id);
+      return { state: { ...state, groups }, changed: true, result: { group: joined, added: joining, left } };
+    }
+
     case "rename_group": {
       let renamed = false;
       const groups = state.groups.map((group) => {