2026-06-06-ai-user-doc-updates Add AI risk guidance and script execution page

Author: dpolivaev

post.md

@@ -0,0 +1,40 @@
+# Preview: AI prompts, formulas, scripts, and MCP updates in Freeplane 1.13.3
+
+We have a preview build of Freeplane `1.13.3` with a broader set of AI
+features and updated documentation.
+
+Highlights in this preview:
+
+- reusable AI prompts and assistant profiles,
+- prompt-specific optional model and tool settings,
+- AI attachment for the Formula Editor and Script Editor,
+- optional AI repair after formula execution failure,
+- a separate `AI may edit formulas` permission,
+- a separate explanation of AI-owned script execution and its risks,
+- a clearer `AI-owned script execution policy`,
+- improved MCP behavior and MCP visibility in AI chat,
+- Groovy scripts that can ask AI asynchronously,
+- the `Block formula map edits` safeguard.
+
+The documentation now covers these areas in more detail, including the
+permissions each feature needs and the risks and benefits of enabling
+it.
+
+Important risk notes:
+
+- AI output can be wrong.
+- Prompt injection through mind map content or scripts cannot be fully
+  excluded.
+- AI-generated formulas and especially AI-generated scripts should be
+  reviewed carefully.
+- Allowing AI to run scripts without user review is materially riskier
+  than shown-mode review.
+- Freeplane's MCP server listens only on `127.0.0.1` by default, so it
+  is not remotely reachable by itself. It becomes externally reachable
+  only if separate forwarding or proxy software exposes that local
+  port.
+- Even then, connected MCP clients may themselves send map content or
+  results to external AI services.
+
+If you test this preview, feedback on both usability and safety wording
+would be especially useful.

src/docs/SUMMARY.md

@@ -12,6 +12,7 @@
   - [AI chat workflows](ai/ai-chat-workflows.md)
   - [AI prompts and profiles](ai/ai-prompts-and-profiles.md)
   - [AI formulas and script editing](ai/ai-formulas-and-script-editing.md)
+  - [AI-owned script execution](ai/ai-owned-script-execution.md)
   - [Model Context Protocol server](ai/model-context-protocol-server.md)
   - [AI integration troubleshooting](ai/ai-integration-troubleshooting.md)
 - [User documentation](user-documentation/user-documentation.md)

src/docs/ai/ai-chat-workflows.md

@@ -3,6 +3,21 @@
 This page focuses on practical ways to get useful results from AI in
 everyday map work.
 
+## Benefits and risks
+
+Benefits:
+
+- workflow patterns can make repeated map tasks faster and more
+  consistent,
+- profiles and prompts reduce repeated setup work.
+
+Risks:
+
+- AI suggestions can still be wrong,
+- hidden prompt runs reduce visibility,
+- tool-call summaries help review what happened, but they do not prove
+  that the result is correct or safe.
+
 ## Use profiles and prompts for repeatable work
 
 - Use `Manage profiles` when you want reusable chat behavior across many

src/docs/ai/ai-formulas-and-script-editing.md

@@ -1,7 +1,21 @@
 ## AI formulas and script editing
 
 The features on this page require Freeplane `1.13.3` or later.
-Each section below repeats the settings it needs.
+The feature sections below repeat the settings they need.
+
+## Benefits and risks
+
+Benefits:
+
+- AI can draft, explain, and repair formulas and scripts faster,
+- editor attachment lets AI work with the live text you are currently
+  editing.
+
+Risks:
+
+- formulas and scripts can be wrong or unsafe,
+- models make mistakes, and prompt injection through map content or
+  scripts cannot be fully excluded.
 
 ## Formula editing and execution with AI
 
@@ -10,6 +24,11 @@ To use this:
 - `AI tool availability` must include `Editing` or `Script execution`.
 - `AI may edit formulas` must be enabled.
 
+Benefit: AI can help draft and repair formulas faster.
+
+Risk: review any generated formula before submitting it, especially if
+it refers to other nodes or searches the map.
+
 `Formula Editor` can be attached to AI through its local `AI` button.
 
 When you attach the editor, AI works with the **live text currently
