Merge pull request #7223 from FlowFuse/update-docs-2-30

docs: update documentation to align with 2.30

Author: dimitrieh

docs/admin/sso/README.md

@@ -18,8 +18,7 @@ registers when they first sign in.
 Otherwise, a user will have to first register on the platform, providing a temporary
 password in order to create an account. They will then be able to log in via their SSO provider.
 
-Admin users will still be able to log in with their original FlowFuse username/password - this ensures
-they don't get locked out of the platform if there is a problem with the SSO configuration.
+By default, admin users can still log in with their original FlowFuse username and password, which ensures they are not locked out if there is a problem with the SSO configuration.
 
 ## SAML SSO
 

docs/admin/sso/images/force-sso.png

@@ -195,6 +195,20 @@ For Self Hosted users there is an option in the Admin Settings to enable buttons
 
 These buttons will redirect to the SSO provider rather than requiring users to enter and email address in the username field to select the correct provider.
 
+## Forcing All Users to Use SSO
+
+For self-hosted installations that need to ensure no user can bypass SSO, there is an option in **Admin Settings > Settings > SSO > Force all logins for non-admin users via a single SAML SSO provider**.
+
+![SSO settings page showing the option to force all non-admin users to log in via a single SAML SSO provider](./images/force-sso.png)
+_SSO settings page showing the option to force all non-admin users to log in via a single SAML SSO provider_
+
+When this option is enabled:
+- All users are redirected to the configured SSO provider at login, regardless of their email domain
+- The email and password login form is no longer presented as a fallback option
+- Admin users can bypass SSO by accessing `/admin` routes
+
+This is intended for organisations running a single identity provider across the entire platform, where per-domain SSO configuration is not sufficient to cover all users.
+
 ## Providers
 
 The following is a non-exhaustive list of the providers that are known to work

docs/admin/sso/saml.md

@@ -4,17 +4,17 @@ navTitle: Chat Interface
 
 # Chat Interface
 
-The FlowFuse Expert chat interface is your conversational AI companion that you can open directly in the Node-RED editor. While other FlowFuse Expert features (like inline code completions and next-node prediction) work passively in the Node-RED Editor, the chat interface is where you actively engage the AI - asking questions, exploring your flows, and gaining insights from your live data.
+The FlowFuse Expert chat interface is where you actively engage the AI: asking questions, building flows directly on your canvas, and querying live operational data. While other FlowFuse Expert features (like inline code completions and next-node prediction) work passively in the Node-RED editor, the chat interface is where you direct Expert and see it act on your behalf.
 
 ## Opening the Chat Interface
 
-To open the chat, first open your Node-RED instance using the **Open Editor** button. This launches Immersive Mode.
+To open the chat, first open your Node-RED instance using the **Open Editor** button. This launches Immersive Mode, where the Expert panel is available alongside your canvas.
 
-As of v2.29, the FlowFuse Expert panel opens automatically when you enter the immersive editor. If you close the panel, that preference is saved — Expert will remain closed on your next visit so it doesn't get in your way.
+While in Immersive Mode you also have access to all [instance settings](/docs/user/instance-settings/) from a drawer that sits beside the canvas. You can manage environment variables, snapshots, the palette, and other settings without leaving the editor. Use the eye icon at the top of the drawer to move it left or right, pin or unpin it, or toggle fullscreen mode.
 
-You can reopen the Expert panel at any time by clicking the **FlowFuse Expert** button in the top-left of the editor.
+> **Note:** Note: As of v2.29, the FlowFuse Expert panel opens automatically whenever you enter the FlowFuse platform or an instance. If you close the panel, your preference is saved — Expert will remain closed on your next visit so it doesn’t get in your way. To open or close the panel while within the editor, click the FlowFuse drawer button in the top-left corner of the editor.
 
-![FlowFuse Expert open by default in the immersive editor.](../images/assistant/ff-expert-opened-by-default.png){data-zoomable}
+!["Chat interface of FlowFuse Expert alongside the Node-RED editor"](../images/assistant/flowfuse-expert-drawer.png){data-zoomable}
 
 ## Chat Modes
 
@@ -42,13 +42,33 @@ The chat interface operates in two distinct modes. You can switch between them u
 
 ### Support Mode
 
