plotcoder-board 0.1.25 → 0.1.26

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. Eighty-one tools: reading (`list_board`, `read_wall`, `read_pages`, `read_character`, `page_count`, `list_words`, `list_workflows`, `segment_brief`, `compare_structure`); the card, cast, place and when (`set_when`), group (with `add_to_group`) and arrow verbs, `set_logline`, `set_target`, `set_rank`, `set_plant` (with `later` and `at`) and `set_payoff`, `write_scene`, `edit_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. Eighty-two tools: reading (`list_board`, `read_wall`, `read_pages`, `read_character`, `page_count`, `list_words`, `list_workflows`, `segment_brief`, `compare_structure`); the card, cast, place and when (`set_when`), group (with `add_to_group`) and arrow verbs, `set_logline`, `set_target`, `set_rank`, `set_open` (a card the writer has not decided), `set_plant` (with `later` and `at`) and `set_payoff`, `write_scene`, `edit_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.
@@ -100,4 +100,4 @@ next round into a test of `claim_account` instead of the door it meant to test.
 
 ## Status
 
-Version 0.1.25. 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.26. 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.25",
+  "version": "0.1.26",
   "type": "module",
   "scripts": {
     "dev": "vite",

package/scripts/plotcoder-mcp-server.mjs

@@ -1039,11 +1039,12 @@ function summarize(state) {
       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}` : "";
       const when = note.when ? `, when: ${note.when}` : "";
+      const openWord = note.open ? `, open: ${note.open}` : "";
       const count = formatPages(noteEighths(note));
       // A written card's estimate is kept underneath for when the text goes; say it, or it is invisible (round sixteen, entry 44).
       const underneath = isMeasured(note) && note.lengthEighths !== null ? `; the writer's estimate underneath: ${formatPages(note.lengthEighths)}` : "";
       const pages = isMeasured(note) ? `${count} ${count === "1" ? "page" : "pages"}, written${underneath}` : note.lengthEighths === null ? "about a page, unsized" : `${count} ${count === "1" ? "page" : "pages"}`;
-      return `  - ${note.id} [${note.rank ?? "scene"}, ${pages}${who}${place}${when}${plant}${pays}${revised}] — "${note.headline}" (${note.color}) at ${Math.round(note.x)},${Math.round(note.y)}`;
+      return `  - ${note.id} [${note.rank ?? "scene"}, ${pages}${who}${place}${when}${openWord}${plant}${pays}${revised}] — "${note.headline}" (${note.color}) at ${Math.round(note.x)},${Math.round(note.y)}`;
     })
     .join("\n");
   const cast = state.characters
@@ -1311,6 +1312,7 @@ server.registerTool(
       before: z.string().optional().describe("Or before this card (id or headline)."),
       location: z.string().optional(),
       when: z.string().optional().describe('When the scene happens, as the writer says it — "night", "day four, dawn" — printed after the place on the scene heading.'),
+      open: z.string().optional().describe("The writer's words for what is not decided about this card (R59) — \"where, and whether Ruth is there\" — so the card is born open: the reading lists it and asks nothing else of it until the words are cleared."),
       characters: z.array(z.string().min(1)).optional(),
       x: z.number().optional(),
       y: z.number().optional(),
@@ -1345,6 +1347,7 @@ server.registerTool(
         plants: args.plants,
         location: args.location,
         when: args.when,
+        open: args.open,
         x: landing.x,
         y: landing.y,
       }).result;
@@ -1381,6 +1384,7 @@ server.registerTool(
       result?.plants ? "corner folded" : null,
       result?.location ? `at ${result.location}` : `no place yet${once("place", " (location here, or set_location)")}`,
       result?.when ? `when: ${result.when}` : null,
+      result?.open ? `open: "${result.open}" (listed, not asked about)` : null,
     ].filter(Boolean).join(", ");
     // Where it landed matters only until the tidy, so the reply says the rule once and never the coordinates (round fourteen, entry 11).
     const placed = beside
