@miadi/stateloom-mcp 0.2.5 → 0.3.0

package/dist/server.js

@@ -18,15 +18,34 @@
  *   - load_definition: Load a definition from JSON
  *   - list_states: List all states in the current definition
  *   - list_events: List all events in the current definition
- *   - set_project_file: Choose which document is active (.smdf.json or .erdf.json)
+ *   - set_project_file: Choose which document is active — .smdf.json (state
+ *     machine), .erdf.json (ERD), .sqdf.json (sequence) or .sysdf.json (system)
  *   - get_project_file: Report the active document path and bridge status
  *
- * ERD tools (Spec 80, ./erd.ts) — the active document's type is its extension:
+ * The active document's type is its extension, and the tools for each type
+ * refuse to write over another type.
+ *
+ * ERD tools (Spec 80, ./erd.ts):
  *   - create_erd, add_entity, update_entity, add_attribute, add_relationship
  *   - remove_entity, remove_attribute, remove_relationship
  *   - validate_erd, check_links
- *   get_definition, load_definition and render_diagram answer for an ERD when
- *   the active document is one.
+ *
+ * Sequence tools (Spec 81, ./sequence.ts) — a usage scenario:
+ *   - create_sequence, add_participant, update_participant, remove_participant
+ *   - add_message, update_message, remove_message, move_message
+ *   - add_fragment, add_fragment_message, remove_fragment, validate_sequence
+ *
+ * System tools (Spec 82, ./system.ts) — the drawings of one thing, together:
+ *   - create_system, add_member, remove_member, add_actor, remove_actor
+ *   - set_reconcile_mode, check_system, replay_scenario, reconcile_scenario
+ *   - show: tell the canvases on a system which member and element to show
+ *   In reconcile mode auto, each sequence edit also updates the machines, the
+ *   ERD and the system it implies (./live.ts pushes the changes to their rooms).
+ *
+ * Notes (every document type): set_notes, get_notes — what a person or an
+ * agent wrote down about the diagram or one of its shapes, saved in the file.
+ *   get_definition, load_definition, render_diagram and check_links answer for
+ *   the active document's type; generate_rispec also writes a system's rispec.
  *
  * Resources:
  *   - smcraft://definition — Current state machine definition
@@ -46,10 +65,13 @@ import { basename, dirname, join, resolve } from "path";
 import { fileURLToPath } from "node:url";
 import { tmpdir } from "os";
 import { createBridgeClient } from "@miadi/stateloom-client";
-import { envAlias, isErdfPath, } from "@miadi/stateloom-protocol";
+import { collectNotes, docKindOfPath, envAlias, isErdfPath, isSqdfPath, isSysdfPath, } from "@miadi/stateloom-protocol";
 import { renderDiagramToFile, defaultOutputPath } from "@miadi/stateloom-cli/render";
 import { resolveProjectSwitch } from "./projectSwitch.js";
-import { registerErdTools, erdSummary, erdGetDefinition, erdLoadDefinition, erdRender, } from "./erd.js";
+import { registerErdTools, erdSummary, erdGetDefinition, erdLoadDefinition, erdRender, erdGetNotes, erdSetNotes, formatNotes, } from "./erd.js";
+import { registerSequenceTools, sequenceSummary, sequenceGetDefinition, sequenceLoadDefinition, sequenceRender, sequenceGetNotes, sequenceSetNotes, } from "./sequence.js";
+import { registerSystemTools, checkSystemReport, reconcileAfterEdit, reconcileModeLine, systemSummary, systemGetDefinition, systemLoadDefinition, systemRender, systemGetNotes, systemSetNotes, systemRispec, } from "./system.js";
+import { liveBridge } from "./live.js";
 // STATELOOM_* read first, SMCRAFT_* legacy twin honored — the live MCP
 // registration bakes SMCRAFT_PROJECT_FILE and must keep working (2026-07-27
 // rename brief). Resolved once at boot, like the direct reads they replace.
@@ -69,9 +91,17 @@ const canvasLink = (path) => `${CANVAS_URL}/?doc=${encodeURIComponent(path)}`;
 // Mutable: `set_project_file` lets the agent re-point the loom at another
 // .smdf.json document mid-session (the hub keys live rooms by this path).
 let PROJECT_FILE = resolve(envAlias("PROJECT_FILE") ?? "./statemachine.smdf.json");
+const KIND_WORDS = { machine: "a state machine", erd: "an ERD", sequence: "a sequence", system: "a system" };
+/** What the state-machine tools say when there is no machine to act on. */
+function noMachine(then = "") {
+    const kind = docKindOfPath(PROJECT_FILE);
+    if (kind === "machine")
+        return `No state machine at ${PROJECT_FILE}.${then}`;
+    return `The active document ${PROJECT_FILE} is ${KIND_WORDS[kind]}, not a state machine. Use the ${kind === "erd" ? "ERD" : kind} tools on it, or set_project_file to a .smdf.json document.`;
+}
 function readDef() {
-    // An ERD is not a machine; the state-machine tools see no definition there.
-    if (isErdfPath(PROJECT_FILE))
+    // An ERD, a sequence or a system is not a machine; the state-machine tools see no definition there.
+    if (docKindOfPath(PROJECT_FILE) !== "machine")
         return null;
     if (!existsSync(PROJECT_FILE))
         return null;
@@ -86,11 +116,10 @@ function readDef() {
     }
 }
 function writeDef(def) {
-    // Never write a machine over an ERD: create_state_machine and load_definition
-    // write without reading first, so this is the one place that can refuse.
-    if (isErdfPath(PROJECT_FILE)) {
-        throw new Error(`The active document ${PROJECT_FILE} is an ERD. Use the ERD tools on it, or set_project_file to a .smdf.json document for a state machine.`);
-    }
+    // Never write a machine over an ERD, a sequence or a system: create_state_machine
+    // and load_definition write without reading first, so this is the one place that can refuse.
+    if (docKindOfPath(PROJECT_FILE) !== "machine")
+        throw new Error(noMachine());
     writeFileSync(PROJECT_FILE, JSON.stringify({ stateMachine: def }, null, 2), "utf8");
 }
 // ─── Optional real-time design bridge (env-gated, best-effort) ───────
@@ -224,6 +253,34 @@ const erdHost = {
     },
     emitFull: (def) => bridgeEmitFull(def),
     outsideRoot: (path) => outsideRoot(path),
+    // From a sequence or a system, the links are the whole system's: check_system.
+    checkSystem: async () => checkSystemReport(systemHost),
+};
+// Pushes to rooms other than the active document's: a reconciled machine, an
+// ERD, a view on a system. Each is a short-lived client of its own (./live.ts).
+const live = liveBridge({ url: BRIDGE_URL, token: BRIDGE_TOKEN, name: AGENT_NAME ?? "mcp-agent" });
+// The system this server last created, set or checked — where `show` and the
+// system tools go when neither an argument nor the active document names one.
+let LAST_SYSTEM = isSysdfPath(PROJECT_FILE) ? PROJECT_FILE : undefined;
+const systemHost = {
+    projectFile: () => PROJECT_FILE,
+    outsideRoot: (path) => outsideRoot(path),
+    emitFull: (def) => bridgeEmitFull(def),
+    live,
+    reconcileOverride: () => envAlias("RECONCILE"),
+    validateMachine: (def) => validate(def),
+    machineSpec: (def, level) => machineSpecLines(def, level),
+    lastSystem: () => LAST_SYSTEM,
+    rememberSystem: (path) => {
+        LAST_SYSTEM = path;
+    },
+};
+const sequenceHost = {
+    projectFile: () => PROJECT_FILE,
+    switchTo: (path) => erdHost.switchTo(path),
+    emitFull: (def) => bridgeEmitFull(def),
+    outsideRoot: (path) => outsideRoot(path),
+    afterEdit: (path) => reconcileAfterEdit(systemHost, path),
 };
 function createEmpty(namespace, name) {
     return {
@@ -498,30 +555,7 @@ function generateRispec(def, intent) {
     // Specifications
     lines.push("## S — Specifications");
     lines.push("");
-    lines.push("### States");
-    lines.push("");
-    for (const s of states) {
-        renderStateSpec(s, lines, 0);
-    }
-    lines.push("");
-    lines.push("### Events");
-    lines.push("");
-    for (const src of def.events) {
-        if (!src.events?.length)
-            continue;
-        lines.push(`**${src.name}**`);
-        for (const e of src.events) {
-            lines.push(`- \`${e.id}\`${e.description ? ` — ${e.description}` : ""}`);
-        }
-        lines.push("");
-    }
-    lines.push("### Transitions (flat)");
-    lines.push("");
-    for (const t of collectTransitions(def.state)) {
-        const arrow = t.next ? `→ ${t.next}` : "→ (internal)";
-        lines.push(`- \`${t.from}\` --[${t.event}]-- ${arrow}${t.condition ? ` *(when: ${t.condition})*` : ""}`);
-    }
-    lines.push("");
+    lines.push(...machineSpecLines(def, 3));
     // Action Steps (medicine-wheel walk if South/East/North/West present)
     const mw = states.filter((s) => ["East", "South", "West", "North"].includes(s.name));
     if (mw.length || pde?.actionStack?.length) {
@@ -565,6 +599,40 @@ function generateRispec(def, intent) {
     lines.push("");
     return lines.join("\n");
 }
+/**
+ * A machine's states, events and flat transitions as markdown, headings at
+ * `level` — the Specifications of a machine's rispec, and each machine's
+ * Behaviour in a system's rispec.
+ */
+function machineSpecLines(def, level) {
+    const h = "#".repeat(level);
+    const lines = [];
+    lines.push(`${h} States`);
+    lines.push("");
+    for (const s of def.state?.states ?? []) {
+        renderStateSpec(s, lines, 0);
+    }
+    lines.push("");
+    lines.push(`${h} Events`);
+    lines.push("");
+    for (const src of def.events ?? []) {
+        if (!src.events?.length)
+            continue;
+        lines.push(`**${src.name}**`);
+        for (const e of src.events) {
+            lines.push(`- \`${e.id}\`${e.description ? ` — ${e.description}` : ""}`);
+        }
+        lines.push("");
+    }
+    lines.push(`${h} Transitions (flat)`);
+    lines.push("");
+    for (const t of def.state ? collectTransitions(def.state) : []) {
+        const arrow = t.next ? `→ ${t.next}` : "→ (internal)";
+        lines.push(`- \`${t.from}\` --[${t.event}]-- ${arrow}${t.condition ? ` *(when: ${t.condition})*` : ""}`);
+    }
+    lines.push("");
+    return lines;
+}
 function depth(s, d = 0) {
     if (!s.states?.length)
         return d;
@@ -678,7 +746,7 @@ function buildServer() {
         const def = readDef();
         if (!def)
             return {
-                content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}. Use create_state_machine first.` }],
+                content: [{ type: "text", text: noMachine(" Use create_state_machine first.") }],
                 isError: true,
             };
         const parentName = parent ?? "Root";
@@ -703,7 +771,7 @@ function buildServer() {
         const def = readDef();
         if (!def)
             return {
-                content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }],
+                content: [{ type: "text", text: noMachine() }],
                 isError: true,
             };
         const source = def.events[0];
@@ -724,7 +792,7 @@ function buildServer() {
         const def = readDef();
         if (!def)
             return {
-                content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }],
+                content: [{ type: "text", text: noMachine() }],
                 isError: true,
             };
         const target = findState(def.state, state);
@@ -746,7 +814,7 @@ function buildServer() {
     server.tool("remove_state", "Remove a state from the definition", { name: z.string() }, async ({ name }) => {
         const def = readDef();
         if (!def)
-            return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
+            return { content: [{ type: "text", text: noMachine() }], isError: true };
         if (name === "Root")
             return { content: [{ type: "text", text: "Cannot remove Root state." }], isError: true };
         def.state = removeState(def.state, name);
@@ -757,7 +825,7 @@ function buildServer() {
     server.tool("validate_definition", "Validate the current state machine definition against all rules", {}, async () => {
         const def = readDef();
         if (!def)
-            return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
+            return { content: [{ type: "text", text: noMachine() }], isError: true };
         const errors = validate(def);
         if (errors.length === 0)
             return { content: [{ type: "text", text: "✓ Definition is valid. No errors found." }] };
@@ -769,7 +837,7 @@ function buildServer() {
     server.tool("generate_code", "Generate Python or TypeScript code from the current definition", { language: z.enum(["python", "typescript"]) }, async ({ language }) => {
         const def = readDef();
         if (!def)
-            return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
+            return { content: [{ type: "text", text: noMachine() }], isError: true };
         const errors = validate(def);
         if (errors.length > 0) {
             const lines = errors.map((e) => `[${e.ruleId}] ${e.message}`).join("\n");
@@ -781,19 +849,27 @@ function buildServer() {
         const code = generateViaSmcg(def, language);
         return { content: [{ type: "text", text: code }] };
     });
-    server.tool("get_definition", "Get the current definition as JSON — the state machine, or the ERD when the active document is a .erdf.json", {}, async () => {
+    server.tool("get_definition", "Get the active document as JSON — a state machine, or the ERD, sequence or system when the active document is a .erdf.json, .sqdf.json or .sysdf.json", {}, async () => {
         if (isErdfPath(PROJECT_FILE))
             return erdGetDefinition(erdHost);
+        if (isSqdfPath(PROJECT_FILE))
+            return sequenceGetDefinition(sequenceHost);
+        if (isSysdfPath(PROJECT_FILE))
+            return systemGetDefinition(systemHost);
         const def = readDef();
         if (!def)
-            return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
+            return { content: [{ type: "text", text: noMachine() }], isError: true };
         return {
             content: [{ type: "text", text: JSON.stringify({ stateMachine: def }, null, 2) }],
         };
     });
-    server.tool("load_definition", "Load a definition from JSON into the active document — a state machine, or an ERD when the active document is a .erdf.json", { json: z.string() }, async ({ json }) => {
+    server.tool("load_definition", "Load a definition from JSON into the active document — a state machine, or an ERD, a sequence or a system when the active document is a .erdf.json, .sqdf.json or .sysdf.json", { json: z.string() }, async ({ json }) => {
         if (isErdfPath(PROJECT_FILE))
             return erdLoadDefinition(erdHost, json);
+        if (isSqdfPath(PROJECT_FILE))
+            return sequenceLoadDefinition(sequenceHost, json);
+        if (isSysdfPath(PROJECT_FILE))
+            return systemLoadDefinition(systemHost, json);
         try {
             const parsed = JSON.parse(json);
             const def = parsed.stateMachine ?? parsed.StateMachine ?? parsed;
@@ -817,7 +893,7 @@ function buildServer() {
     server.tool("list_states", "List all states in the current definition with their kind and transitions", {}, async () => {
         const def = readDef();
         if (!def)
-            return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
+            return { content: [{ type: "text", text: noMachine() }], isError: true };
         const lines = [];
         const walk = (state, depth) => {
             const indent = "  ".repeat(depth);
@@ -835,13 +911,13 @@ function buildServer() {
     server.tool("list_events", "List all events in the current definition", {}, async () => {
         const def = readDef();
         if (!def)
-            return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
+            return { content: [{ type: "text", text: noMachine() }], isError: true };
         const events = def.events.flatMap((src) => src.events.map((e) => `${e.id}${e.description ? ` — ${e.description}` : ""}`));
         if (events.length === 0)
             return { content: [{ type: "text", text: "No events defined yet." }] };
         return { content: [{ type: "text", text: events.join("\n") }] };
     });
-    server.tool("set_project_file", "Choose the active document the loom weaves — two modalities. STANDALONE: any .smdf.json path (a state machine) or .erdf.json path (an ERD — the ERD tools act on it). RELATIONAL: a chronicle address `miadi-chronicle://<episode>/<diagram>` resolving over $MIADI_CHRONICLE_ROOT to <episode-dir>/diagrams/<diagram>.smdf.json — an ambiguous episode number is a hard error naming the candidates. Disk persistence AND the live bridge room both re-point. A missing file is legitimate — naming it is how an episode's first diagram is created.", { path: z.string() }, async ({ path }) => {
+    server.tool("set_project_file", "Choose the active document the loom weaves — two modalities. STANDALONE: a path whose extension says what it is: .smdf.json (a state machine), .erdf.json (an ERD — the ERD tools act on it), .sqdf.json (a sequence — the sequence tools act on it) or .sysdf.json (a system — the system tools, check_system and show act on it). RELATIONAL: a chronicle address `miadi-chronicle://<episode>/<diagram>` resolving over $MIADI_CHRONICLE_ROOT to <episode-dir>/diagrams/<diagram>.smdf.json; name another type by its extension (`miadi-chronicle://103/flow.sqdf.json`) — an ambiguous episode number is a hard error naming the candidates. Disk persistence AND the live bridge room both re-point. A missing file is legitimate — naming it is how an episode's first diagram is created.", { path: z.string() }, async ({ path }) => {
         try {
             const r = resolveProjectSwitch(path, PROJECT_FILE);
             const denial = denyProjectSwitch(r.path);
@@ -852,14 +928,25 @@ function buildServer() {
                 bindBridge(PROJECT_FILE);
                 joinBridge();
             }
+            if (isSysdfPath(PROJECT_FILE))
+                LAST_SYSTEM = PROJECT_FILE;
             const def = r.exists ? readDef() : null;
-            const summary = isErdfPath(PROJECT_FILE)
-                ? erdSummary(PROJECT_FILE)
-                : def
-                    ? `existing machine '${def.settings.name}' (${collectStateNames(def.state).length} states, ${collectEventIds(def).length} events)`
-                    : r.exists
-                        ? "file exists but is not a readable definition"
-                        : "no file yet — create_state_machine or load_definition will write it";
+            const summary = [
+                isErdfPath(PROJECT_FILE)
+                    ? erdSummary(PROJECT_FILE)
+                    : isSqdfPath(PROJECT_FILE)
+                        ? sequenceSummary(PROJECT_FILE)
+                        : isSysdfPath(PROJECT_FILE)
+                            ? systemSummary(PROJECT_FILE)
+                            : def
+                                ? `existing machine '${def.settings.name}' (${collectStateNames(def.state).length} states, ${collectEventIds(def).length} events)`
+                                : r.exists
+                                    ? "file exists but is not a readable definition"
+                                    : "no file yet — create_state_machine or load_definition will write it",
+                reconcileModeLine(systemHost, PROJECT_FILE),
+            ]
+                .filter(Boolean)
+                .join("\n");
             const bridgeNote = BRIDGE_URL
                 ? r.unchanged
                     ? `bridge unchanged (${bridge?.status ?? "not configured"})`
@@ -881,15 +968,24 @@ function buildServer() {
             };
         }
     });
-    server.tool("get_project_file", "Report the active .smdf.json document path, whether it exists on disk, and live-bridge status", {}, async () => {
+    server.tool("get_project_file", "Report the active document's path and what it is (a .smdf.json state machine, .erdf.json ERD, .sqdf.json sequence or .sysdf.json system), whether it exists on disk, the reconcile mode for a sequence or a system, and live-bridge status", {}, async () => {
         const def = readDef();
-        const summary = isErdfPath(PROJECT_FILE)
-            ? erdSummary(PROJECT_FILE)
-            : def
-                ? `machine '${def.settings.name}' (${collectStateNames(def.state).length} states, ${collectEventIds(def).length} events)`
-                : existsSync(PROJECT_FILE)
-                    ? "file exists but is not a readable definition"
-                    : "file does not exist yet";
+        const summary = [
+            isErdfPath(PROJECT_FILE)
+                ? erdSummary(PROJECT_FILE)
+                : isSqdfPath(PROJECT_FILE)
+                    ? sequenceSummary(PROJECT_FILE)
+                    : isSysdfPath(PROJECT_FILE)
+                        ? systemSummary(PROJECT_FILE)
+                        : def
+                            ? `machine '${def.settings.name}' (${collectStateNames(def.state).length} states, ${collectEventIds(def).length} events)`
+                            : existsSync(PROJECT_FILE)
+                                ? "file exists but is not a readable definition"
+                                : "file does not exist yet",
+            reconcileModeLine(systemHost, PROJECT_FILE),
+        ]
+            .filter(Boolean)
+            .join("\n");
         const bridgeNote = BRIDGE_URL
             ? `bridge: ${bridge?.status ?? "not initialized"} → ${BRIDGE_URL}`
             : "bridge not configured (STATELOOM_BRIDGE_URL unset)";
@@ -899,10 +995,12 @@ function buildServer() {
             ],
         };
     });
-    server.tool("generate_rispec", "Generate a RISE rispec (markdown) from the current state machine. If the SMDF was sourced from a PDE (settings._source.pdeId/pdeFolder), the PDE's intent, directions, and ambiguities are folded in. Pass `intent` to override the desired outcome.", { intent: z.string().optional() }, async ({ intent }) => {
+    server.tool("generate_rispec", "Generate a RISE rispec (markdown) from the current state machine. If the SMDF was sourced from a PDE (settings._source.pdeId/pdeFolder), the PDE's intent, directions, and ambiguities are folded in. Pass `intent` to override the desired outcome. When the active document is a system (.sysdf.json), or `system` names one, the rispec is the whole system's: Creative Intent, Data from its ERDs, Behaviour per machine, each scenario path as a Creative Advancement Scenario (from the replay), and Open questions. Returns markdown; writes nothing.", { intent: z.string().optional(), system: z.string().optional() }, async ({ intent, system }) => {
+        if (system || isSysdfPath(PROJECT_FILE))
+            return systemRispec(systemHost, { system, intent });
         const def = readDef();
         if (!def)
-            return { content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }], isError: true };
+            return { content: [{ type: "text", text: noMachine() }], isError: true };
         const md = generateRispec(def, intent);
         return { content: [{ type: "text", text: md }] };
     });
@@ -929,7 +1027,7 @@ function buildServer() {
             return "no desktop opener available";
         }
     }
-    server.tool("render_diagram", "Draw the current state machine as a picture. Writes the file next to the project document (or at `path`) and returns its absolute path — plus the image itself for png, so it can be looked at without leaving the conversation. Formats: png (raster, needs librsvg/Inkscape/ImageMagick/Chrome on the host), svg (needs nothing), mermaid, ascii. Pass stamp:true to keep every render instead of overwriting one file.", {
+    server.tool("render_diagram", "Draw the current state machine as a picture. Writes the file next to the project document (or at `path`) and returns its absolute path — plus the image itself for png, so it can be looked at without leaving the conversation. Formats: png (raster, needs librsvg/Inkscape/ImageMagick/Chrome on the host), svg (needs nothing), mermaid, ascii. Pass stamp:true to keep every render instead of overwriting one file. An ERD renders as mermaid (<name>.erd.mmd), a sequence as mermaid (<name>.seq.mmd), and a system as one markdown file of its members' mermaid (<name>.sys.md).", {
         format: z.enum(["png", "svg", "mermaid", "ascii"]).optional(),
         path: z.string().optional(),
         scale: z.number().optional(),
@@ -939,10 +1037,14 @@ function buildServer() {
     }, async ({ format, path, scale, theme, stamp, open }) => {
         if (isErdfPath(PROJECT_FILE))
             return erdRender(erdHost, { format, path, stamp });
+        if (isSqdfPath(PROJECT_FILE))
+            return sequenceRender(sequenceHost, { format, path, stamp });
+        if (isSysdfPath(PROJECT_FILE))
+            return systemRender(systemHost, { format, path, stamp });
         const def = readDef();
         if (!def)
             return {
-                content: [{ type: "text", text: `No state machine at ${PROJECT_FILE}.` }],
+                content: [{ type: "text", text: noMachine() }],
                 isError: true,
             };
         const chosen = format ?? "png";
@@ -1006,6 +1108,52 @@ function buildServer() {
         }
     });
     registerErdTools(server, erdHost);
+    registerSequenceTools(server, sequenceHost);
+    registerSystemTools(server, systemHost);
+    // Notes — the same two tools for either document type.
+    server.tool("set_notes", "Save working notes on the active diagram or on one of its shapes — what was said about it, an open question, a decision — so whoever opens the document next (a person or an agent) finds them. Omit `target` for the whole diagram; otherwise `target` is a state name (state machine), an entity name (ERD), a participant name, a message ('9', 'f1.2') or 'fragment N' (sequence), or a member's path (system). The text replaces what was there; an empty string clears it. Notes are kept in the document and are not part of the model: engines and code generation ignore them.", { target: z.string().optional(), notes: z.string() }, async ({ target, notes }) => {
+        if (isErdfPath(PROJECT_FILE))
+            return erdSetNotes(erdHost, target, notes);
+        if (isSqdfPath(PROJECT_FILE))
+            return sequenceSetNotes(sequenceHost, target, notes);
+        if (isSysdfPath(PROJECT_FILE))
+            return systemSetNotes(systemHost, target, notes);
+        const def = readDef();
+        if (!def)
+            return { content: [{ type: "text", text: noMachine() }], isError: true };
+        const holder = target ? findState(def.state, target) : def.settings;
+        if (!holder)
+            return { content: [{ type: "text", text: `State '${target}' not found.` }], isError: true };
+        if (notes.trim())
+            holder.notes = notes;
+        else
+            delete holder.notes;
+        writeDef(def);
+        // "" is how an erased note travels; the far side removes the key.
+        const patch = { notes: notes.trim() ? notes : "" };
+        bridgeEmitPatch([target ? { op: "state.update", name: target, patch } : { op: "settings.update", patch }]);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `${notes.trim() ? "Saved" : "Cleared"} the notes on ${target ? `state '${target}'` : "the diagram"}.`,
+                },
+            ],
+        };
+    });
+    server.tool("get_notes", "Read every note in the active document in one call — the diagram's own first, then each shape that has one. Read them before changing a diagram somebody else has been working on: they are where a person leaves what they were thinking.", {}, async () => {
+        if (isErdfPath(PROJECT_FILE))
+            return erdGetNotes(erdHost);
+        if (isSqdfPath(PROJECT_FILE))
+            return sequenceGetNotes(sequenceHost);
+        if (isSysdfPath(PROJECT_FILE))
+            return systemGetNotes(systemHost);
+        const def = readDef();
+        if (!def)
+            return { content: [{ type: "text", text: noMachine() }], isError: true };
+        const entries = collectNotes(def);
+        return { content: [{ type: "text", text: formatNotes(def.settings.name, PROJECT_FILE, entries) }] };
+    });
     // Resources
     server.resource("definition", "smcraft://definition", async () => {
         const def = readDef();

package/dist/system.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The system half of the MCP server (Spec 82).
+ *
+ * A system (`.sysdf.json`) names the drawings of one thing being built — its
+ * ERDs, its machines, its scenarios — and the actors its scenarios share. The
+ * tools here edit it, check every name that crosses between its members, replay
+ * a scenario through the machines, and reconcile the members from a scenario.
+ *
+ * Reconcile mode (`settings.reconcile`, overridden for a session by
+ * STATELOOM_RECONCILE): in `propose`, a sequence edit reports in one line what
+ * the scenario implies for the other members; in `auto`, the edit applies it —
+ * machines are written and patched live, ERDs and the system are written and
+ * sent whole — and reports in one line what changed.
+ *
+ * Which system: the `system` argument, else the active document when it is a
+ * `.sysdf.json`, else the system that lists the sequence (or member) at hand —
+ * the last one this server created, set or checked, or one beside it — else the
+ * last system. Which sequence: the `sequence` argument, else the active document
+ * when it is a `.sqdf.json`. A sequence no system lists is checked, replayed and
+ * reconciled against the machines (and ERDs) beside it.
+ *
+ * Everything that touches the server's own state comes in through `SystemHost`.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type StateMachineDefinition, type SystemDefinition } from "@miadi/stateloom-protocol";
+import type { Live } from "./live.js";
+export interface SystemHost {
+    /** The active document's absolute path. */
+    projectFile(): string;
+    /** The refusal for a path outside the permitted document root, if any. */
+    outsideRoot(path: string): string | undefined;
+    /** Mirror a document to the server's own room (it is the active document). Best-effort. */
+    emitFull(def: unknown): void;
+    /** Pushes to other rooms: a reconciled machine, an ERD, a view. */
+    live: Live;
+    /** STATELOOM_RECONCILE, when set: wins over every system's own mode for this session. */
+    reconcileOverride(): string | undefined;
+    /** A machine's own V rules — the validator behind validate_definition. */
+    validateMachine(def: StateMachineDefinition): {
+        ruleId: string;
+        message: string;
+    }[];
+    /** A machine's states, events and transitions as markdown, headings at `level` — generate_rispec's content. */
+    machineSpec(def: StateMachineDefinition, level: number): string[];
+    /** The system this server last created, set or checked. */
+    lastSystem(): string | undefined;
+    rememberSystem(path: string): void;
+}
+type ToolResult = {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+};
+export declare function readSystem(path: string): SystemDefinition | null;
+/** One line for set_project_file / get_project_file when the active document is a system. */
+export declare function systemSummary(path: string): string;
+/** The reconcile line for get_project_file: a system's mode, or the mode of the system that lists a sequence. */
+export declare function reconcileModeLine(host: SystemHost, path: string): string | undefined;
+/**
+ * After a sequence edit (sequence.ts `afterEdit`): reconcile the system that
+ * lists it, and return the ONE line the edit's result carries. In auto mode the
+ * changes are applied; in propose mode — or when no system lists the sequence —
+ * they are counted.
+ */
+export declare function reconcileAfterEdit(host: SystemHost, sequencePath: string): Promise<string | undefined>;
+export declare function checkSystemReport(host: SystemHost, args?: {
+    system?: string;
+    sequence?: string;
+}): ToolResult;
+export declare function systemGetDefinition(host: SystemHost): ToolResult;
+export declare function systemLoadDefinition(host: SystemHost, json: string): ToolResult;
+/** Every member's mermaid in one markdown file: `<name>.sys.md` beside the system. */
+export declare function systemRender(host: SystemHost, opts: {
+    format?: string;
+    path?: string;
+    stamp?: boolean;
+}): ToolResult;
+export declare function systemGetNotes(host: SystemHost): ToolResult;
+/** `target` is a member's path (as the system writes it, or absolute); omitted, the whole system. */
+export declare function systemSetNotes(host: SystemHost, target: string | undefined, notes: string): ToolResult;
+export declare function systemRispec(host: SystemHost, args: {
+    system?: string;
+    intent?: string;
+}): ToolResult;
+export declare function registerSystemTools(server: McpServer, host: SystemHost): void;
+export {};