@@ -49,6 +68,11 @@ repair, see [Formulas](../scripting/Formulas.md).
 No AI permission is needed for this safeguard itself. It is a
 formula-plugin preference and applies to all formulas.
 
+Benefit: this blocks one important class of formula side effects.
+
+Risk: if you disable it, formula evaluation can perform map edits when
+the formula text does that.
+
 The formula-plugin preference `Block formula map edits` is enabled by
 default.
 
@@ -66,6 +90,16 @@ To use this:
 
 - `AI tool availability` must include `Script execution`.
 
+Benefit: AI can help draft, explain, and refactor Groovy scripts
+faster.
+
+Risk: AI-generated code is untrusted code and should be reviewed before
+running it.
+
+This attached editor flow helps AI edit the current script draft. For
+execution of AI-owned scripts, see
+[AI-owned script execution](ai-owned-script-execution.md).
+
 `Edit script` can be attached to AI through its local `AI` button.
 
 When you attach the editor, AI works with the **live text currently
@@ -75,33 +109,6 @@ open in that editor**, not only with already-saved map content.
 
 *Script Editor with the local AI attach button.*
 
-## AI-owned script execution policy
-
-This section matters only when `AI tool availability` includes `Script
-execution`.
-
-`AI-owned script execution policy` controls how AI-created scripts are
-run:
-
-- `Shown, user must press Run`
-- `Hidden, AI may run directly`
-
-In shown mode, Freeplane opens a review dialog so you can inspect the
-script before running it.
-
-If you want AI to run the script directly, this policy must be `Hidden,
-AI may run directly`.
-The separate `AI-owned dialog Run permissions` setting controls which
-external permissions a user-started `Run` from that dialog uses.
-
-![AI-owned script review dialog](../images/ai-owned-script-review-dialog.png)
-
-*Shown mode is a review gate. The dialog is for script inspection and
-Run/Cancel only.*
-
-The shown dialog is not a results window. If you later see a popup with
-script output, that popup usually comes from the script itself.
-
 ## Prefer value-computing formulas and scripts
 
 This guidance still applies when the relevant permissions are enabled.
@@ -123,10 +130,12 @@ If you want most features on this page, a good default configuration is:
 
 - `AI tool availability`: `Editing` or `Script execution`
 - `AI may edit formulas`: enabled if you want AI to help with formulas
-- `AI-owned script execution policy`: `Shown, user must press Run`
 - `AI chat shows tool calls`: enabled if you want visible AI/MCP tool
   activity in chat
 
+For AI-owned script execution settings, see
+[AI-owned script execution](ai-owned-script-execution.md).
+
 The preferences page below shows the main settings involved in these
 workflows.
 

src/docs/ai/ai-integration-getting-started.md

@@ -6,6 +6,28 @@ The newer features linked from this page — prompts, editor attachment,
 AI-owned script review, formula-editing controls, and script-facing AI
 requests — require Freeplane `1.13.3` or later.
 
+## Benefits and risks
+
+Benefits:
+
+- AI can summarize, rewrite, inspect, and help edit map content faster.
+- Prompts, profiles, formulas, and scripts can make repeated tasks
+  easier.
+
+Risks:
+
+- Depending on your provider and setup, map content sent to AI may
+  leave your machine.
+- Model output can be wrong, misleading, or influenced by map content.
+- Higher-permission features such as editing, formula authoring,
+  script execution, and MCP increase risk and should be enabled
+  deliberately.
+
+For the higher-risk features, read
+[AI formulas and script editing](ai-formulas-and-script-editing.md)
+and [Model Context Protocol server](model-context-protocol-server.md)
+before enabling them.
+
 ### Configure AI in Preferences
 
 Open AI Preferences from the AI panel toolbar burger menu, then
@@ -48,7 +70,7 @@ The following settings matter for most current AI workflows:
     availability is high enough
 - `AI-owned script execution policy`
   - controls whether AI-owned scripts are shown for review or may run
-    directly
+    directly without user review
 - `AI chat shows tool calls`
   - shows AI and MCP tool activity in chat
 
