plotcoder-board 0.1.7 → 0.1.9

package/package.json

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

package/scripts/plotcoder-mcp-server.mjs

@@ -29,6 +29,8 @@ import {
   formatPages,
   isBoardState,
   isMeasured,
+  NOTE_HEIGHT,
+  NOTE_WIDTH,
   DEFAULT_TARGET_EIGHTHS,
   normalizeState,
   noteEighths,
@@ -49,7 +51,7 @@ import { segmentBrief, WORKFLOWS } from "../src/board/workflows.js";
 import { DEFAULT_REMINDERS, titleFromBody } from "../src/board/reminders.js";
 import crypto from "node:crypto";
 import { describeRuns, describeSetups, readWall } from "../src/board/readWall.js";
-import { organizePoses } from "../src/board/organize.js";
+import { GAP, ROW_WIDTH, organizePoses } from "../src/board/organize.js";
 import {
   addBoard,
   addStructure,
@@ -737,7 +739,16 @@ async function commit(command) {
 }
 
 /** Said once per session: that cards stack until organize (round seven, finding 11). */
-let saidStack = false;
+/** Where a new card lands when the agent gives no position: after the last card in reading order, wrapping five wide, so cards never stack (round eleven, finding 14). */
+function nextPlace(state) {
+  const order = readingOrder(state.notes);
+  const last = order[order.length - 1];
+  if (!last) return { x: 140, y: 140 };
+  const originX = Math.min(...state.notes.map((note) => note.x));
+  const x = last.x + NOTE_WIDTH + GAP;
+  if (x + NOTE_WIDTH > originX + ROW_WIDTH) return { x: originX, y: last.y + NOTE_HEIGHT + GAP };
+  return { x, y: last.y };
+}
 
 /** Which door a read came through, for the head of a reply: the account as whom, the open app, or the file at which path. */
 function door(live, base = null) {
@@ -857,7 +868,7 @@ function summarize(state) {
     `notes: ${state.notes.length}, groups: ${state.groups.length}, arrows: ${state.arrows.length}, cast: ${state.characters.length}`,
     "cast:",
     cast || "  (no one yet — add_character to start the roster)",
-    "places (each distinct phrase is one place; near-matches sit side by side):",
+    "places (each phrase is its own place, and the app relates none of them — if two are one place, set_location them the same):",
     places || "  (no card says where it happens yet)",
     "cards:",
     notes || "  (no cards)",
@@ -884,15 +895,23 @@ const server = new McpServer({ name: "plotcoder-board", version: "0.1.0" });
 
 // A door's answer is a reply, not an error: a shut account door, or an
 // account with no project yet, says so in words from every tool alike.
+// Tool calls run one at a time. Every tool reads the board, decides, and
+// writes it back; two calls interleaving at those awaits would each read the
+// same board and the second would write over the first — thirteen parallel
+// create_note calls naming Nessa made thirteen Nessas in prospect (round
+// eleven, finding 22). One lane, in the order the calls arrive.
 const registerTool = server.registerTool.bind(server);
+let lane = Promise.resolve();
 server.registerTool = (name, config, handler) =>
-  registerTool(name, config, async (...args) => {
-    try {
-      return await handler(...args);
-    } catch (error) {
-      if (error instanceof DoorReply) return ok(error.message);
-      throw error;
-    }
+  registerTool(name, config, (...args) => {
+    const turn = lane.then(() =>
+      handler(...args).catch((error) => {
+        if (error instanceof DoorReply) return ok(error.message);
+        throw error;
+      }),
+    );
+    lane = turn.catch(() => undefined);
+    return turn;
   });
 
 server.registerTool(
@@ -1028,6 +1047,7 @@ server.registerTool(
     },
   },
   async (args) => {
+    const landing = args.x === undefined && args.y === undefined ? nextPlace((await readBoard()).state) : { x: args.x, y: args.y };
     let { result, live } = await commit({
       type: "create_note",
       headline: args.headline,
@@ -1041,8 +1061,8 @@ server.registerTool(
       lengthEighths: args.pages === undefined ? undefined : toEighths(args.pages),
       plants: args.plants,
       location: args.location,
-      x: args.x,
-      y: args.y,
+      x: landing.x,
+      y: landing.y,
     });
     let castLine = "";
     if (args.characters && args.characters.length && result?.id) {
@@ -1074,8 +1094,7 @@ server.registerTool(
       result?.plants ? "corner folded" : null,
       result?.location ? `at ${result.location}` : "no place yet (location here, or set_location)",
     ].filter(Boolean).join(", ");
-    const placed = args.x === undefined && args.y === undefined && !saidStack ? " Cards stack until organize lays them out along the arrows." : "";
-    if (placed) saidStack = true;
+    const placed = args.x === undefined && args.y === undefined ? ` Placed after the last card in reading order (${Math.round(landing.x)},${Math.round(landing.y)}); organize lays the wall out along the arrows.` : "";
     return ok(`Created card ${result?.id ?? ""}: ${landed}${where(live)}.${castLine}${placed}`, result);
   },
 );
@@ -1161,7 +1180,7 @@ server.registerTool(
   {
     title: "Read the wall",
     description:
-      "Read the board back: the beats in wall order (rows top to bottom, cards left to right), the pages of scenes between consecutive beats with the cards in each, every setup with the distance to its payoff, and the questions the wall raises — no beat marked yet; a run out of proportion with the others; beats back to back with nothing between them (a chain of them is one question); a card with a placeholder headline or no change line; a card no arrow touches; two headlines that read like the same scene; a group too long to be one sequence; a person in the cast on no card; a person gone for more than a third of the story and ten pages; a payoff before its setup on the wall; a folded card no setup arrow pays off; cards that say no place once any card has one. These are questions, not fixes: put them to the writer and do not act on them unasked. It says nothing about how many beats there should be, and neither should you.",
+      "Read the board back: the beats in wall order (rows top to bottom, cards left to right), the pages of scenes between consecutive beats with the cards in each, every setup with the distance to its payoff, and the questions the wall raises — no beat marked yet; a run out of proportion with the others; beats back to back with nothing between them (a chain of them is one question); a card with a placeholder headline or no change line; a card no arrow touches; two headlines that read like the same scene; a group too long to be one sequence; a person in the cast on no card; a person gone for more than a third of the story and ten pages; a payoff before its setup on the wall; a folded card no setup arrow pays off; cards that say no place once any card has one. These are questions, not fixes: put them to the writer and do not act on them unasked. It says nothing about how many beats there should be, and neither should you. The prose carries every id; the JSON after it is the same reading for a program, and PLOTCODER_JSON=0 in the server's environment drops it.",
     inputSchema: {},
   },
   async () => {
@@ -1176,6 +1195,7 @@ server.registerTool(
     const lines = [
       `PlotCoder wall (${door(live, base)})`,
       `logline: ${state.logline ? `"${state.logline}"` : "(none yet)"}`,
+      "the cast and the places are list_board's, not the reading's",
       state.targetEighths === DEFAULT_TARGET_EIGHTHS
         ? `runtime: about ${formatPages(boardEighths(state))} pages; no target set (set_target)`
         : `runtime: about ${formatPages(boardEighths(state))} pages of a ${formatPages(state.targetEighths)}-page target — ${boardEighths(state) > state.targetEighths ? `${formatPages(boardEighths(state) - state.targetEighths)} over` : boardEighths(state) < state.targetEighths ? `${formatPages(state.targetEighths - boardEighths(state))} under` : "on it"}`,
@@ -1185,12 +1205,12 @@ server.registerTool(
               .map((group) => {
                 const members = state.notes.filter((note) => group.noteIds.includes(note.id));
                 const act = /^act\b/i.test((group.title ?? "").trim());
-                return `"${group.title || "(untitled)"}" — ${members.length} card(s), about ${formatPages(members.reduce((sum, note) => sum + noteEighths(note), 0))} pages${act ? ", read as an act (never asked whether it is one sequence)" : ", read as a sequence"}`;
+                return `"${group.title || "(untitled)"}" — ${members.length} card(s), about ${formatPages(members.reduce((sum, note) => sum + noteEighths(note), 0))} pages${act ? ", read as an act, so its length is not questioned" : ", read as a sequence"}`;
               })
               .join("; ")
           : "(none)"
       }`,
-      `pages: ${written === 0 ? "all estimates — no scene is written yet, so every card is the writer's guess" : written === state.notes.length ? "measured — every scene is written" : `estimates — ${written} of ${state.notes.length} cards are written, the rest are guesses`}`,
+      `pages: ${written === 0 ? "all estimates — no scene is written yet, so every card is the writer's guess" : written === state.notes.length ? "measured — every scene is written" : `estimates — ${written} of ${state.notes.length} cards are written${written <= 5 ? ` (${state.notes.filter((note) => isMeasured(note)).map((note) => `"${note.headline}"`).join(", ")})` : ""}, the rest are guesses`}`,
       `beats in wall order: ${
         reading.beats.length
           ? reading.beats.map((beat) => `"${beat.headline}"`).join(", ")
@@ -1206,7 +1226,13 @@ server.registerTool(
       ...(reading.findings.length
         ? reading.findings.map((finding) => `  - [${finding.kind}] ${finding.text}${finding.ids.length ? ` (ids: ${finding.ids.join(", ")})` : ""}`)
         : ["  (none that this reading can see)"]),
-      `checks: ${CHECKS.length} run — asking about ${[...new Set(reading.findings.map((finding) => finding.kind))].filter((kind) => CHECKS.includes(kind)).join(", ") || "nothing"}; checked and clean: ${CHECKS.filter((kind) => !reading.findings.some((finding) => finding.kind === kind)).map((kind) => CHECK_WORDS[kind]).join("; ") || "(nothing — every check found something)"}`,
+      `checks: ${CHECKS.length} run — ${(() => {
+        const asked = reading.findings.filter((finding) => CHECKS.includes(finding.kind));
+        if (asked.length === 0) return "asking nothing";
+        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(", ")}`;
+      })()}; checked and clean: ${CHECKS.filter((kind) => !reading.findings.some((finding) => finding.kind === kind)).map((kind) => CHECK_WORDS[kind]).join("; ") || "(nothing — every check found something)"}`,
     ];
     if (isSampleWall(state)) lines.unshift(SAMPLE_NOTE);
     return ok(lines.join("\n"), { ...reading, sample: isSampleWall(state) });
@@ -1315,7 +1341,7 @@ server.registerTool(
       else if (note && !wrappedUnder.some((item) => item.beat === currentBeat)) wrappedUnder.push({ beat: currentBeat, first: note });
     }
     const shape = beats
-      ? `${opening ? `an opening row of ${opening} card(s) before the first beat, then ` : ""}${beats} row(s), one per beat${wrappedUnder.length ? `; ${wrappedUnder.map((item) => `the row of "${item.beat.headline}" wraps under from "${item.first.headline}"`).join(", ")}` : ""}`
+      ? `${opening ? `an opening row of ${opening} card(s) before the first beat, then ` : ""}${beats} row(s), one per beat${wrappedUnder.length ? `; ${wrappedUnder.map((item) => `the row of "${item.beat.headline}" wraps under from "${item.first.headline}", indented under the row's first scene, never under the beat`).join(", ")}` : ""}`
       : `${rows} row(s) five cards wide — no beats yet, so nothing sets the rows; set_rank the turns and organize again for a row per beat`;
     return ok(`Organized ${poses.length} card(s) along the arrows into ${shape}${where(live)}.`, poses);
   },
@@ -2021,7 +2047,7 @@ server.registerTool(
       if (!result) return ok(`No character with id ${person.id}. Call list_board for the cast.`);
       return ok(`Nothing changed on ${result.name}'s page: those lines already read that way.`, result);
     }
-    const trim = (text) => (text.length > 140 ? `${text.slice(0, 137)}…` : text);
+    const trim = (text) => (text.length > 400 ? `${text.slice(0, 140)}… (${text.length} characters in all, every one landed)` : text);
     const lines = Object.keys(patch).map((field) => {
       const had = (person[field] ?? "").trim();
       const now = (result[field] ?? "").trim();
@@ -2528,7 +2554,8 @@ server.registerTool(
     workingProject(record.id, record.name, (account.projectCount ?? 0) + 1);
     joinPresence(record.id);
     const targetLine = target === undefined ? ` Its target is ${formatPages(state.targetEighths)} pages, the default for a feature; set_target for a pilot or a half-hour, or pass pages or minutes here.` : ` Its target is ${formatPages(state.targetEighths)} pages.`;
-    return ok(`Started "${record.name}" (${record.id}) and working it now, as ${account.email}.${targetLine}${oneCallHint(record)}`, { id: record.id, name: record.name, targetEighths: state.targetEighths });
+    const first = record.boards[0];
+    return ok(`Started "${record.name}" (${record.id}) with its first board "${first.name}" (${first.id}), and working it now, as ${account.email}.${targetLine}${oneCallHint(record)}`, { id: record.id, name: record.name, boardId: first.id, boardName: first.name, targetEighths: state.targetEighths });
   },
 );
 
@@ -2628,7 +2655,7 @@ server.registerTool(
   {
     title: "Save the project as a file",
     description:
-      "The project the server is working, as the file Save project writes and Open project takes: the record, every board with its cards, the reminders and the writer's structures. Pass path to write it (a .json); without a path, the reply's JSON is the file. Pictures and takes on the account are not in the file. Works through every door.",
+      "The project the server is working, as the file Save project writes and Open project takes: the record, every board with its cards, the reminders and the writer's structures. Pass path to write it (a .json) — an absolute path, since a relative one resolves from the server's own folder, not yours; without a path, the reply's JSON is the file. Pictures and takes on the account are not in the file. Works through every door.",
     inputSchema: { path: z.string().optional() },
   },
   async (args) => {
@@ -2640,7 +2667,7 @@ server.registerTool(
     if (args.path) {
       fs.mkdirSync(path.dirname(path.resolve(args.path)), { recursive: true });
       fs.writeFileSync(args.path, JSON.stringify(file, null, 2));
-      return ok(`Saved ${what}. Written to ${args.path}: Open project in the app takes it, import_project brings it onto an account.`, { path: args.path, boards: project.boards.length, cards });
+      return ok(`Saved ${what}. Written to ${path.resolve(args.path)}: Open project in the app takes it, import_project brings it onto an account.`, { path: path.resolve(args.path), boards: project.boards.length, cards });
     }
     return ok(`The project as a file — ${what}. The JSON below is the file; write it to a .json for Open project or import_project.`, file);
   },

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.",
+    "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.",
   doors: [
     {
       id: "mcp",
@@ -42,7 +42,7 @@ export const AGENTS = {
       text: "Skip this when the account is the wall. Without an account, a wall is a folder: any folder, empty is fine — choose one that will outlive your session, never a scratch one. The app run from that folder shows the wall, and the server writes it there (PLOTCODER_ROOT, or the folder it is run from). A fresh folder holds the sample; new_board for the writer's wall, then rename_project. No app running? export_fountain is the wall in order, as text.",
     },
   ],
-  firstNote: "These four are about the wall you will work, so after open_project or open_board, 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: "These four 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.",
   first: [
     { tool: "list_words", why: "the room's words, the app's meaning." },
     { tool: "read_wall", why: "what is here, and what it asks. A fresh folder holds a sample wall (Maya, Tom, the letter) and says so; it is not the writer's." },
@@ -51,7 +51,7 @@ export const AGENTS = {
   ],
   rules: [
     "Questions, not fixes, until the writer says.",
-    "No opinions about how many beats there should be.",
+    "No opinions about how many beats there should be. Marking the turns a treatment plainly makes is reading it, not an opinion: mark them, say which, and let the writer strike or add.",
     "Page counts are estimates.",
     "Ask before delete_board, delete_project, empty_account, delete_account, unlock_numbers, remove_file, an import_project that replaces, or claim_account — the writer gives the email and the password; never invent one. export_project first, when something might be wanted back.",
     "Do not invent people or a logline. What the treatment states — an age, a job, a bad knee — is not invented: it goes in the person's notes. An unnamed person is named by their role — Dana's mother, the dispatcher — which is a name until the writer gives one. A scene is one place and one stretch of time; a new place or time is a new card. A beat is a whole card; a setup arrow lands on the scene's card, so a payoff never needs a card of its own. Acts are groups titled Act one, Act two, when the treatment has them; the wall never asks whether an act is a sequence. Paper colour means nothing to the app. Under target is a fact to report plainly, like over; neither is a verdict.",
@@ -64,7 +64,7 @@ export const AGENTS = {
 
 /** The on-ramp as one text: the file at /llms.txt, and what an agent reads. */
 export function agentsAsText() {
-  const lines = ["# PlotCoder — for agents", "", AGENTS.lead, "", `The guide, read once before anything: ${AGENTS.guide}.`, "", "## Doors"];
+  const lines = ["# PlotCoder — for agents", "", AGENTS.lead, "", `The guide, read once before anything: ${AGENTS.guide}. The guide is the whole and this page is its first page; where the two differ, the guide wins.`, "", "## Doors"];
   for (const door of AGENTS.doors) {
     lines.push(`- ${door.name}: ${door.text}`);
     if (door.code) lines.push("", "```", door.code, "```", "");