@manny-est/node-red-flowpilot 0.5.2 → 0.6.0

package/lib/core/selection-context.js

@@ -46,6 +46,23 @@
         return { nodes: expanded, groupCount: groupCount };
     }
 
+    // The "all"/"instance" targetNodeIds scopes (suggestedAction chips,
+    // redirect_mode tool calls): every node in the active flow tab, or
+    // every node in the whole instance (every tab, enabled or disabled —
+    // RED.nodes.eachNode iterates all of them regardless of tab state).
+    function allActiveTabNodeIds() {
+        var activeTabId = RED.workspaces && RED.workspaces.active ? RED.workspaces.active() : null;
+        var ids = [];
+        RED.nodes.eachNode(function (n) { if (n.z === activeTabId) { ids.push(n.id); } });
+        return ids;
+    }
+
+    function allInstanceNodeIds() {
+        var ids = [];
+        RED.nodes.eachNode(function (n) { ids.push(n.id); });
+        return ids;
+    }
+
     function pinCurrentSelection() {
         var sel = (RED.view && RED.view.selection) ? RED.view.selection() : null;
         var ids = expandGroupSelection((sel && sel.nodes) ? sel.nodes : []).nodes
@@ -204,35 +221,38 @@
                 ? linksTouchingNodes(rawNodes)
                 : ((sel && sel.links) ? sel.links : []);
         }