-**Support mode** is for flow-building assistance. Use it when you need help understanding, building, or debugging your Node-RED flows. In this mode, the Expert draws on its knowledge of Node-RED, your installed palette, and the context of your current flows to answer questions and provide guidance.
+**Support mode** is for flow-building assistance. Use it when you need help understanding, building, or debugging your Node-RED flows. Expert draws on its knowledge of Node-RED, your installed palette, and the context of your current flows to answer questions, explain and debug flows, and, when agentic flow building is enabled, build flows directly on your canvas.
 
 Typical use cases in Support mode:
 - "How do I convert data to CSV for writing to file & do you have any flow examples?"
 - "Explain what this flow is doing"
 - "Why is this node outputting a number instead of a string?"
 - "Is `node-red-contrib-string` node installed on this instance?"
+- "Build a flow that reads from Modbus and publishes each tag value to MQTT"
+
+#### Building Flows on the Canvas
+
+Expert can act on your requests directly by adding tabs, placing and wiring nodes, and configuring node properties on the canvas, rather than only describing what you should do yourself.
+
+To use it, describe what you want to build in the chat input, the same way you would ask a question. Expert will start working immediately, and you can follow along via real-time status updates in the chat panel as each step completes. When it finishes, the result is live on your canvas. You can continue refining it through chat by asking Expert to adjust a configuration, add a node, or change a topic path, or you can edit the canvas directly as normal.
+
+![FlowFuse Expert building and configuring a flow directly on the Node-RED canvas](../images/assistant/flowfuse-expert-building-flow.gif){data-zoomable}
+
+Some prompts that work well:
+
+- "Create a flow that reads Modbus registers from `192.168.1.10` every 5 seconds and publishes the values to MQTT on `factory/line3/temperature`"
+- "Build an OEE dashboard tab with downtime reason buttons and a shift target gauge"
+- "Add a shift handover screen that shows the last 5 alarms and a notes input field"
+- "Set up a flow that polls an HTTP endpoint every minute and sends an alert if the response status is not 200"
+
+The more specific your prompt, the closer the result will be to what you need. Include node names, topic paths, endpoints, or field names where you have them. Expert will use them directly rather than substituting placeholders.
+
+> **Availability:** This feature is currently available on **FlowFuse Cloud** (Starter, Team, and Enterprise tiers) and must be enabled for your team on request. [Contact us](https://flowfuse.com/contact-us/?subject=FlowFuse%20Expert%20Application%20Building) to get access. Self-hosted support is coming in a future release.
 
 #### Context: What the Expert Can See
 
@@ -159,9 +179,9 @@ Typical use cases in Insights mode:
 
 ## Writing Better Queries
 
-The quality of the Expert's responses depends heavily on how your questions are phrased. The more specific and contextual your query, the more accurate and actionable the answer.
+The quality of Expert's responses depends heavily on how your prompt is phrased, whether you are asking a question or requesting Expert to build something on the canvas. The more specific and contextual your prompt, the more accurate and actionable the result.
 
-Here are some common patterns to improve your queries:
+Here are some common patterns to improve your prompts:
 
 ### Be specific about what you're referring to
 
@@ -234,4 +254,4 @@ When a newer version of FlowFuse Expert is available, a banner appears in the ch
     font-size: 1.15rem;
     pointer-events: none;
   }
-</style>
+</style>

docs/user/expert/chat.md

@@ -14,9 +14,11 @@ FlowFuse Expert works in two distinct ways inside your environment.
 
 ### Chat Interface
 
-The Chat Interface is a conversational AI panel built into the FlowFuse Platform and accessible directly within the Node-RED editor. You can ask questions, get help building and debugging flows, query live operational data via MCP, and explore your environment using context-aware tools.
+The Chat Interface is a conversational AI panel built into the FlowFuse Platform and accessible directly within the Node-RED editor. With agentic flow building enabled, you can describe what you want to build and Expert will build it on your canvas for you. It can also answer questions, debug flows, and query live operational data via MCP.
 
-The Chat Interface supports two modes - **Support** for flow-building assistance, and **Insights** for querying live data via MCP tools and resources.
+The Chat Interface supports two modes:
+- **Support**: flow-building assistance, including asking questions, debugging, and building flows on the canvas
+- **Insights**: query live operational data via MCP tools and resources exposed by your own MCP servers
 
 [Learn more about the Chat Interface](/docs/user/expert/chat/)
 

docs/user/expert/index.md

@@ -6,15 +6,32 @@ navTitle: Instance Settings
 
 The Instance Settings allow you to customize many aspects of your Node-RED runtime.
 
