plotcoder-board 0.1.35 → 0.1.36

package/README.md

@@ -4,6 +4,8 @@ A storylining app for screenwriters, live at [plotcoder.com](http://plotcoder.co
 
 PlotCoder is a set of tools for building a storyline, covering the activities a writer does today in Final Draft. It is designed so that an **agent driven by a person** has every one of those tools: the person directs, the agent operates, and the board on screen is the person's window onto the same records. The first tool is the wall, a digital corkboard for breaking and rearranging plot before writing the script, because that is the part of the job Final Draft does worst. Pages come last. Once the tools exist, workflows get launched on top of them. The horizon, a long way off: a person makes a storyline they believe in, then the app helps them drive agents that build segments of the movie with video generation tools.
 
+**Using it as a writer:** [plotcoder.com/writers.html](https://plotcoder.com/writers.html) says how, from the door to the script out, the agent first. Its source is `public/writers.html`, and a change to a gesture or a sheet changes it in the same pull request (R63).
+
 The full statement of purpose, every decision, and every requirement lives in [REQUIREMENTS.md](REQUIREMENTS.md). Read it before changing anything. It is the source of truth; this file is the front door.
 
 ## The method the tools serve
@@ -105,4 +107,4 @@ next round into a test of `claim_account` instead of the door it meant to test.
 
 ## Status
 
-Version 0.1.35. 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.36. 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.35",
+  "version": "0.1.36",
   "type": "module",
   "scripts": {
     "dev": "vite",

package/scripts/plotcoder-mcp-server.mjs

@@ -3877,6 +3877,63 @@ server.registerTool(
   },
 );
 
+// Help in the app (R64): the questions writers asked that the guide did not
+// answer. They are the app's, not a project's, so these two tools take the
+// maintainer's service role from the server's environment — the key never
+// ships, as the wipe script's does not — and every other door refuses them.
+async function questionsDoor() {
+  const key = process.env.SUPABASE_SERVICE_ROLE_KEY || process.env.PLOTCODER_SERVICE_ROLE_KEY;
+  if (!key) return null;
+  const { createClient } = await import("@supabase/supabase-js");
+  return createClient(process.env.SUPABASE_URL || SUPABASE_URL, key, { auth: { persistSession: false } });
+}
+const NO_QUESTIONS_DOOR = "The questions are the app's, not a project's: set SUPABASE_SERVICE_ROLE_KEY in the server's environment — the maintainer's key, never in the repo — and call again. A writer asks from the Help sheet; the answer goes into public/writers.html and back to them through answer_question.";
+
+server.registerTool(
+  "list_questions",
+  {
+    title: "The writers' questions",
+    description:
+      "The questions writers asked from the app's Help sheet that the guide did not answer, waiting first: who asked, when, the words. Maintainer only — needs the service role in the server's environment. Answer one with answer_question after the answer is in public/writers.html.",
+    inputSchema: { all: z.boolean().optional() },
+  },
+  async (args) => {
+    const db = await questionsDoor();
+    if (!db) return ok(NO_QUESTIONS_DOOR);
+    const { data, error } = await db.from("questions").select("id, email, question, asked_at, answered_at, answer, section").order("asked_at", { ascending: false });
+    if (error) return ok(`Could not read the questions: ${error.message}`);
+    const rows = args.all ? data : data.filter((row) => !row.answered_at);
+    const waiting = data.filter((row) => !row.answered_at).length;
+    const line = (row) => `  - ${row.id.slice(0, 8)} · ${String(row.asked_at).slice(0, 10)} · ${row.email} · "${row.question}" · ${row.answered_at ? `answered ${String(row.answered_at).slice(0, 10)}${row.section ? ` → ${row.section}` : ""}` : "waiting"}`;
+    return ok(
+      [`${waiting} waiting, ${data.length - waiting} answered.${args.all ? "" : " (all: true lists the answered ones too)"}`, ...(rows.length ? rows.map(line) : ["  (none)"])].join("\n"),
+      rows,
+    );
+  },
+);
+
+server.registerTool(
+  "answer_question",
+  {
+    title: "Answer a writer's question",
+    description:
+      "Mark a writer's question answered, with the answer in a sentence or two and the guide's section it went into (\"#s5\"), once the answer is in public/writers.html: the writer sees both under Your questions. Maintainer only — needs the service role in the server's environment. The guide is the answer; this is the promise kept.",
+    inputSchema: { id: z.string().min(1), answer: z.string().min(1), section: z.string().optional() },
+  },
+  async (args) => {
+    const db = await questionsDoor();
+    if (!db) return ok(NO_QUESTIONS_DOOR);
+    const { data: found, error: findError } = await db.from("questions").select("id, question, answered_at").ilike("id", `${args.id}%`);
+    if (findError) return ok(`Could not read the questions: ${findError.message}`);
+    if (!found?.length) return ok(`No question whose id starts "${args.id}". list_questions shows them.`);
+    if (found.length > 1) return ok(`${found.length} questions start "${args.id}": say more of the id.`);
+    const row = found[0];
+    const { error } = await db.from("questions").update({ answered_at: new Date().toISOString(), answer: args.answer.trim(), section: args.section?.trim() || null }).eq("id", row.id);
+    if (error) return ok(`Could not answer it: ${error.message}`);
+    return ok(`Answered "${row.question}"${args.section ? ` and filed it under ${args.section.trim()}` : ""}${row.answered_at ? " (it had been answered before; this replaces that)" : ""}. The writer sees it under Your questions. If the answer is not yet in public/writers.html, put it there and open the pull request: the guide is the answer, this list is the promise.`, { id: row.id });
+  },
+);
+
 server.registerTool(
   "export_project",
   {

package/src/board/agents.js

@@ -58,7 +58,7 @@ export const AGENTS = {
     "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. A thing the writer has not decided is an open card in their words (set_open), or an open field — the logline, the premise, a card's place or when, a board's or the project's name take open beside the value — never a guess to fill the field; a thing whose far end the writer knows and not where it is first seen — the letter, the ring — is a thread (create_thread) with an open start, and the wall asks from that end.",
   ],
   person:
-    "Give your agent the account door only on a machine you trust; it signs in as you and shows under People as “an agent, as you” while it runs. Wire the server before you start the agent's session, with the two sign-in lines beside it, and the agent has every tool from its first message; wired from inside a session, the server connects only on the next one. Your agent can also make your account: give it your email and a password of your choosing.",
+    "Give your agent the account door only on a machine you trust; it signs in as you and shows under People as “an agent, as you” while it runs. Wire the server before you start the agent's session, with the two sign-in lines beside it, and the agent has every tool from its first message; wired from inside a session, the server connects only on the next one. Your agent can also make your account: give it your email and a password of your choosing. Your own guide — how a writer uses PlotCoder, from the door to the script out, the agent first — is at https://plotcoder.com/writers.html.",
   guide: "https://plotcoder.com/guide.md",
   url: "https://plotcoder.com/llms.txt",
 };

package/src/board/help.d.ts

@@ -0,0 +1,11 @@
+// Type surface for help.js — Help in the app (R64).
+
+export type GuideParagraph = { id: string; title: string; sub: string; text: string };
+export type HelpHit = { kind: "word" | "guide"; from: string; text: string; href: string | null };
+export type HelpWord = { name: string; sentence: string };
+
+export declare function helpWords(text: string): string[];
+/** The guide's page as paragraphs under their section and sub-head. */
+export declare function indexGuide(html: string): GuideParagraph[];
+/** The hits for a question: the words first, then the guide, by how many of the question's words each holds. Empty when nothing matches. */
+export declare function searchHelp(query: string, words: HelpWord[], guide: GuideParagraph[], limit?: number): HelpHit[];

package/src/board/help.js

@@ -0,0 +1,103 @@
+// Help in the app (R64): the writer's guide and the words, searched by the
+// writer's own words. Pure: the sheet fetches the guide's page and hands its
+// HTML here; the maintainer's tools and the tests never touch a browser.
+
+const FILLER = new Set(["a", "an", "the", "and", "or", "of", "to", "in", "on", "at", "is", "it", "i", "do", "how", "can", "my", "me", "we", "you", "your", "for", "with", "be", "what", "when", "where", "does", "did", "this", "that", "from", "as", "by", "are", "am", "if", "so", "up", "one", "two", "not", "no", "yes"]);
+
+/** The words of a question or a paragraph, lower-cased, without the filler. */
+export function helpWords(text) {
+  return (text ?? "")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s]/gu, " ")
+    .split(/\s+/)
+    .filter((word) => word && !FILLER.has(word));
+}
+
+function stripTags(html) {
+  return html
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * The guide's page as paragraphs, each under its section (an <h2 id="sN">)
+ * and its sub-head (an <h3>), so a hit can say where it comes from and link
+ * there. Anything before the first section — the title, the contents — is
+ * not indexed.
+ */
+export function indexGuide(html) {
+  const paragraphs = [];
+  const sections = html.split(/(?=<h2 id="s\d+">)/g).slice(1);
+  for (const chunk of sections) {
+    const head = /^<h2 id="(s\d+)">([^<]*)<\/h2>/.exec(chunk);
+    if (!head) continue;
+    const id = head[1];
+    const title = stripTags(head[2]).replace(/^\d+\.\s*/, "");
+    let sub = "";
+    const parts = chunk.slice(head[0].length).split(/(?=<h3>)|(?=<p>)/g);
+    for (const part of parts) {
+      const h3 = /^<h3>([^<]*)<\/h3>/.exec(part);
+      if (h3) {
+        sub = stripTags(h3[1]);
+        continue;
+      }
+      const p = /^<p[^>]*>([\s\S]*?)<\/p>/.exec(part);
+      if (p) {
+        const text = stripTags(p[1]);
+        if (text) paragraphs.push({ id, title, sub, text });
+      }
+    }
+  }
+  return paragraphs;
+}
+
+/**
+ * The hits for a question: the words first, then the guide's paragraphs, each
+ * scored by how many of the question's words it holds (a word matches on its
+ * start, so "beats" finds "beat"). Nothing matched is an empty list, which is
+ * the sheet's cue to offer Ask.
+ */
+export function searchHelp(query, words, guide, limit = 8) {
+  // A plural asks for its singular too: "beats" finds "beat", "writers" finds "writer".
+  const stem = (word) => (word.length > 3 && word.endsWith("s") ? word.slice(0, -1) : word);
+  const wanted = [...new Set(helpWords(query).map(stem))];
+  if (wanted.length === 0) return [];
+  // A short question is answered whole; a long one may miss a word.
+  const needed = wanted.length <= 3 ? wanted.length : wanted.length - 1;
+  const holds = (have, want) => have.some((word) => word === want || word.startsWith(want));
+  const count = (text) => {
+    const have = helpWords(text);
+    let hits = 0;
+    for (const want of wanted) if (holds(have, want)) hits += 1;
+    return hits;
+  };
+  const scored = [];
+  for (const word of words ?? []) {
+    const hits = count(`${word.name} ${word.sentence}`);
+    if (hits < needed) continue;
+    // The entry named for the thing asked about comes first: "A beat" before a sentence that mentions beats.
+    const named = count(word.name) > 0 ? 2 : 0;
+    scored.push({ kind: "word", from: `The words · ${word.name}`, text: word.sentence, href: null, rank: hits + named, order: scored.length });
+  }
+  for (const paragraph of guide ?? []) {
+    const hits = count(`${paragraph.title} ${paragraph.sub} ${paragraph.text}`);
+    if (hits < needed) continue;
+    const headed = count(`${paragraph.title} ${paragraph.sub}`) > 0 ? 1 : 0;
+    scored.push({
+      kind: "guide",
+      from: `The guide · ${paragraph.title}${paragraph.sub ? ` · ${paragraph.sub}` : ""}`,
+      text: paragraph.text,
+      href: `/writers.html#${paragraph.id}`,
+      rank: hits + headed,
+      order: scored.length,
+    });
+  }
+  scored.sort((a, b) => b.rank - a.rank || (a.kind === "word" ? -1 : b.kind === "word" ? 1 : 0) || a.order - b.order);
+  return scored.slice(0, limit).map(({ kind, from, text, href }) => ({ kind, from, text, href }));
+}

package/src/board/words.js

@@ -73,6 +73,11 @@ export const WORD_GROUPS = [
         name: "A thread",
         sentence: "A named string through the cards a thing runs through — the letter, the key, a subplot — with either end open until the writer ties it. Drawn on the wall as a dashed string, a ring where an end is loose; the reading asks where a loose thread is first seen, or where it comes out.",
       },
+      {
+        id: "help",
+        name: "Help",
+        sentence: "The button top right: type a question and the words and the writer's guide answer as you go; when nothing does, Ask sends it to the people who build PlotCoder, and the answer lands in the guide and under Your questions.",
+      },
       {
         id: "corner",
         name: "The folded corner",