@@ -1551,6 +1555,9 @@ server.registerTool(
         : [reading.paidBy.length ? "  (no setup arrow on this board; what pays off a fold of another board is listed below)" : "  (no arrow is marked as a setup)"]),
       ...reading.later.map((item) => `  - "${state.notes.find((note) => note.id === item.id)?.headline ?? item.id}" is folded and pays off later, on "${boardById(projectForRead, item.boardId)?.name ?? item.boardId}"${item.noteId ? `, at ${episodeLabel(projectForRead, boardsNow, item.boardId, item.noteId)} "${boardsNow[item.boardId]?.notes?.find((note) => note.id === item.noteId)?.headline ?? item.noteId}"` : " — no scene there claims it yet"}`),
       ...reading.paidBy.map((item) => `  - "${state.notes.find((note) => note.id === item.id)?.headline ?? item.id}" pays off "${item.fromHeadline}" from "${item.fromBoardName}" (${episodeLabel(projectForRead, boardsNow, item.fromBoardId, item.fromNoteId)}), one board earlier`),
+      ...(reading.open.length
+        ? ["open, by the writer's word (listed, not asked about while the words stand; set_open with \"\" closes):", ...reading.open.map((item) => `  - "${state.notes.find((note) => note.id === item.id)?.headline ?? item.id}" — ${item.words}`)]
+        : []),
       "questions the wall raises:",
       ...(reading.findings.length
         ? reading.findings.map((finding) => `  - [${finding.kind}] ${finding.text}${finding.ids.length ? ` (ids: ${finding.ids.join(", ")})` : ""}`)
@@ -1568,7 +1575,7 @@ server.registerTool(
         const counts = new Map();
         for (const finding of asked) counts.set(finding.kind, (counts.get(finding.kind) ?? 0) + 1);
         return `asking ${asked.length} question${asked.length === 1 ? "" : "s"} of ${counts.size} kind${counts.size === 1 ? "" : "s"}: ${[...counts.entries()].map(([kind, n]) => (n > 1 ? `${kind} ×${n}` : kind)).join(", ")}${held}`;
-      })()}${reading.left.length ? `; left by the writer, so not clean: ${[...new Set(reading.left.map((finding) => finding.kind))].map((kind) => `[${kind}]`).join(" ")}` : ""}; checked and clean: ${CHECKS.filter((kind) => !reading.findings.some((finding) => finding.kind === kind) && !reading.left.some((finding) => finding.kind === kind)).map((kind) => {
+      })()}${reading.left.length ? `; left by the writer, so not clean: ${[...new Set(reading.left.map((finding) => finding.kind))].map((kind) => `[${kind}]`).join(" ")}` : ""}${reading.open.length ? `; ${reading.open.length} card${reading.open.length === 1 ? "" : "s"} open by the writer's word, not asked` : ""}; checked and clean: ${CHECKS.filter((kind) => !reading.findings.some((finding) => finding.kind === kind) && !reading.left.some((finding) => finding.kind === kind)).map((kind) => {
         if (kind === "unlinked" && state.arrows.length === 0) return "no card without an arrow (not asked until half the cards are wired: no arrows yet)";
         if (kind === "unlinked") {
           const linked = new Set(state.arrows.flatMap((arrow) => [arrow.from, arrow.to]));
@@ -2663,6 +2670,33 @@ server.registerTool(
   },
 );
 
+// The open card (R59): the writer's word that a card is not decided. The
+// per-card twin of leave_question — that one leaves a question, this one
+// leaves a card.
+server.registerTool(
+  "set_open",
+  {
+    title: "Leave a card open",
+    description:
+      "Mark one or more cards open, with the writer's words for what is not decided — \"where, and whether Ruth is there\", \"the buyer\". An open card is listed by read_wall under its own head and asked nothing else of while the words stand: not its place, not its change line, not its arrows. It is still counted, in the order, and a page. open \"\" closes the card and its questions come back on their own. Only on the writer's word — a card is open because they said so, never because you could not decide; where the notes have two versions, ask, and if they say leave it, this is how.",
+    inputSchema: { ids: z.array(z.string()).min(1), open: z.string() },
+  },
+  async (args) => {
+    const { state, changed, result, live } = await commit({ type: "set_open", ids: args.ids, open: args.open });
+    if (!changed) {
+      const missing = args.ids.filter((id) => !state.notes.some((note) => note.id === id));
+      return ok(missing.length ? `No card with id ${missing.join(", ")}. Call list_board for the real ids.` : `Nothing changed: ${args.ids.length === 1 ? "the card already says that" : "those cards already say that"}.`);
+    }
+    const words = result[0]?.open ?? "";
+    return ok(
+      words
+        ? `${result.length} card(s) open: "${words}"${where(live)}. The reading lists ${result.length === 1 ? "it" : "them"} under "open, by the writer's word" and asks nothing else of ${result.length === 1 ? "it" : "them"} while the words stand; the card wears the words on its edge. set_open with "" closes it.`
+        : `${result.length} card(s) closed${where(live)}: decided, so the wall's questions about ${result.length === 1 ? "it" : "them"} come back on their own.`,
+      result,
+    );
+  },
+);
+
 server.registerTool(
   "set_plant",
   {

package/src/board/readWall.d.ts

@@ -67,6 +67,8 @@ export type WallReading = {
   payoffs: Record<string, string[]>;
   /** Folded cards that pay off on another board of the project (R50): the card, the board, and the scene there that claims it (R58) or null while the board is a promise. */
   later: { id: string; boardId: string; noteId: string | null }[];
+  /** Open cards (R59): the writer's words for what is not decided, in story order; not asked about while they stand. */
+  open: Array<{ id: string; words: string }>;
   /** Cards here that pay off a fold of another board (R58), composed by the door from the project. */
   paidBy: Array<{ id: string; fromBoardId: string; fromBoardName: string; fromNoteId: string; fromHeadline: string; fromColor: string }>;
   /** The questions the wall asks now. A left one (R53) is not here while its words hold. */

package/src/board/readWall.js

@@ -197,6 +197,10 @@ export function readWall(state, options = {}) {
   if (from !== null && cards > 0) runs.push({ from, to: null, eighths, cards, ids });
 
   const findings = [];
+  // Open cards (R59): the writer's word that a card is not decided. Listed,
+  // and asked nothing else while the words stand — the card's own "leave it".
+  const openIds = new Set(order.filter((note) => (note.open ?? "").trim()).map((note) => note.id));
+  const askable = (note) => !openIds.has(note.id);
   const byId = new Map(state.notes.map((note) => [note.id, note]));
   const headline = (id) => (id ? byId.get(id)?.headline ?? id : null);
   const position = new Map(order.map((note, index) => [note.id, index]));
@@ -282,7 +286,7 @@ export function readWall(state, options = {}) {
   // A card that says no place, once the writer has started placing cards.
   // One question however many there are; a wall with no places at all is a
   // wall the writer has not placed yet, and is not asked.
-  const unplaced = order.filter((note) => !(note.location ?? "").trim());
+  const unplaced = order.filter((note) => askable(note) && !(note.location ?? "").trim());
   if (unplaced.length > 0 && unplaced.length < order.length) {
     findings.push({
       kind: "unplaced",
@@ -296,6 +300,7 @@ export function readWall(state, options = {}) {
 
   // A card that has not earned its place yet.
   for (const note of order) {
+    if (!askable(note)) continue;
     const change = (note.change ?? "").trim();
     const title = (note.headline ?? "").trim();
     if (title === "" || title === PLACEHOLDER_HEADLINE) {
@@ -320,7 +325,7 @@ export function readWall(state, options = {}) {
     linked.add(arrow.to);
   }
   if (state.notes.length > 0 && linked.size * 2 >= state.notes.length) {
-    const loose = order.filter((note) => !linked.has(note.id));
+    const loose = order.filter((note) => askable(note) && !linked.has(note.id));
     if (loose.length > 0) {
       findings.push({
         kind: "unlinked",
@@ -433,7 +438,7 @@ export function readWall(state, options = {}) {
   // A card with nobody in it, once the wall has a cast (round seventeen,
   // entry 28): a scene nobody is in passed every check.
   if ((state.characters ?? []).length > 0) {
-    const empty = order.filter((note) => !(note.characterIds ?? []).length);
+    const empty = order.filter((note) => askable(note) && !(note.characterIds ?? []).length);
     if (empty.length) {
       findings.push({
         kind: "nobody",
@@ -499,7 +504,10 @@ export function readWall(state, options = {}) {
   // it is a new question and is asked. The kernel never decides this; the
   // reading does, on every read.
   const left = [];
+  // A question whose every card is open is not asked (R59): the writer's word covers it.
+  const openCards = openIds.size ? findings.filter((finding) => finding.ids.some((id) => byId.has(id)) && finding.ids.filter((id) => byId.has(id)).every((id) => openIds.has(id))) : [];
   const asked = findings.filter((finding) => {
+    if (openCards.includes(finding)) return false;
     const entry = (state.left ?? []).find(
       (item) => item.kind === finding.kind && sameList(item.ids, finding.ids) && item.text === finding.text,
     );
@@ -516,6 +524,7 @@ export function readWall(state, options = {}) {
     payoffs,
     later,
     paidBy: paidHere,
+    open: order.filter((note) => openIds.has(note.id)).map((note) => ({ id: note.id, words: note.open.trim() })),
     findings: asked,
     left,
   };

package/src/board/reducer.d.ts

@@ -83,6 +83,8 @@ export type BoardNote = {
   payoffBoardId: string | null;
   /** The scene on that board that pays it off (R58), or null while the board is only a promise. */
   payoffNoteId: string | null;
+  /** The writer's words for what is not decided about this card (R59), or empty: the reading lists an open card and asks nothing else of it. */
+  open: string;
   /** Where the scene happens (R37): a phrase in the writer's words; empty until set. */
   location: string;
   /** When the scene happens, as the writer says it — "night", "day four, dawn" — printed after the place on the heading (R55). Empty when unsaid. */
@@ -162,6 +164,7 @@ export type Command =
       plants?: boolean;
       location?: string;
       when?: string;
+      open?: string;
       text?: string;
     }
   | { type: "update_note"; id: string; headline?: string; change?: string; location?: string; when?: string }
@@ -186,6 +189,7 @@ export type Command =
   | ({ type: "update_character"; id: string } & Partial<Record<CharacterField, string>>)
   | { type: "set_cast"; ids: string[]; characterIds: string[] }
   | { type: "set_plant"; ids: string[]; plants: boolean }
+  | { type: "set_open"; ids: string[]; open: string }
   | { type: "set_payoff_board"; ids: string[]; boardId: string | null; noteId?: string | null }
   | { type: "set_location"; ids: string[]; location: string }
   | { type: "set_when"; ids: string[]; when: string }

package/src/board/reducer.js

@@ -253,6 +253,10 @@ export function seedState(now = nowIso()) {
     // does (R58); null while the board is a promise.
     payoffBoardId: null,
     payoffNoteId: null,
+    // Open: the writer's words for what is not decided about this card, or
+    // nothing (R59). While they stand the reading lists the card and asks
+    // nothing else of it.
+    open: "",
     createdAt: now,
     updatedAt: now,
   });
@@ -350,6 +354,8 @@ export function normalizeState(value) {
     const payoffBoardId = plants && typeof note?.payoffBoardId === "string" && note.payoffBoardId ? note.payoffBoardId : null;
     // Cards written before R58 name a board and no scene on it.
     const payoffNoteId = payoffBoardId && typeof note?.payoffNoteId === "string" && note.payoffNoteId ? note.payoffNoteId : null;
+    // Cards written before R59 are not open; a card claims to be decided until the writer says otherwise.
+    const open = typeof note?.open === "string" ? note.open : "";
     // Cards written before R37 have no place; a scene is nowhere until it is.
     const location = typeof note?.location === "string" ? note.location : "";
     // Cards written before R55 have no when; a scene is at no time until it is.
@@ -365,6 +371,7 @@ export function normalizeState(value) {
       note.plants === plants &&
       note.payoffBoardId === payoffBoardId &&
       note.payoffNoteId === payoffNoteId &&
+      note.open === open &&
       note.location === location &&
       note.when === when &&
       note.text === text
@@ -372,7 +379,7 @@ export function normalizeState(value) {
       return note;
     }
     patched = true;
-    return { ...note, rank, lengthEighths, characterIds, plants, payoffBoardId, payoffNoteId, location, when, text };
+    return { ...note, rank, lengthEighths, characterIds, plants, payoffBoardId, payoffNoteId, open, location, when, text };
   });
 
   // Boards written before the production half (Roadmap 2, item 8) have no
@@ -423,6 +430,11 @@ function bump(note, patch, now) {
   return { ...note, ...patch, updatedAt: now };
 }
 
+/** The writer's words for what is open about a card, one line, spaces collapsed; empty closes it (R59). */
+function cleanOpen(value) {
+  return typeof value === "string" ? value.trim().replace(/\s+/g, " ") : "";
+}
+
 /** A when as the writer typed it, one line, spaces collapsed. */
 function cleanWhen(value) {
   return typeof value === "string" ? value.trim().replace(/\s+/g, " ") : "";
@@ -459,6 +471,7 @@ export function applyCommand(state, command, now = nowIso()) {
         plants: command.plants === true,
         payoffBoardId: null,
         payoffNoteId: null,
+        open: cleanOpen(command.open),
         location: cleanPlace(command.location),
         when: cleanWhen(command.when),
         text: typeof command.text === "string" ? command.text : "",
@@ -917,6 +930,7 @@ export function applyCommand(state, command, now = nowIso()) {
         plants: false,
         payoffBoardId: null,
         payoffNoteId: null,
+        open: "",
         location: "",
         when: "",
         text: "",
@@ -1037,6 +1051,23 @@ export function applyCommand(state, command, now = nowIso()) {
       return { state: { ...state, notes }, changed: true, result: touched };
     }
 
+    // Leave a card open (R59): the writer's words for what is not decided,
+    // or nothing. A claim about the card, like rank: it never moves it.
+    case "set_open": {
+      const ids = new Set(command.ids);
+      if (ids.size === 0) return { state, changed: false };
+      const open = cleanOpen(command.open);
+      const touched = [];
+      const notes = state.notes.map((note) => {
+        if (!ids.has(note.id) || (note.open ?? "") === open) return note;
+        const next = bump(note, { open }, now);
+        touched.push(next);
+        return next;
+      });
+      if (touched.length === 0) return { state, changed: false };
+      return { state: { ...state, notes }, changed: true, result: touched };
+    }
+
     // Fold the corner (R31): this card plants something. A claim about the
     // card, like rank, so it never moves it and never touches its arrows.
     case "set_plant": {

package/src/board/words.js

@@ -63,6 +63,11 @@ export const WORD_GROUPS = [
         sentence: "The second line. If nothing is different after the scene, the scene is usually decoration.",
         target: "change",
       },
+      {
+        id: "open",
+        name: "Open",
+        sentence: "A card the writer has not decided, in their words on its edge: the reading lists it and asks nothing else of it until the words are cleared.",
+      },
       {
         id: "corner",
         name: "The folded corner",