@@ -74,8 +96,10 @@ Helpful chat controls:
   [AI chat workflows](ai-chat-workflows.md).
 - Learn how prompts and profiles differ in
   [AI prompts and profiles](ai-prompts-and-profiles.md).
-- Learn about editor attachment, formulas, and script review in
+- Learn about editor attachment, formulas, and script editing in
   [AI formulas and script editing](ai-formulas-and-script-editing.md).
+- Learn about direct AI-owned script execution in
+  [AI-owned script execution](ai-owned-script-execution.md).
 - For remote tool access, see
   [Model Context Protocol server](model-context-protocol-server.md).
   MCP is disabled by default and should be enabled only when needed,

src/docs/ai/ai-integration-troubleshooting.md

@@ -1,6 +1,6 @@
 ## AI integration troubleshooting
 
-### Start here
+## Start here
 
 If AI does not respond as expected, open AI Preferences (from the AI
 panel burger menu) and check:
@@ -15,7 +15,20 @@ panel burger menu) and check:
 For prompts, editor attachment, AI-owned script review, and formula
 editing features, use Freeplane `1.13.3` or later.
 
-### Messages you may see
+## Benefits and risks
+
+Benefits:
+
+- this page helps you diagnose configuration and permission problems,
+- it can help you avoid enabling stronger AI features by guesswork.
+
+Risks:
+
+- some fixes involve enabling stronger permissions,
+- when a fix requires editing, formula authoring, script execution, or
+  MCP, re-read the corresponding feature page before enabling it.
+
+## Messages you may see
 
 - `No AI provider is configured.`
   - Required provider settings are missing.
@@ -33,7 +46,7 @@ editing features, use Freeplane `1.13.3` or later.
 - `Unknown AI provider selection.`
   - Re-check provider settings in Preferences.
 
-### Prompts and profiles
+## Prompts and profiles
 
 If you cannot find saved prompts or assistant profiles:
 
@@ -48,7 +61,7 @@ If prompts do not behave like normal chat, that may be expected:
 - shown prompts open their own chat,
 - hidden prompts do not stay as visible saved chats.
 
-### Formula editing is missing or not offered
+## Formula editing is missing or not offered
 
 If AI does not offer formula editing:
 
@@ -57,10 +70,12 @@ If AI does not offer formula editing:
 
 Formula editing is gated separately from ordinary AI editing.
 
-### AI-owned script review behaves differently than expected
+## AI-owned script review behaves differently than expected
 
 If an AI-owned script waits for you instead of running immediately,
 check `AI-owned script execution policy`.
+For the full behavior and risk model, see
+[AI-owned script execution](ai-owned-script-execution.md).
 
 - `Shown, user must press Run`
   - opens the review dialog and waits for your decision.
@@ -71,7 +86,7 @@ If you see a popup with a script result, that popup may have been
 created by the script itself rather than by the AI-owned review dialog.
 Prefer `return` or `println` in scripts when you do not want UI popups.
 
-### Formula execution fails while editing
+## Formula execution fails while editing
 
 If formula execution fails with a message about blocked execute calls,
 check the formula-plugin setting `Block formula map edits`.
@@ -82,7 +97,7 @@ validation can fail by design.
 This is especially relevant if a formula tries to create nodes or make
 other map changes.
 
-### Editor attachment and AI repair
+## Editor attachment and AI repair
 
 If the `AI` button in `Formula Editor` or `Edit script` does not behave
 as expected:
@@ -92,7 +107,7 @@ as expected:
 - if formula repair is offered after an execution failure, remember that
   the repair request is optional and starts only if you choose it.
 
-### MCP not working
+## MCP not working
 
 If another local AI app cannot use Freeplane through MCP:
 
@@ -115,12 +130,12 @@ Also remember that some MCP-assisted editing features depend on the
 current AI settings. If formula-related editing is missing, re-check
 `AI tool availability` and `AI may edit formulas`.
 
-### Scripts asking AI
+## Scripts asking AI
 
 If you are troubleshooting Groovy scripts that call AI, see
 [Asking AI from scripts](../scripting/Asking_AI_from_scripts.md).
 
-### Quick success checklist
+## Quick success checklist
 
 Use this after changes or upgrades: