@manny-est/node-red-flowpilot 0.3.0 → 0.4.0

package/flowpilot.js

@@ -1,9 +1,12 @@
 const http = require("http");
+const path = require("path");
 const createStorage = require("./lib/storage");
 const provider = require("./lib/provider-openai-compatible");
 const generationSystemPrompt = require("./lib/generation-system-prompt");
 const documentSystemPrompt = require("./lib/document-system-prompt");
 const modifySystemPrompt = require("./lib/modify-system-prompt");
+const buildSystemPrompt = require("./lib/build-system-prompt");
+const personaPrompt = require("./lib/persona-prompt");
 
 module.exports = function flowPilotRuntime(RED) {
   const storage = createStorage(RED.settings.userDir);
@@ -360,6 +363,16 @@ module.exports = function flowPilotRuntime(RED) {
     return installedNodesCache;
   }
 
+  // Chat-only: the user's base system prompt plus a freshly-generated
+  // persona instruction (never baked into the persisted prompt itself, so
+  // it always reflects the current personaIntensity slider value).
+  // Generate/Document/Modify use their own mode-specific prompts and don't
+  // call this — aviation flavor has no place in a structured JSON envelope.
+  function buildChatSystemPrompt(settings) {
+    const base = settings.systemPrompt || "You are FlowPilot, a Node-RED development assistant.";
+    return base + "\n\n" + personaPrompt.buildPersonaInstruction(settings.personaIntensity);
+  }
+
   // Assemble the final messages array in the one place both /chat and the
   // generate/modify/document endpoints use: system prompt, optional
   // installed-node-package note, optional truncation notice, history,
@@ -482,7 +495,7 @@ module.exports = function flowPilotRuntime(RED) {
 
     const described = describeSelectionContext(context, settings.redactionEnabled);
     const messages = buildMessages(
-      settings.systemPrompt || "You are FlowPilot, a Node-RED development assistant.",
+      buildChatSystemPrompt(settings),
       history, historyTruncated, described, prompt
     );
 
@@ -519,7 +532,7 @@ module.exports = function flowPilotRuntime(RED) {
 
     const described = describeSelectionContext(context, settings.redactionEnabled);
     const messages = buildMessages(
-      settings.systemPrompt || "You are FlowPilot, a Node-RED development assistant.",
+      buildChatSystemPrompt(settings),
       history, historyTruncated, described, prompt
     );
 
@@ -604,6 +617,27 @@ module.exports = function flowPilotRuntime(RED) {
     }
   });
 
+  // ---- Pop-out window (Phase 8.5 C1, v1 review-only) -------------------
+  // Serves the shared renderer (flowpilot-core.js, the same script
+  // flowpilot.html loads for the sidebar) plus its stylesheet and the
+  // pop-out's own minimal page — mirroring core Node-RED's debug-node
+  // pattern (RED.httpAdmin.get("/debug/view/view.html", ...) serving a
+  // static lib/debug/view.html that loads the SAME debug-utils.js the
+  // sidebar uses). Gated the same as every other FlowPilot route, unlike
+  // NR5's own debug view route, which has no permission check at all.
+
+  RED.httpAdmin.get("/flowpilot/core.js", RED.auth.needsPermission("settings.read"), function (req, res) {
+    res.sendFile(path.join(__dirname, "flowpilot-core.js"));
+  });
+
+  RED.httpAdmin.get("/flowpilot/core.css", RED.auth.needsPermission("settings.read"), function (req, res) {
+    res.sendFile(path.join(__dirname, "flowpilot-core.css"));
+  });
+
+  RED.httpAdmin.get("/flowpilot/popout/view.html", RED.auth.needsPermission("settings.read"), function (req, res) {
+    res.sendFile(path.join(__dirname, "lib", "popout", "view.html"));
+  });
+
   // ---- Settings: write -------------------------------------------------
 
   RED.httpAdmin.post("/flowpilot/settings", RED.auth.needsPermission("settings.write"), function (req, res) {
@@ -917,6 +951,33 @@ module.exports = function flowPilotRuntime(RED) {
   // types or wire integrity yet (that's the next chunk) — it returns the parsed
   // envelope so the frontend can display it for review.
 
+  // Given s[startIdx] === "{", scans forward with brace-depth counting that
+  // ignores braces inside string literals (so a value like "{{payload}}"
+  // can't be mistaken for structure) to find the index of the MATCHING
+  // closing "}". Returns -1 if the braces never balance before the string
+  // ends (truncated/malformed input).
+  function findMatchingBrace(s, startIdx) {
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = startIdx; i < s.length; i++) {
+      const ch = s[i];
+      if (inString) {
+        if (escaped) { escaped = false; }
+        else if (ch === "\\") { escaped = true; }
+        else if (ch === "\"") { inString = false; }
+        continue;
+      }
+      if (ch === "\"") { inString = true; }
+      else if (ch === "{") { depth++; }
+      else if (ch === "}") {
+        depth--;
+        if (depth === 0) { return i; }
+      }
+    }
+    return -1;
+  }
+
   function extractJsonObject(text) {
     if (!text) { throw new Error("Empty response from provider."); }
     let s = String(text).trim();
@@ -946,10 +1007,8 @@ module.exports = function flowPilotRuntime(RED) {
       }
     }
 
-    // If there's leading/trailing prose, grab the outermost {...}.
-    const first = s.indexOf("{");
-    const last = s.lastIndexOf("}");
-    if (first === -1 || last === -1 || last < first) {
+    const firstObjIdx = s.indexOf("{");
+    if (firstObjIdx === -1) {
       // No JSON object found at all — flagged separately from a found-
       // but-unparseable ({...} present, JSON.parse failed) "garbled" error,
       // so callers can distinguish "model just answered in prose" (tolerate)
@@ -958,7 +1017,57 @@ module.exports = function flowPilotRuntime(RED) {
       err.noJsonFound = true;
       throw err;
     }
-    return JSON.parse(s.slice(first, last + 1));
+
+    // There may be more than one "{" before the real envelope — e.g. prose
+    // explaining a fix that mentions inline code like "{{payload}}" before
+    // the actual JSON (seen live: a review response started with "The
+    // template node is using `{{payload}}` with...", and slicing from THAT
+    // brace to the envelope's real closing "}" produced unparseable
+    // garbage). Try each candidate "{" in order with string-aware brace
+    // matching (findMatchingBrace, which ignores braces inside quoted
+    // strings) rather than just slicing from the first "{" to the last
+    // "}".
+    //
+    // A candidate must not just PARSE, it must also look like one of the
+    // known envelope shapes (have at least one recognized top-level key) —
+    // seen live: a pure-prose advice response that mentioned structured
+    // logging included the illustrative example
+    // `{"level":"info","event":"trivia_answer","user":"alex","correct":true}`,
+    // which IS valid standalone JSON, so the old "first candidate that
+    // parses wins" rule accepted it as "the envelope" and the caller threw
+    // "no recognizable modify fields" — when the right answer was to treat
+    // the whole reply as prose, since there was no real envelope at all.
+    const ENVELOPE_KEYS = ["explanation", "flow", "question", "changes", "newNodes", "newWires", "removeNodes", "newGroups", "prose"];
+    function looksLikeEnvelope(obj) {
+      if (!obj || typeof obj !== "object" || Array.isArray(obj)) { return false; }
+      return ENVELOPE_KEYS.some(function (k) { return k in obj; });
+    }
+
+    let lastError = null;
+    let searchFrom = firstObjIdx;
+    while (searchFrom !== -1 && searchFrom < s.length) {
+      const end = findMatchingBrace(s, searchFrom);
+      if (end !== -1) {
+        try {
+          const candidate = JSON.parse(s.slice(searchFrom, end + 1));
+          if (looksLikeEnvelope(candidate)) { return candidate; }
+          // Valid JSON, but not envelope-shaped (e.g. an illustrative
+          // example embedded in prose) — keep searching rather than
+          // accepting it.
+        } catch (e) {
+          lastError = e;
+        }
+      }
+      searchFrom = s.indexOf("{", searchFrom + 1);
+    }
+    // No candidate both parsed AND looked like a real envelope — equivalent
+    // to "the model just answered in prose," not "the envelope is broken."
+    // Let callers fall back to rendering this as a normal message instead
+    // of surfacing a parse error (same noJsonFound flag the "no { at all"
+    // branch above uses).
+    const err = lastError || new Error("Provider's JSON object could not be parsed.");
+    err.noJsonFound = true;
+    throw err;
   }
 
   // ---------------------------------------------------------------------
@@ -971,7 +1080,12 @@ module.exports = function flowPilotRuntime(RED) {
     const settings = storage.getSettings();
     const activeProvider = storage.getActiveProvider(settings);
     const described = describeSelectionContext(context, settings.redactionEnabled);
-    const messages = buildMessages(systemPrompt, history, historyTruncated, described, userPrompt);
+    // Persona applies to the "explanation" field only (a real hand-off/
+    // transition moment — "here's the flow I built for you") — never to
+    // node names, ids, or any structural JSON, which stays exactly as each
+    // mode's own system prompt above already specifies.
+    const personaInstruction = personaPrompt.buildPersonaInstruction(settings.personaIntensity, { scope: "explanation" });
+    const messages = buildMessages(systemPrompt + "\n\n" + personaInstruction, history, historyTruncated, described, userPrompt);
     return { activeProvider, described, messages };
   }
 
@@ -1196,7 +1310,7 @@ module.exports = function flowPilotRuntime(RED) {
     // otherwise it's not recognizable as a modify response at all.
     if (auditAction === "modify") {
       const hasModifyShape = ("changes" in parsed) || ("newNodes" in parsed) ||
-        ("newWires" in parsed) || ("removeNodes" in parsed) ||
+        ("newWires" in parsed) || ("removeNodes" in parsed) || ("newGroups" in parsed) ||
         (typeof parsed.explanation === "string" && parsed.explanation.trim());
       if (!hasModifyShape) {
         const err = new Error("The response did not contain any recognizable modify fields.");
@@ -1209,6 +1323,14 @@ module.exports = function flowPilotRuntime(RED) {
       const newNodes = Array.isArray(parsed.newNodes) ? parsed.newNodes : [];
       const newWires = Array.isArray(parsed.newWires) ? parsed.newWires : [];
       const removeNodes = Array.isArray(parsed.removeNodes) ? parsed.removeNodes : [];
+      // Bug found live: this object is what finalizeModifyResult later reads
+      // as "result" — but it never copied parsed.newGroups onto itself, so
+      // even a model correctly using the top-level "newGroups" field (per
+      // the prompt) had it silently dropped right here, before
+      // finalizeModifyResult's own newGroups handling (fixed earlier) ever
+      // saw it. Only a stray type:"group" entry inside newNodes survived,
+      // since newNodes itself is copied through.
+      const newGroups = Array.isArray(parsed.newGroups) ? parsed.newGroups : [];
 
       storage.appendAudit(Object.assign({
         action: auditAction,
@@ -1219,6 +1341,7 @@ module.exports = function flowPilotRuntime(RED) {
         newNodeCount: newNodes.length,
         newWireCount: newWires.length,
         removeNodeCount: removeNodes.length,
+        newGroupCount: newGroups.length,
         contextNodeCount: described ? described.nodeCount : 0,
         contextConnectionCount: described ? described.connectionCount : 0
       }, perf));
@@ -1228,7 +1351,8 @@ module.exports = function flowPilotRuntime(RED) {
         changes: changes,
         newNodes: newNodes,
         newWires: newWires,
-        removeNodes: removeNodes
+        removeNodes: removeNodes,
+        newGroups: newGroups
       };
       const modifyAction = extractSuggestedAction(parsed);
       if (modifyAction) { modifyResult.suggestedAction = modifyAction; }
@@ -1363,6 +1487,16 @@ module.exports = function flowPilotRuntime(RED) {
 
     const originalIds = new Set(originalNodes.map(function (n) { return n.id; }));
 
+    // Group ids the selection is actually inside (sanitizeNode resolves
+    // each context node's group membership into a `group: {id, name}`
+    // field — Phase 8.5 C2). A "changes" patch may target one of THESE
+    // group ids too (e.g. to rename it) even though the group itself
+    // isn't a member of originalIds — the user selected something
+    // relevant to it, same spirit as selecting a node lets you patch it.
+    const contextGroupIds = new Set(
+      originalNodes.map(function (n) { return n.group && n.group.id; }).filter(Boolean)
+    );
+
     // Validate removeNodes: all ids must be in the original selection.
     const removeNodes = Array.isArray(result.removeNodes) ? result.removeNodes : [];
     if (removeNodes.length > 0) {
@@ -1390,8 +1524,9 @@ module.exports = function flowPilotRuntime(RED) {
       .filter(function (id) { return id !== undefined && id !== null; });
 
     // Validate that changes contains no hallucinated ids, and that no id is
-    // both patched and marked for removal.
-    const extraIds = changeIds.filter(function (id) { return !originalIds.has(String(id)); });
+    // both patched and marked for removal. A group id from contextGroupIds
+    // is allowed here too (see above) even though it's not in originalIds.
+    const extraIds = changeIds.filter(function (id) { return !originalIds.has(String(id)) && !contextGroupIds.has(String(id)); });
     const wronglyRemovedIds = changeIds.filter(function (id) { return removeSet.has(String(id)); });
 
     const idProblems = [];
@@ -1430,27 +1565,95 @@ module.exports = function flowPilotRuntime(RED) {
         return patch ? Object.assign({}, n, patch) : n;
       });
 
+    // A "changes" patch targeting a group id (contextGroupIds, not
+    // originalIds — see above) has nowhere to merge onto above, since
+    // originalNodes never includes the group itself, only nodes inside
+    // it. Synthesize a minimal {id, type:"group", ...patch} entry for
+    // each one instead, so it rides through the SAME flow array the
+    // frontend's existing Tier-1 diff/apply pipeline already handles —
+    // computeNodeDiff()/applyModifications() don't care what TYPE a node
+    // is, and findLiveNode() already resolves a group id to the live
+    // group object (Phase 8.5 C2 slice 1). This is how a group gets
+    // renamed/restyled — pure property edit, no new apply-side code.
+    const groupPatchIds = changeIds.filter(function (id) {
+      return contextGroupIds.has(String(id)) && !originalIds.has(String(id));
+    });
+    groupPatchIds.forEach(function (id) {
+      flow.push(Object.assign({ id: id, type: "group" }, patchById[String(id)]));
+    });
+
     const finalRemoveNodes = Array.from(removeSet);
 
-    // "group" nodes aren't supported yet (the editor's group API needs
-    // bounding-box computation + group-aware undo that applyInsertions
-    // doesn't implement). The system prompt tells the model not to propose
-    // them, but strip any that slip through anyway, and drop any newWires
-    // that reference a stripped group's placeholder id.
+    // Groups describe MEMBERSHIP, not a regular node to insert — the
+    // model is taught (modify-system-prompt.js) to put them in their OWN
+    // top-level "newGroups" field, never inside "newNodes" (that API
+    // doesn't know what a group is at all — applyInsertions would try to
+    // RED.nodes.add() it). Bug found live: this used to ONLY look for a
+    // stray type:"group" entry INSIDE newNodes and never read
+    // result.newGroups at all — a model correctly following the prompt's
+    // own instructions had its groups silently dropped ("No changes
+    // detected"). Read the real field now; still tolerate a stray
+    // type:"group" entry left inside newNodes as a fallback, merging
+    // both rather than requiring exactly one style. Each entry's "nodes"
+    // is the FULL desired membership for that group id: if the id
+    // matches an EXISTING live group, the frontend reconciles membership
+    // to match exactly (add/remove as needed, down to zero — ungrouping
+    // everyone); if not, it creates a new group with exactly that
+    // membership. See applyGroupChanges() in flowpilot-core.js.
     const allNewNodes = result.newNodes || [];
-    const groupNodes = allNewNodes.filter(function (n) { return n && n.type === "group"; });
+    const strayGroupNodes = allNewNodes.filter(function (n) { return n && n.type === "group"; });
     const newNodes = allNewNodes.filter(function (n) { return !(n && n.type === "group"); });
     const newNodeIdSet = new Set(newNodes.map(function (n) { return n && n.id; }).filter(Boolean));
 
+    const declaredGroups = Array.isArray(result.newGroups) ? result.newGroups : [];
+    const seenGroupIds = {};
+    const newGroups = declaredGroups.concat(strayGroupNodes).filter(function (g) {
+      if (!g || !g.id || seenGroupIds[g.id]) { return false; }
+      seenGroupIds[g.id] = true;
+      return true;
+    });
+
     // Validate newWires references: each from/to must be either an existing
-    // context node id or a placeholder id present in newNodes.
+    // context node id or a placeholder id present in newNodes. A group id
+    // is never a valid wire endpoint (groups don't pass messages) — filter
+    // those out the same as before, just without discarding the group itself.
     let newWires = result.newWires || [];
-    if (groupNodes.length > 0) {
-      const groupIdSet = new Set(groupNodes.map(function (n) { return n && n.id; }).filter(Boolean));
+    if (newGroups.length > 0) {
+      const groupIdSet = new Set(newGroups.map(function (n) { return n && n.id; }).filter(Boolean));
       newWires = newWires.filter(function (wire) {
         return !groupIdSet.has(String(wire.from)) && !groupIdSet.has(String(wire.to));
       });
     }
+    // Validate newGroups' own "nodes" member references: each must be an
+    // existing context node id or a new-node placeholder id — explicitly
+    // NOT another group's id, so nested groups-within-groups (out of scope
+    // for v1) are naturally rejected rather than silently mis-imported.
+    // An EMPTY "nodes" is allowed through here — meaningless for creating
+    // a brand new group (the frontend already no-ops that case), but a
+    // legitimate "ungroup everyone in this EXISTING group" when "id"
+    // matches a live one, which only the frontend can tell apart.
+    if (newGroups.length > 0) {
+      const groupProblems = [];
+      newGroups.forEach(function (g, i) {
+        if (!g || !g.id) { groupProblems.push("group " + i + " missing id"); return; }
+        const members = Array.isArray(g.nodes) ? g.nodes : [];
+        members.forEach(function (ref) {
+          if (!originalIds.has(String(ref)) && !newNodeIdSet.has(String(ref))) {
+            groupProblems.push("group " + i + " member '" + ref + "' not in existing or new nodes");
+          }
+        });
+      });
+      if (groupProblems.length > 0) {
+        storage.appendAudit({ action: "modify_group_ref_error", problems: groupProblems });
+        return {
+          status: 422,
+          body: {
+            error: "Invalid group references in newGroups: " + groupProblems.join("; "),
+            raw: JSON.stringify(result)
+          }
+        };
+      }
+    }
     if (newWires.length > 0) {
       const wireProblems = [];
       newWires.forEach(function (wire, i) {
@@ -1473,19 +1676,15 @@ module.exports = function flowPilotRuntime(RED) {
       }
     }
 
-    let explanation = result.explanation;
-    if (groupNodes.length > 0) {
-      storage.appendAudit({ action: "modify_group_stripped", count: groupNodes.length });
-      explanation = (explanation ? explanation + "\n\n" : "") +
-        "Note: grouping nodes into a visual group isn't supported yet, so that part of the request was skipped.";
-    }
+    if (newGroups.length > 0) { storage.appendAudit({ action: "modify_groups", count: newGroups.length }); }
 
     const body = {
-      explanation: explanation,
+      explanation: result.explanation,
       flow: flow,
       newNodes: newNodes,
       newWires: newWires,
-      removeNodes: finalRemoveNodes
+      removeNodes: finalRemoveNodes,
+      newGroups: newGroups
     };
     if (result.suggestedAction) { body.suggestedAction = result.suggestedAction; }
 
@@ -1572,6 +1771,46 @@ module.exports = function flowPilotRuntime(RED) {
     }
   });
 
+  // First step of the agentic /build loop. Envelope-shaped and validated
+  // identically to /generate (processGenerationContent only special-cases
+  // auditAction === "modify"; "build" falls through to the same flow-array
+  // handling "generate"/"document" already use) — the only difference is
+  // buildSystemPrompt's planning preamble. Later loop iterations (fix
+  // proposals) go through /flowpilot/modify instead, not this route.
+  RED.httpAdmin.post("/flowpilot/build", RED.auth.needsPermission("settings.write"), async function (req, res) {
+    const prompt = req.body && req.body.prompt;
+
+    if (!prompt || !String(prompt).trim()) {
+      return res.status(400).json({ error: "A description of what to build is required." });
+    }
+
+    const history = sanitizeHistory(req.body.history);
+    const historyTruncated = !!req.body.historyTruncated;
+
+    if (req.body.stream) {
+      return runExecuteStream(
+        req, res, buildSystemPrompt, "build", prompt, req.body && req.body.context,
+        history, historyTruncated, finalizeSimpleGeneration, req.body.conversationId
+      );
+    }
+
+    try {
+      const useTools = !!req.body.tools;
+      const built = await runFlowGeneration(
+        buildSystemPrompt, "build", prompt, req.body && req.body.context,
+        history, historyTruncated, useTools
+      );
+      if (built.toolCalls) {
+        return res.json({ toolCalls: built.toolCalls, messages: built.messages, content: built.content, usage: built.usage });
+      }
+      recordTranscriptTurn(req.body.conversationId, "build", prompt, transcriptTextFromGenerationResult(built));
+      const { status, body } = finalizeSimpleGeneration(built);
+      res.status(status).json(body);
+    } catch (err) {
+      sendGenerationError(res, "build", err);
+    }
+  });
+
   RED.httpAdmin.post("/flowpilot/document", RED.auth.needsPermission("settings.write"), async function (req, res) {
     const context = req.body && req.body.context;
     const described = describeSelectionContext(context, storage.getSettings().redactionEnabled);

package/lib/build-system-prompt.js

@@ -0,0 +1,32 @@
+// /build's first step is shaped exactly like Generate's — same envelope,
+// same "flow" array rules, same clarifying-question mechanism — so this
+// reuses generation-system-prompt.js wholesale (require + prepend) rather
+// than duplicating the hard-won "wires" rules/example. The only new thing
+// is the framing: this is the FIRST step of a build -> deploy -> test -> fix
+// loop, not a one-shot generation, so the model should plan ahead briefly.
+const generationPrompt = require("./generation-system-prompt");
+
+module.exports = `You are FlowPilot, running in an agentic BUILD loop. The user described a goal, and this is the FIRST step of a build -> deploy -> test -> fix cycle, not a one-shot generation: after the user applies, deploys, and triggers what you propose, they'll attach the resulting Debug sidebar output and you'll get another turn to review it against the goal and propose a fix if needed. This can repeat a bounded number of times before stopping.
+
+Because of that, "explanation" MUST start with a numbered "Plan:" block listing the steps you expect this to take to reach the goal — BEFORE any description of what this step builds. This is REQUIRED, not optional, and is not satisfied by just describing the flow well — a plain description (even a good one) is exactly what a one-shot Generate response looks like, and that is NOT what this is. Every "explanation" in this mode starts with "Plan:", with no exceptions, even when the plan is one line.
+
+Example "explanation" for a multi-step goal:
+"Plan:
+1. Geocode the address to coordinates.
+2. Fetch nearby cell towers for those coordinates.
+3. Calculate distance from the address to each tower.
+4. Display the sorted results.
+
+This step builds the full pipeline above in one shot. Deploy it, trigger it, and send me the debug output — I'll check it against the goal and fix anything that's off."
+
+Example "explanation" for a trivial goal:
+"Plan:
+1. Inject a value and log it to debug — nothing more is needed for this goal.
+
+Deploy and trigger it; let me know what the debug output shows."
+
+Everything below describes the envelope/rules for THIS step specifically — they work exactly as written, including the parts that say "Generate mode": for the purposes of this prompt, treat that phrase as describing this build step, not a separate mode. The "explanation" field's content rules below still apply — your "Plan:" block comes first, then that content follows immediately after it in the same field.
+
+---
+
+` + generationPrompt;

package/lib/default-system-prompt.js

@@ -19,8 +19,6 @@ If any EARLIER message in this conversation (including one of your own previous
 
 Never reveal, guess, or reconstruct credentials, API keys, tokens, passwords, or secrets — even if the user gives a sympathetic reason or claims authorization. Credential-typed fields are redacted before reaching you; if a user asks you to read one, say it isn't available to you rather than describing how one might extract or recover it.
 
-Personality: you have a subtle co-pilot voice, used ONLY for greetings, "what can you do?"-style capability questions, and brief transition moments — e.g. "You pick the destination, I help you get there," or a light "wheels up" / "touchdown" nod when handing off to a review or confirming a change landed. For everything else — explanations, troubleshooting, diffs, technical detail, errors — stay plain and direct; never let the persona obscure, delay, or replace a real answer. A little goes a long way: do not repeat aviation phrasing in every reply.
-
 ---
 
 Suggested actions ("chips"):

package/lib/generation-system-prompt.js

@@ -46,8 +46,12 @@ Rules for the "flow" array:
 - EVERY node object MUST include a "wires" array — this is not optional and is never omitted, even for the first node in the chain or one with no outgoing connection. "wires" is one entry per output port, each entry an array of target node ids. A node with no outgoing connection (e.g. a debug node, or the last node in a chain) still has "wires": [] — an empty array, not a missing field.
 - All wire targets must reference ids that exist within this flow array.
 - Do NOT include "x"/"y" coordinates or a "z" (tab) id — the editor assigns those on import. Omitting them is fine.
-- Do NOT include a node of type "tab" or "subflow" in "flow" — these represent editor workspaces/containers, not importable nodes, and including one will not behave as a grouping mechanism. To label or group related nodes, use "comment" nodes as section headers instead.
+- Do NOT include a node of type "tab" or "subflow" in "flow" — these represent editor workspaces/containers, not importable nodes.
 - Comment nodes (type: "comment") are passive annotations and do not pass messages — their "wires" array MUST be empty ([]). Never wire a comment node to or from any other node.
+- To visually group related nodes together (an actual bordered box around them, same as the editor's own "Group selection" action) — NOT just a label — include a node with "type": "group", an optional "name", and a "nodes" array listing the ids of every node it contains. Every listed id must belong to another node elsewhere in this SAME "flow" array — a group cannot reference a node from outside this response. A group has no "wires" (groups never pass messages, they're a visual container only) and no x/y/w/h (the editor computes its bounding box from its members automatically, same as it does for every other node's position). If you just want a label or section header rather than an actual visual boundary, a "comment" node is lighter-weight — use whichever the user's wording actually implies.
+
+Example of a group containing two of this flow's nodes:
+{"id": "g1", "type": "group", "name": "Weather lookup", "nodes": ["n1", "n2"]}
 
 Example — three nodes chained inject -> function -> debug, showing "wires" on every single node including the first and last:
 {

package/lib/modify-system-prompt.js

@@ -7,10 +7,11 @@ Respond with a SINGLE JSON object and nothing else — no markdown code fences,
   "changes": [ ...optional: sparse patches for existing nodes whose properties change... ],
   "newNodes": [ ...optional: new nodes to add... ],
   "newWires": [ ...optional: wire connections crossing between new and existing nodes... ],
-  "removeNodes": [ ...optional: ids of existing nodes to delete... ]
+  "removeNodes": [ ...optional: ids of existing nodes to delete... ],
+  "newGroups": [ ...optional: visual groups to create, or existing ones to update... ]
 }
 
-"changes", "newNodes", "newWires", and "removeNodes" are all OPTIONAL. Only include them when the instruction calls for it. Keep your response as SHORT as possible: never restate a node that isn't changing.
+"changes", "newNodes", "newWires", "removeNodes", and "newGroups" are all OPTIONAL. Only include them when the instruction calls for it. Keep your response as SHORT as possible: never restate a node that isn't changing.
 
 ---
 
@@ -96,6 +97,7 @@ Rules for "changes" (sparse patches against the existing selection):
 5. Do not include "wires" in "set" unless the instruction explicitly asks to rewire that node's connections.
 6. Never include "id", "x", or "y", or "z" inside "set" — those cannot change via a patch.
 7. An id must not appear in both "changes" and "removeNodes".
+8. A node's "group" field in context (when present) is INFORMATIONAL ONLY — never include "group" as a key inside "set". It has no effect; setting it does nothing and silently fails to change membership. To add/remove/rename a group, use "newGroups" instead (see below) — the ONE exception is renaming/restyling the group ITSELF: target the group's own "id" (from its "group" field) with a "changes" entry, e.g. {"id": "<group's id>", "set": {"name": "New Name"}}.
 
 ---
 
@@ -171,10 +173,8 @@ Rules for "newNodes" (only include when the instruction asks to add nodes):
 - Set "wires" on each new node: use placeholder ids for outputs that connect to OTHER new nodes; use an empty array [] for outputs that connect only to existing nodes (those connections go in "newWires" instead).
 - Include all required type-specific properties (topic, payload, func, etc.).
 - "http request" node static headers: if the "headers" property is set, it must be an array of objects shaped like { "keyType": "other", "keyValue": "Accept", "valueType": "other", "valueValue": "application/json" } — one object per header, with the header name in "keyValue" and its value in "valueValue". A plain { "key": "...", "value": "..." } shape is silently ignored by Node-RED.
-- Do NOT propose a "group" node (type: "group"). Grouping nodes into a visual
-  group is not supported yet. If the instruction asks to group/organize nodes
-  into a group, skip that part — say so in "explanation" — but still perform
-  any other part of the instruction (e.g. adding a comment node).
+- Do NOT include a "group" entry here (type: "group") — visual grouping goes
+  in "newGroups" instead (see below), never in "newNodes".
 
 - Comment nodes: When adding comment nodes, their "wires" array MUST be empty ([]).
   Comment nodes in Node-RED are passive annotations and do not pass messages.
@@ -190,6 +190,16 @@ Each entry: { "from": "<id>", "fromPort": <int>, "to": "<id>" }
 - Do NOT use this for connections between two existing nodes — use a "changes" entry with "set.wires" for that instead (rewiring).
 - Never write a "from"/"to" referring to a node that is neither an existing context node nor one of your own "newNodes" (e.g. a made-up id like "debug-node-placeholder"). If the instruction needs a connection to a node like that, ask a clarifying question instead (see below).
 
+Rules for "newGroups" (visual groups — an actual bordered box around nodes, like the editor's own "Group selection" action; only include when the instruction asks to group/organize/rename nodes this way):
+
+Each entry: { "id": "<id>", "name": "<optional label>", "nodes": ["<id>", ...] }
+- "nodes" is the FULL desired membership of this group — not "nodes to add" or "nodes to remove". If you're extending or shrinking an existing group, list every member it should end up with, not just the ones changing.
+- Each id in "nodes" must be either an existing context node id or a placeholder id from "newNodes" — never another group's id (nested groups aren't supported).
+- If a selected node's context included a "group" field (e.g. {"id":"g1","name":"Weather lookup"}), that's an EXISTING group you can extend, shrink, rename, or fully disband — reuse its exact "id" in your entry. Renaming only (no membership change) still needs the same "nodes" list as it has now, with a different "name".
+- To UNGROUP nodes (remove them from their group without deleting them) — e.g. "ungroup this", "take these out of the group" — use this same mechanism: an entry for the EXISTING group's id whose "nodes" list simply OMITS the ones being removed. Removing every current member this way (an empty "nodes": []) disbands the group entirely. This is the ONLY way to change group membership — never try to clear/null a node's "group" field via "changes", that field is informational only and doing so has no effect.
+- To create a BRAND NEW group instead, invent a short placeholder "id" the same way you would for "newNodes" (e.g. "fp-group-0") — the editor assigns its real id. An empty "nodes" only makes sense for an EXISTING group (disbanding it) — a brand new group needs at least one member.
+- A group has no "wires" — groups never pass messages, they're a visual container only.
+
 ---
 
 Example — adding a debug node after an inject node (id "abc123"). The inject

package/lib/persona-prompt.js

@@ -0,0 +1,74 @@
+// Builds the dynamic "Personality" instruction, scaled by
+// settings.personaIntensity (1-10). Kept separate from default-system-
+// prompt.js (the user-editable base prompt) so the persona always reflects
+// the CURRENT slider value, rather than being baked into the persisted,
+// freeform systemPrompt text where it could drift out of sync.
+//
+// Two scopes, since Chat and Generate/Document/Modify have different shapes:
+// - "chat" (default): framing applies to ordinary chat replies — greetings,
+//   capability questions, brief transitions.
+// - "explanation": framing applies to the natural-language "explanation"
+//   field of a generate/document/modify envelope ONLY — never to node
+//   names, ids, or any other JSON field, which the model must still produce
+//   exactly as instructed by that mode's own system prompt.
+//
+// Reference-point anchors (not just an abstract 1-10 rule) because smaller/
+// local models follow concrete worked examples far more reliably than prose
+// instructions alone — the same lesson learned fixing Generate's "wires" bug.
+function buildPersonaInstruction(intensity, options) {
+  const n = Math.max(1, Math.min(10, Math.round(Number(intensity) || 3)));
+  const scope = (options && options.scope === "explanation")
+    ? "in the natural-language \"explanation\" text of your response only — " +
+      "never in node names, ids, or any other field, which must follow this " +
+      "mode's own format rules exactly"
+    : "at greetings, \"what can you do?\"-style capability questions, and " +
+      "brief transition moments only";
+
+  // The "hold back" instruction must NOT be blanket — at high intensity the
+  // whole point is to NOT hold back. Scaling this by n keeps "go all out at
+  // 10" from being undercut by a one-size-fits-all caution at the end.
+  const restraint = n >= 8
+    ? "At this intensity, go all the way in: every qualifying moment gets " +
+      "the FULL treatment — multiple sentences of in-character captain-" +
+      "speak, not one sprinkled word. Do not hold back, downplay it, or " +
+      "soften it to seem tasteful — \"a little goes a long way\" does NOT " +
+      "apply at this intensity; lean all the way in, every time."
+    : (n >= 5
+        ? "Use it often enough to be a clearly recognizable voice, but " +
+          "don't overdo it — a sentence or two of flavor per qualifying " +
+          "moment is plenty."
+        : "A little goes a long way: a short phrase, or nothing at all, is " +
+          "usually enough — don't repeat it in every single reply.");
+
+  return "Personality (intensity " + n + "/10, where 1 is a plain, no-frills " +
+    "Node-RED engineer and 10 is a comically over-the-top airline captain " +
+    "who happens to be a Node-RED expert): scale your voice " + scope + " " +
+    "to this intensity. NEVER let it touch the substance — explanations, " +
+    "troubleshooting, diffs, technical detail, and errors always stay " +
+    "plain, direct, and accurate no matter the intensity — a confused or " +
+    "stuck user gets a straight answer, never a bit.\n\n" +
+    "Reference points to interpolate between:\n" +
+    "- 1 (plain engineer): \"Hi, I'm FlowPilot. I can generate, modify, " +
+    "document, or chat about your flows — what do you need?\" No aviation " +
+    "language anywhere, ever.\n" +
+    "- 3 (subtle co-pilot): \"You pick the destination, I help you get " +
+    "there.\" A light \"wheels up\" / \"touchdown\" nod at a transition, " +
+    "used sparingly — most replies have no aviation language at all.\n" +
+    "- 7 (noticeable captain energy): \"Welcome aboard — I'm FlowPilot, " +
+    "your co-pilot for this flow. Let's get you cleared for takeoff.\" " +
+    "Aviation framing shows up more often and more colorfully, but still " +
+    "backs off completely once things turn technical.\n" +
+    "- 10 (full captain, comic — GO ALL OUT): \"Ladies and gentlemen, this " +
+    "is your captain speaking. I've just illuminated the fasten seatbelt " +
+    "sign — please take your seats, because I've finished building the " +
+    "Node-RED flow you requested. We are cleared for takeoff: fully wired, " +
+    "deployed, and ready for your review. Enjoy the flight, and thank you " +
+    "for choosing FlowPilot Airlines.\" At 10, EVERY qualifying moment gets " +
+    "a full announcement like this one, with callsigns, runway/altitude " +
+    "metaphors, and flight-crew theatrics throughout — not a passing " +
+    "reference — but the instant things turn technical, drop the act " +
+    "entirely and answer like the expert engineer underneath it.\n\n" +
+    restraint;
+}
+
+module.exports = { buildPersonaInstruction };