+To access them, click on an instance from the FlowFuse platform and select the **Settings** tab. The instance view also includes other tabs such as Overview, Devices, Version History, Assets, and Node-RED Logs.
+
+You can also access all the same settings from within the immersive Node-RED editor. The settings drawer sits alongside the canvas without overlapping it, so you can adjust environment variables, manage snapshots, update the palette, and make other changes without leaving your flow. 
+
+You can customize the drawer layout using the eye icon at the top of the drawer, which lets you move it from right to left, pin or unpin it, and toggle fullscreen mode.
+
+![Instance settings drawer](./images/instance-settings.png)
+
 Instance Settings are split into a number of sections:
 
- - [General](#general)
- - [Environment](#environment)
- - [High Availability](#high-availability)
- - [Editor](#editor)
- - [Security](#security)
- - [Palette](#palette)
- - [Alerts](#alerts)
+- [Instance Settings](#instance-settings)
+  - [General](#general)
+    - [Change Stack](#change-stack)
+    - [Copy Instance](#copy-instance)
+    - [Import Instance](#import-instance)
+    - [Suspend Instance](#suspend-instance)
+    - [Delete Instance](#delete-instance)
+  - [Environment](#environment)
+  - [High Availability](#high-availability)
+  - [Editor](#editor)
+  - [Security](#security)
+    - [None](#none)
+    - [Basic Authentication](#basic-authentication)
+    - [FlowFuse User Authentication](#flowfuse-user-authentication)
+  - [Palette](#palette)
+  - [Alerts](#alerts)
 
 ## General
 

docs/user/images/assistant/flowfuse-expert-building-flow.gif

@@ -250,22 +250,29 @@ _Screenshot to an example flow preview for a Snapshot in FlowFuse_
 
 ### Comparing Snapshots
 
-From any Snapshots tab, you can compare two snapshots by selecting the Snapshot's action, 
-then selecting "Compare Snapshots". This will open a new dialog with the option to choose 
-a second snapshot to compare with.
+From any Snapshots tab, you can compare two snapshots by selecting the Snapshot's action, then selecting "Compare Snapshots". This will open a dialog where you choose a second snapshot to compare with.
 
-In the top left, a sidebar lists every changed, added, and deleted node, showing what action 
-occurred for each. The flow canvas highlights the selected node and scrolls to it 
-automatically, giving you a visual indication of where the change is in your flow. The right 
-side shows the property and code changes for the affected node. You can step through them 
-one at a time using the **Prev / Next** buttons. For each change you can see:
+The comparison view has three panels:
 
-- **Property diffs** - Each changed property is shown inline with the old and new value side by side, with red `-` for removed and green `+` for added
+- **Left sidebar** — lists every node that differs between the two snapshots. Each entry shows a node-type badge (config node, tab, or regular node) and one of three statuses:
+  - **Added** — the node exists in the newer snapshot but not the older one
+  - **Deleted** — the node existed in the older snapshot but has been removed
+  - **Changed** — the node exists in both snapshots but one or more properties differ
+- **Flow canvas** — highlights the selected node and scrolls to it automatically, giving a visual indication of where the change is in your flow
+- **Right panel** — shows the property and code changes for the selected node. Use the **Prev / Next** buttons to step through changes one at a time
+
+Selecting an entry in the sidebar highlights the corresponding node on the canvas. The highlight clears automatically when you select a different entry.
+
+There are two types of diff shown in the right panel:
+
+- **Property diffs** — each changed property is shown with the old and new value side by side, with red `-` for removed and green `+` for added
 
 ![Screenshot showing property-level diff with old and new values displayed side by side](images/snapshots/snapshot-diff-prop-change.png)
 _Screenshot showing property-level diff with old and new values displayed side by side_
 
-- **Code diffs** - For multiline properties — for example in function and template nodes — code changes appear as a line-level diff with red `-` for removed lines and green `+` for added, the same format you'd expect from a git diff
+- **Code diffs** — for multiline properties such as function and template nodes, changes appear as a line-level diff with red `-` for removed lines and green `+` for added, in the same format as a git diff. Use the **Prettify** and **Wrap** toggles to make large or nested values easier to read
 
 ![Screenshot showing a code diff for a function node with red and green line-level changes](images/snapshots/snapshot-diff-code-change.png)
 _Screenshot showing a code diff for a function node with red and green line-level changes_
+
+Not every difference between two snapshots is meaningful. Computed layout properties such as group node `w` and `h` values are automatically excluded because they are recalculated by Node-RED and do not reflect intentional edits. Position-only changes (nodes that moved on the canvas but had no property edits) can be hidden when you want to focus on substantive changes.