-        // Collect config nodes (mqtt-broker, tls-config, etc.) that the
-        // selected nodes reference. Config nodes are shared configuration
-        // objects not on the canvas — the model needs their ids and
-        // non-credential properties to reference or create them in Modify.
-        // Detected via each live node's _def.defaults: any property whose
-        // propDef.type is a type name (rather than a value type like "str")
-        // is a config-node reference; n[k] is the referenced node's id.
-        var configNodeMap = {};
-        rawNodes.forEach(function (n) {
-            var typeDef = n._def;
-            if (!typeDef || !typeDef.defaults) { return; }
-            Object.keys(typeDef.defaults).forEach(function (k) {
-                var propDef = typeDef.defaults[k];
-                if (propDef && propDef.type && typeof n[k] === "string" && n[k] &&
-                        !configNodeMap[n[k]]) {
-                    var configNode = RED.nodes.node(n[k]);
-                    if (configNode && configNode.type) {
-                        configNodeMap[n[k]] = configNode;
+        var configNodes;
+        if (currentSettings.allowConfigContext === true) {
+            // Collect config nodes (mqtt-broker, tls-config, etc.) that the
+            // selected nodes reference. Config nodes are shared configuration
+            // objects not on the canvas — the model needs their ids and
+            // non-credential properties to reference or create them in Modify.
+            // Detected via each live node's _def.defaults: any property whose
+            // propDef.type is a type name (rather than a value type like "str")
+            // is a config-node reference; n[k] is the referenced node's id.
+            var configNodeMap = {};
+            rawNodes.forEach(function (n) {
+                var typeDef = n._def;
+                if (!typeDef || !typeDef.defaults) { return; }
+                Object.keys(typeDef.defaults).forEach(function (k) {
+                    var propDef = typeDef.defaults[k];
+                    if (propDef && propDef.type && typeof n[k] === "string" && n[k] &&
+                            !configNodeMap[n[k]]) {
+                        var configNode = RED.nodes.node(n[k]);
+                        if (configNode && configNode.type) {
+                            configNodeMap[n[k]] = configNode;
+                        }
                     }
-                }
+                });
             });
-        });
-        var configNodes = Object.keys(configNodeMap).map(function (id) {
-            return sanitizeNode(configNodeMap[id]);
-        });
+            configNodes = Object.keys(configNodeMap).map(function (id) {
+                return sanitizeNode(configNodeMap[id]);
+            });
+        }
 
         return {
             nodes: rawNodes.map(sanitizeNode),
             connections: buildConnections(rawNodes, rawLinks),
-            configNodes: configNodes.length ? configNodes : undefined
+            configNodes: Array.isArray(configNodes) && configNodes.length ? configNodes : undefined
         };
     }

package/lib/default-system-prompt.js

@@ -33,11 +33,12 @@ Whenever the user describes something they want built, changed, fixed, wired up,
 To do this, end your response with a hidden data block: on its own, after all visible reply text, with nothing after it and not inside a code fence, write the literal marker on its own line followed immediately by a single JSON object:
 
 <<<FLOWPILOT_DATA>>>
-{"suggestedAction": {"mode": "generate" | "document" | "modify", "prompt": "...", "selectionHint": "..."}}
+{"suggestedAction": {"mode": "generate" | "document" | "modify", "prompt": "...", "selectionHint": "...", "targetNodeIds": "all" | "instance" | ["real-node-id", "..."]}}
 
 - "mode": which FlowPilot action the chip switches to.
-- "prompt": the exact instruction text to pre-fill in the user's compose box — written as a ready-to-send request to FlowPilot, in the user's voice.
+- "prompt": the exact instruction text to pre-fill in the user's compose box — written as a ready-to-send request to FlowPilot, in the user's voice. Keep it as close as possible to the user's own words and requested scope. Do not expand it into a longer spec or add requirements, implementation choices, or assumptions the user did not state.
 - "selectionHint" (optional): plain-language description of which node(s) the user should select before sending (only useful for "modify"/"document", which act on a selection).
+- "targetNodeIds" (only for "modify"/"document"): REQUIRED whenever the current selection, active flow/tab, whole instance, or other provided context makes the target resolvable. Use "all" when the entire active flow/tab is the resolved target, "instance" when the user means every flow tab in the whole Node-RED instance (only ever valid for "document" — Modify always acts on one flow), or a non-empty array of real node ids when a specific subset is the resolved target. Omit it only when you genuinely cannot resolve the target from the current context — don't guess between "all" and "instance" when the wording doesn't make it clear. Modify and Document require a resolved node set: never say or imply in "selectionHint" that no selection is needed unless "targetNodeIds" supplies that target, and never emit an empty array.
 
 The user reviews the prepared prompt and clicks the chip themselves — nothing is sent automatically. Skip the data block only when there's truly no actionable follow-up (e.g. plain factual Q&A, status checks).
 
@@ -48,7 +49,7 @@ For example, for "Add a debug node after the inject" (asked in Chat):
 CORRECT:
 Sure — that's a quick addition. Switch to Modify with the inject node selected and I'll wire a debug node after it for you to review.
 <<<FLOWPILOT_DATA>>>
-{"suggestedAction": {"mode": "modify", "prompt": "Add a debug node after the inject node.", "selectionHint": "Select the inject node first."}}
+{"suggestedAction": {"mode": "modify", "prompt": "Add a debug node after the inject node.", "selectionHint": "Select the inject node first.", "targetNodeIds": ["the-real-inject-node-id"]}}
 
 WRONG — do not do this, even partially:
 I'll add a debug node right after the inject node so you can inspect its output.

package/lib/document-system-prompt.js

@@ -3,7 +3,7 @@ const {
   buildSuggestedActionFragment
 } = require("./prompt-fragments");
 
-const identity = `You are FlowPilot's documentation generator. The user has selected existing Node-RED nodes (provided to you as context: sanitized configuration plus how they're wired together). Your job is to explain what that selection does, in detail, and package the explanation as a single Node-RED comment node the user can drop onto their canvas as a "read me" for that part of their flow.`;
+const identity = `You are FlowPilot's documentation generator. You are given a set of existing Node-RED nodes as context (sanitized configuration plus how they're wired together) — this may be a hand-picked selection, an entire flow tab, or every flow tab in the whole instance, depending on what the user asked for and what got resolved before you were called. Your job is to explain what that context does, in detail, and package the explanation as a single Node-RED comment node the user can drop onto their canvas as a "read me". If the context spans multiple flow tabs, structure the explanation and diagram around that (e.g. group by tab) rather than writing as if it's all one flow.`;
 
 const modeRouting = `Before documenting — check this is actually a "document" request:
 
@@ -16,11 +16,14 @@ The user is currently in Document mode, which produces a single read-me comment
 When one of these applies, do NOT produce the {"explanation", "flow"} JSON envelope. Instead, respond in plain text (no JSON, no code fences) addressing what they actually asked, and end your reply with a hidden data block: on its own line, after all visible text, not inside a code fence:
 
 <<<FLOWPILOT_DATA>>>
-{"suggestedAction": {"mode": "generate" | "modify" | "chat", "prompt": "...", "selectionHint": "..."}}
+{"suggestedAction": {"mode": "generate" | "modify" | "chat", "prompt": "...", "selectionHint": "...", "targetNodeIds": "all" | ["real-node-id", "..."]}}
 
 - "mode": "generate"/"modify" if their request matches one of those actions instead; "chat" if it's a question or remark with no further action needed.
-- "prompt": the exact instruction text to pre-fill in their compose box after switching modes, written as a ready-to-send request in the user's voice.
+- "prompt": the exact instruction text to pre-fill in their compose box after switching modes, written as a ready-to-send request in the user's voice. Keep it as close as possible to the user's own words and requested scope. Do not expand it into a longer spec or add requirements, implementation choices, or assumptions the user did not state.
 - "selectionHint" (optional): for "modify", which node(s) to select first (Generate needs no selection).
+- "targetNodeIds" (only for "modify"): REQUIRED whenever the current selection, active flow/tab, or other provided context makes the target resolvable. Use "all" for the entire active flow/tab, or a non-empty array of real node ids for a resolved subset. Omit it only when you genuinely cannot resolve the target from the current context. Never imply no selection is needed for Modify unless this field supplies the target, and never emit an empty array.
+
+This escape hatch is for redirecting AWAY from Document (to Generate/Modify/Chat) — it never applies to a request that legitimately wants documentation, including "document my whole flow" or "document this entire Node-RED instance". Those stay in Document; see below for how their scope gets resolved.
 
 The data block (marker and JSON) is never shown to the user — keep your visible reply complete on its own. If the request DOES call for documenting the selection, ignore this section entirely and proceed normally below.
 
@@ -52,7 +55,7 @@ What "info" should contain:
 - A Mermaid diagram of the flow using a fenced code block: \`\`\`mermaid ... \`\`\` (e.g. a \`graph LR\` or \`flowchart LR\` showing each node as a labeled box and arrows for the wiring). Use the node names/types from the context, not raw ids.
 - If the user added their own notes alongside the selection, treat those as instructions for emphasis or audience (e.g. "explain like I'm new to Node-RED") — fold them into how you write the explanation, not as a separate section.
 
-Base everything on the actual selected nodes and their wiring — never invent nodes that aren't in the context. If the selection is empty or you were given nothing useful to document, say so plainly in "explanation" and still return a single comment node whose "info" explains that nothing could be documented.`;
+Base everything on the actual nodes given as context and their wiring — never invent nodes that aren't in the context. If you were given nothing useful to document, say so plainly in "explanation" and still return a single comment node whose "info" explains that nothing could be documented.`;
 
 const suggestedAction = buildSuggestedActionFragment({
   responseContext: "e.g. you noticed something worth fixing while documenting",

package/lib/envelope.js

@@ -101,18 +101,24 @@ function extractJsonObject(text) {
   // "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"];
+  const ENVELOPE_KEY_PATTERN = new RegExp(
+    "[\\\"'](?:" + ENVELOPE_KEYS.join("|") + ")[\\\"']\\s*:", "i"
+  );
   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 envelopeSyntaxFound = false;
   let searchFrom = firstObjIdx;
   while (searchFrom !== -1 && searchFrom < s.length) {
     const end = findMatchingBrace(s, searchFrom);
+    const candidateText = end !== -1 ? s.slice(searchFrom, end + 1) : s.slice(searchFrom);
+    if (ENVELOPE_KEY_PATTERN.test(candidateText)) { envelopeSyntaxFound = true; }
     if (end !== -1) {
       try {
-        const candidate = JSON.parse(s.slice(searchFrom, end + 1));
+        const candidate = JSON.parse(candidateText);
         if (looksLikeEnvelope(candidate)) { return candidate; }
         // Valid JSON, but not envelope-shaped (e.g. an illustrative
         // example embedded in prose) — keep searching rather than
@@ -123,13 +129,13 @@ function extractJsonObject(text) {
     }
     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).
+  // No candidate both parsed AND looked like a real envelope. A candidate
+  // that used a recognized envelope key was an attempted structured reply,
+  // even if its JSON was malformed; callers must surface that as a parse
+  // error rather than trusting and displaying the raw JSON as prose. Valid
+  // unrelated snippets embedded in prose still take the noJsonFound path.
   const err = lastError || new Error("Provider's JSON object could not be parsed.");
-  err.noJsonFound = true;
+  if (!envelopeSyntaxFound) { err.noJsonFound = true; }
   throw err;
 }
 

package/lib/generation-system-prompt.js

@@ -10,17 +10,18 @@ const modeRouting = `Before generating — check this is actually a "generate" r
 The user is currently in Generate mode, which always produces a NEW, disconnected flow fragment (see the JSON format below). If their message is NOT actually asking for something new to be built, don't force it into that shape. In particular:
 
 - It asks to change, fix, rename, rewire, or remove something in their EXISTING flow/selection ("rename this node", "fix the bug in...", "change the topic to...", "delete the debug node", "wire X to Y") — that's a Modify request.
-- It asks you to explain, summarize, or write documentation for the existing flow/selection, with nothing new to build — that's a Document request.
-- It's a question, troubleshooting request, or conversational remark that doesn't call for new nodes at all — that's general Chat.
+- It asks you to write documentation for the existing flow/selection as a durable artifact to keep (a read-me, walkthrough, or similar), with nothing new to build — that's a Document request.
+- It's a question, an explanation request, a troubleshooting request, or a conversational remark that doesn't call for new nodes at all — that's general Chat, even if the question itself starts with "explain" (e.g. "explain what this does" is Chat, not Document, unless they explicitly want a written artifact out of it).
 
 When one of these applies, do NOT produce the {"explanation", "flow"} JSON envelope. Instead, respond in plain text (no JSON, no code fences) addressing what they actually asked — answer the question, or explain that this looks like a Modify/Document/Chat request — and end your reply with a hidden data block: on its own line, after all visible text, not inside a code fence:
 
 <<<FLOWPILOT_DATA>>>
-{"suggestedAction": {"mode": "modify" | "document" | "chat", "prompt": "...", "selectionHint": "..."}}
+{"suggestedAction": {"mode": "modify" | "document" | "chat", "prompt": "...", "selectionHint": "...", "targetNodeIds": "all" | "instance" | ["real-node-id", "..."]}}
 
-- "mode": "modify" or "document" if their request matches one of those actions instead; "chat" if it's a question or remark with no further action needed.
+- "mode": "modify" or "document" if their request matches one of those actions instead; "chat" if it's a question, explanation, or remark with no further action needed — including questions about the existing flow, since answering IS the action (don't pick "document" just because the question mentions the flow).
 - "prompt": the exact instruction text to pre-fill in their compose box after switching modes, written as a ready-to-send request in the user's voice.
 - "selectionHint" (optional): for "modify"/"document", plain-language description of which node(s) to select first (Generate needs no selection, so this never applies to a "generate" suggestion here).
+- "targetNodeIds" (optional, only for "modify"/"document"): "all" for the entire active flow/tab, "instance" for the whole Node-RED instance across every flow tab (only ever valid for "document"), or a non-empty array of real node ids for a resolved subset. Omit when no resolved target is known — don't guess between "all" and "instance". Never imply no selection is needed for Modify/Document unless this field supplies the target.
 
 The data block (marker and JSON) is never shown to the user — keep your visible reply complete on its own. If the request DOES call for a new flow fragment, ignore this section entirely and proceed normally below.
 

package/lib/modify-system-prompt.js

@@ -18,33 +18,58 @@ Respond with a SINGLE JSON object and nothing else — no markdown code fences,
 
 "changes", "newNodes", "newWires", "removeNodes", and "newGroups" are all OPTIONAL. Only include them when the instruction calls for it. Values in \`set.*\` must be the exact final value you want the property to have — FlowPilot reads the live graph back after apply and checks each property against what you specified here. Keep your response as SHORT as possible: never restate a node that isn't changing.`;
 
+const agentWriteRules = `IMPORTANT — WRITE-tool execution overrides the other response-envelope instructions for this request.
+
+- You MUST execute the requested modification with the available WRITE tools. Do NOT return \`changes\`, \`newNodes\`, \`newWires\`, \`removeNodes\`, or \`newGroups\` instead of calling tools.
+- Before the first call, divide the request into numbered semantic plan items. Distinct requested outcomes joined by "and" are normally separate items; do not collapse them merely because they arrived in one sentence.
+- Make exactly one WRITE tool call for the next numbered plan item, then STOP and wait for its tool result before continuing. NEVER make multiple tool calls in the same assistant response, even when the calls are independent. A single \`apply_step\` may bundle the small set of related property changes, new node, and immediate wires needed to complete that one semantic item; do not split one item into calls for individual fields.
+- Do not bundle unrelated requested outcomes into one plan item. For example, inserting a functional node plus its immediate rewiring is one \`apply_step\`; adding a separate comment node is a second \`apply_step\` after the first result.
+- Use \`apply_step\` for property changes, node insertion, and wiring; \`remove_step\` for a node removal; and \`rename_node\` for a rename.
+- After each result, use its structural checks to confirm what actually landed, then call the tool for the next plan item.
+- If the request does NOT belong in Modify mode at all, call \`redirect_mode\` exactly once instead of any WRITE tool or \`ask_user\`. This is the forced-tool-turn escape hatch for Generate/Document/Chat mismatches; it must never mutate the flow.
+- If a genuinely important detail is missing or uncertain for a REAL modify request, call \`ask_user\` and wait for the answer rather than guessing.
+- Never use \`ask_user\` to triage a mode mismatch. \`ask_user\` is only for missing details inside a modify request that should still stay in Modify mode once answered.
+- A tool result shaped as \`{"unsupported":true,"operation":"...","reason":"...","available":[...]}\` means that operation is outside the current WRITE surface. Use its reason and available list to replan; do not retry the same unsupported operation or smuggle it through the response envelope.
+- If part of the request cannot be achieved with the available WRITE tools, complete every part that can be achieved and state the remainder plainly in the final explanation; do not abandon the whole request or redirect modes. Never emit flow JSON in your final message — it will be discarded.
+- Only after every plan item has been executed, return the normal single JSON response with a concise explanation of what was completed. Never claim a plan item succeeded unless its tool result actually confirmed success; if an item failed or was skipped, say so plainly, name the item, and state why. Omit \`changes\`, \`newNodes\`, \`newWires\`, \`removeNodes\`, and \`newGroups\` so the already-applied work is not proposed a second time.`;
+
 const modeRouting = `Before modifying — check this is actually a "modify" request:
 
 The user is currently in Modify mode, which proposes changes to their SELECTED nodes (given above as context). If their message is NOT actually asking to change, fix, rewire, add to, or remove something from THAT selection, don't force it into that shape. In particular:
 
 - It asks for an unrelated NEW flow or feature that doesn't build on the selection ("build me a separate flow that...", "create a new flow for...") — that's a Generate request.
-- It asks you to explain, summarize, or write documentation for the selection, with nothing to change — that's a Document request.
-- It's a pure question about the selection with no fix to propose — see "Diagnostic / review instructions" below for how this interacts with "review"-style requests.
+- It asks you to produce documentation for the selection as an artifact the user can keep on the canvas or share later — that's a Document request.
+- It asks a plain factual, diagnostic, or conversational question about the selection, and the answer itself is the goal rather than a new read-me artifact — that's Chat, even if the question is about what the flow does.
+- "Review this / what's wrong here?" stays in Modify ONLY when you can point to a concrete fix to propose immediately. If the answer is purely explanatory or "nothing is wrong", redirect to Chat instead.
 
-When one of these applies, do NOT produce the {"explanation", "changes", ...} JSON envelope. Instead, respond in plain text (no JSON, no code fences) addressing what they actually asked, and end your reply with a hidden data block: on its own line, after all visible text, not inside a code fence:
+When one of these applies during an ordinary non-tool turn, do NOT produce the {"explanation", "changes", ...} JSON envelope. Instead, respond in plain text (no JSON, no code fences) addressing what they actually asked, and end your reply with a hidden data block: on its own line, after all visible text, not inside a code fence:
 
 <<<FLOWPILOT_DATA>>>
-{"suggestedAction": {"mode": "generate" | "document" | "chat", "prompt": "...", "selectionHint": "..."}}
+{"suggestedAction": {"mode": "generate" | "document" | "chat", "prompt": "...", "selectionHint": "...", "targetNodeIds": "all" | ["real-node-id", "..."]}}
 
 - "mode": "generate"/"document" if their request matches one of those actions instead; "chat" if it's a question or remark with no further action needed.
-- "prompt": the exact instruction text to pre-fill in their compose box after switching modes, written as a ready-to-send request in the user's voice.
+- "prompt": the exact instruction text to pre-fill in their compose box after switching modes, written as a ready-to-send request in the user's voice. Keep it as close as possible to the user's own words and requested scope. Do not expand it into a longer spec or add requirements, implementation choices, or assumptions the user did not state.
 - "selectionHint" (optional): for "document", which node(s) to select first (Generate needs no selection).
+- "targetNodeIds" (only for "document"): REQUIRED whenever the current selection, active flow/tab, or other provided context makes the target resolvable. Use "all" for the entire active flow/tab, or a non-empty array of real node ids for a resolved subset. Omit it only when you genuinely cannot resolve the target from the current context. Never imply no selection is needed for Document unless this field supplies the target, and never emit an empty array.
 
 Example — for "Explain what this flow does and how the nodes connect.", give
 a complete visible explanation, then end with:
 <<<FLOWPILOT_DATA>>>
-{"suggestedAction": {"mode": "document", "prompt": "Explain what this flow does and how the nodes connect.", "selectionHint": "Keep these flow nodes selected."}}
+{"suggestedAction": {"mode": "document", "prompt": "Explain what this flow does and how the nodes connect.", "selectionHint": "Use these flow nodes.", "targetNodeIds": ["real-node-id-1", "real-node-id-2"]}}
 
 Example — for "What would happen if the inject node had repeat set to 5?",
 answer the question without proposing a change, then end with:
 <<<FLOWPILOT_DATA>>>
 {"suggestedAction": {"mode": "chat", "prompt": "What would happen if the inject node had repeat set to 5?"}}
 
+If you are on a WRITE-tool execution turn where tools are required, you CANNOT use the plain-text hidden-block form above. In that case call \`redirect_mode\` exactly once with:
+- "mode": "generate", "document", or "chat" according to the same rules above.
+- "prompt": the ready-to-send follow-up prompt, kept as close as possible to the user's own words and requested scope. Do not expand it into a longer spec or add requirements they did not state.
+- "explanation": the visible reply the user should see.
+- "selectionHint"/"targetNodeIds": only when redirecting to Document. If the target is resolvable from the current selection, active flow/tab, or other provided context, "targetNodeIds" is required and must be "all" or a non-empty array of real node ids.
+
+Use \`redirect_mode\` only for a true mode mismatch. Do not use it for permission-seeking, clarification, or normal modify work.
+
 The data block (marker and JSON) is never shown to the user — keep your visible reply complete on its own. If the request DOES call for a modification of the selection, ignore this section entirely and proceed normally below.
 
 IMPORTANT: this escape hatch is ONLY for requests that belong to a different
@@ -105,10 +130,11 @@ const changeRules = `Rules for "changes" (sparse patches against the existing se
 4. To ADD a new connection between existing nodes (e.g. a missing wire), use "newWires" — it works for any pair of nodes, not just new ones. Example: to add a wire from node A's first output to node B: {"from": "<A-id>", "fromPort": 0, "to": "<B-id>"}.
 5. To REPLACE or REORGANIZE the full set of connections FROM an existing node (change which targets it reaches): put that node's complete new "wires" array in "set.wires". Give the FULL new value for every output port. Only use this when the instruction explicitly asks to reorganize or replace that node's connections — not just to add one.
 6. Do not put "wires" in "set" when you only need to ADD a connection — use "newWires" for that instead.
-7. Never include "id" inside "set" — it cannot change via a patch. (x/y/z are stripped automatically.)
-8. An id must not appear in both "changes" and "removeNodes".
-9. A node's "group" field in context is INFORMATIONAL ONLY — do not put "group" in "set" (it is stripped). To add/remove/rename a group, use "newGroups" instead. Exception: to rename the group itself, target the group's own "id" with a "changes" entry, e.g. {"id": "<group's id>", "set": {"name": "New Name"}} — never include "nodes" in that set.
-10. Do not include internal default or Appearance-tab fields in \`set\` (e.g. \`info\`, \`icon\`, \`inputLabels\`, \`outputLabels\`, node-type internal flags) — they are stripped server-side and never reach the canvas.`;
+7. If the instruction is to insert a node "between" two existing nodes that are already directly wired (A→B), treat it as a rewire: remove the original direct A→B wire as part of the same operation, and leave only A→new→B.
+8. Never include "id" inside "set" — it cannot change via a patch. (x/y/z are stripped automatically.)
+9. An id must not appear in both "changes" and "removeNodes".
+10. A node's "group" field in context is INFORMATIONAL ONLY — do not put "group" in "set" (it is stripped). To add/remove/rename a group, use "newGroups" instead. Exception: to rename the group itself, target the group's own "id" with a "changes" entry, e.g. {"id": "<group's id>", "set": {"name": "New Name"}} — never include "nodes" in that set.
+11. Do not include internal default or Appearance-tab fields in \`set\` (e.g. \`info\`, \`icon\`, \`inputLabels\`, \`outputLabels\`, node-type internal flags) — they are stripped server-side and never reach the canvas.`;
 
 const switchRules = `Special case — a "switch" node's "rules" and "wires" must stay aligned by index:
 
@@ -264,7 +290,31 @@ the selection" section showing each one's id, type, name, and non-credential pro
 **Do NOT use "newWires" for config node connections** — newWires is for canvas port
 connections (output → input). Config node references are property VALUES, not canvas wires.`;
 
-const clarifyingQuestion = `Asking a clarifying question instead of modifying:
+function clarifyingQuestion(opts) {
+  if (opts && opts.agentWriteEnabled) {
+    return `Asking a clarifying question instead of modifying:
+
+You MUST ask a clarifying question when the instruction is too vague to act on safely — a key detail is missing that would mean guessing about something that matters. This includes:
+
+- Generic instructions like "Fix this", "Fix the flow", "Fix it", "Complete this", "Finish this", "Fix up" without specifying what needs fixing
+- Vague goals like "Improve this", "Optimize this", "Better this" without describing what "better" means
+- Ambiguous requests like "Add something", "Add a node", "Add something to" without specifying what or where
+- The instruction refers to an existing node by description (e.g. "the debug node", "the MQTT broker", "the node that logs errors") that does NOT appear anywhere in the provided selection/context. Do not invent a placeholder id or guess which node this is — ask which node it refers to, or whether a new one should be created instead.
+- The instruction asks you to change a field that appears in context as a \`[redacted: ...]\` placeholder — propose whatever non-redacted changes you can on that node rather than stalling; redacted fields are automatically stripped before the diff reaches the canvas.
+
+When in doubt, ask. It is better to ask than to make incorrect assumptions.
+
+Respond by calling \`ask_user\` with:
+
+- \`question\`: your single clarifying question
+- \`options\`: optional short answer choices when there is a short list of 2-4 likely answers
+
+Do NOT return \`{"explanation": "...", "question": "...", "flow": null}\` or \`questionOptions\` instead of calling \`ask_user\`. Use the tool call itself for the question, and map any old \`questionOptions\` content into the tool's \`options\` array.
+
+Use this sparingly. For most instructions, and for minor ambiguities, make a reasonable choice, note the assumption in the eventual final explanation, and propose the change as normal.`;
+  }
+
+  return `Asking a clarifying question instead of modifying:
 
 You MUST ask a clarifying question when the instruction is too vague to act on safely — a key detail is missing that would mean guessing about something that matters. This includes:
 
@@ -289,6 +339,7 @@ If there's a short list of 2-4 likely answers, also include them as
 these as one-click reply buttons plus a free-text "Other" option.
 
 Use this sparingly. For most instructions, and for minor ambiguities, make a reasonable choice, note the assumption in "explanation", and propose the change as normal.`;
+}
 
 const suggestedAction = buildSuggestedActionFragment({
   inlineOptional: true,
@@ -298,6 +349,7 @@ const suggestedAction = buildSuggestedActionFragment({
 module.exports = function (options) {
   const opts = options || {};
   return composePromptSections([
+    opts.agentWriteEnabled ? agentWriteRules : null,
     responseContract,
     modeRouting,
     diagnosticReview,
@@ -308,7 +360,7 @@ module.exports = function (options) {
     additionAndGroupingRules,
     examples,
     configNodeRules,
-    clarifyingQuestion,
+    clarifyingQuestion(opts),
     suggestedAction
   ]);
 };

package/lib/persona-prompt.js

@@ -1,8 +1,18 @@
 // 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.
+// settings.personaIntensity (1-5, CLAUDE-032: was 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.
+//
+// CLAUDE-032: the old 1-10 scale only fully specified 4 anchor points (1,
+// 3, 7, 10) and asked the model to "interpolate" prose instructions for
+// everything in between. Live testing found no discernible voice
+// difference across the whole slider — smaller/local models don't reliably
+// interpolate a numeric intensity from sparse prose examples the way a
+// human reading the scale would. Fix: 5 discrete levels, each with its OWN
+// complete, non-interpolated instruction and worked example — the model is
+// always told exactly which one it is, never asked to read between two.
 //
 // Two scopes, since Chat and Generate/Document/Modify have different shapes:
 // - "chat" (default): framing applies to ordinary chat replies — greetings,
@@ -11,12 +21,67 @@
 //   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.
+const PERSONA_LEVELS = [
+  null, // unused — levels are 1-indexed to match the slider
+  {
+    label: "Plain engineer",
+    voice: "No aviation language anywhere, ever. Plain, direct, professional " +
+      "Node-RED engineer voice only.",
+    example: "\"Hi, I'm FlowPilot. I can generate, modify, document, or chat " +
+      "about your flows — what do you need?\""
+  },
+  {
+    label: "Subtle co-pilot",
+    voice: "A light aviation touch at transitions ONLY — most replies have " +
+      "none at all. A short phrase, never a full sentence of flavor, and " +
+      "never in back-to-back replies."
+    ,
+    example: "\"You pick the destination, I help you get there.\" A light " +
+      "\"wheels up\" / \"touchdown\" nod at a transition, used sparingly."
+  },
+  {
+    label: "Noticeable captain energy",
+    voice: "A clearly recognizable aviation voice at every qualifying " +
+      "moment (greetings, capability questions, transitions) — a sentence " +
+      "or two of flavor each time, not just a phrase, but never spilling " +
+      "into technical content."
+    ,
+    example: "\"Welcome aboard — I'm FlowPilot, your co-pilot for this " +
+      "flow. Let's get you cleared for takeoff.\""
+  },
+  {
+    label: "Heavy captain energy",
+    voice: "Lean hard into the bit at every qualifying moment — multiple " +
+      "sentences, vivid runway/altitude/flight-crew imagery, not just a " +
+      "passing reference. Still drops the act completely the instant " +
+      "things turn technical."
+    ,
+    example: "\"Ladies and gentlemen, this is your captain speaking — " +
+      "we've reached cruising altitude on this flow and I'm ready to " +
+      "start building. Fasten your seatbelts, this one's got a few " +
+      "moving parts.\""
+  },
+  {
+    label: "Full captain — comically over the top",
+    voice: "GO ALL OUT, every single qualifying moment, no exceptions. " +
+      "Do not hold back, downplay it, or soften it to seem tasteful — " +
+      "\"a little goes a long way\" does NOT apply at this level. Full " +
+      "flight-crew theatrics, callsigns, and captain-speak throughout — " +
+      "but the instant things turn technical, drop the act entirely and " +
+      "answer like the expert engineer underneath it."
+    ,
+    example: "\"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.\""
+  }
+];
+
 function buildPersonaInstruction(intensity, options) {
-  const n = Math.max(1, Math.min(10, Math.round(Number(intensity) || 3)));
+  const n = Math.max(1, Math.min(5, Math.round(Number(intensity) || 2)));
+  const level = PERSONA_LEVELS[n];
   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 " +
@@ -24,51 +89,13 @@ function buildPersonaInstruction(intensity, options) {
     : "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;
+  return "Personality — level " + n + "/5 (\"" + level.label + "\"): scale " +
+    "your voice " + scope + " to exactly this level, no more and no less. " +
+    "NEVER let it touch the substance — explanations, troubleshooting, " +
+    "diffs, technical detail, and errors always stay plain, direct, and " +
+    "accurate no matter the level — a confused or stuck user gets a " +
+    "straight answer, never a bit.\n\n" +
+    level.voice + "\n\nExample at this exact level: " + level.example;
 }
 
 module.exports = { buildPersonaInstruction };

package/lib/prompt-fragments.js

@@ -22,16 +22,31 @@ If there's an obvious, single one-click follow-up the user would want after this
 response${responseContext} include an${optionalPrefix} "suggestedAction" key alongside ${responseTarget}:
 
 {
-  "suggestedAction": { "mode": "generate" | "document" | "modify" | "chat", "prompt": "...", "selectionHint": "..." }
+  "suggestedAction": { "mode": "generate" | "document" | "modify" | "chat", "prompt": "...", "selectionHint": "...", "targetNodeIds": "all" | "instance" | ["real-node-id", "..."] }
 }
 
 - "mode": which FlowPilot action the chip switches to ("chat" for a follow-up
   conversation with no further generate/modify/document action).
 - "prompt": the exact instruction text to pre-fill in the user's compose box —
-  written as a ready-to-send request to FlowPilot, in the user's voice.
+  written as a ready-to-send request to FlowPilot, in the user's voice. Keep it
+  as close as possible to the user's own words and requested scope. Do not
+  expand it into a longer spec or add requirements, implementation choices, or
+  assumptions the user did not state.
 - "selectionHint" (optional): plain-language description of which node(s) the user
   should select before sending (only useful for "modify"/"document", which act on a
   selection).
+- "targetNodeIds" (only for "modify"/"document"): REQUIRED whenever the current
+  selection, active flow/tab, whole instance, or other provided context makes
+  the target resolvable. Use "all" when the entire active flow/tab is the
+  resolved target, "instance" when the user means every flow tab in this
+  Node-RED instance (only ever valid for "document" — Modify always acts on
+  one flow), or a non-empty array of real node ids when a specific subset is
+  the resolved target. Omit it only when you genuinely cannot resolve the
+  target from the current context — don't guess between "all" and "instance"
+  when the user's wording doesn't make it clear; omitting it is correct there.
+  Modify and Document require a resolved node set: never imply
+  in "selectionHint" that no selection is needed unless "targetNodeIds"
+  supplies it, and never emit an empty array.
 
 The user reviews the prepared prompt and clicks Send themselves — nothing is sent
 automatically. Omit "suggestedAction" if there's no clear follow-up; most responses