docs(instances): add detailed instance states list

docs/user/instance-states.md

@@ -0,0 +1,31 @@
+---
+navTitle: Instance States
+navOrder: 10
+---
+
+# FlowFuse Node-RED Instance States
+The following list describes the possible states a hosted or remote Node-RED instance can find itself in.
+
+## Stable States
+
+- **running**: Instance is fully operational. Flows are deployed and executing normally.
+- **suspended**: Instance resources are freed and flows are paused. Can be resumed without redeploying.
+- **stopped**: Instance is not executing any flows and is intentionally shut down.
+- **error**: Instance cannot operate normally due to a critical configuration or runtime issue. Requires user intervention.
+- **crashed**: Instance terminated unexpectedly due to repeated runtime errors or failures.
+- **rollback**: A previous working version of the instance has been restored due to deployment failure or manual revert.
+- **warning**: Instance is running but has non-critical issues (e.g., node failures, resource limits close to threshold).
+- **safe**: Running in safe mode after multiple crashes. Editor works, flows are not started until a deploy action is triggered.
+- **protected**: Editor is disabled. Deployment can only occur via pipeline or controlled automation.
+- **connected**: Instance has established a successful connection to its runtime environment and is reachable.
+
+## Transitional States
+- **loading**: Instance UI or resources are being prepared (initial startup or page load).
+- **installing**: Required packages, dependencies, or container layers are being installed.
+- **starting**: Flows and runtime services are initializing.
+- **stopping**: Flows and runtime services are shutting down gracefully.
+- **restarting**: Instance is stopping and then immediately starting again, typically after a deployment or configuration update.
+- **suspending**: Instance flows are being paused and resources deallocated before entering suspended state.
+- **importing**: An external project or configuration is being applied to the instance.
+- **pushing**: Changes are being uploaded to the runtime or container registry.
+- **pulling**: Artifacts or project content are being fetched from a registry or pipeline source.

docs/user/introduction.md

@@ -141,6 +141,7 @@ FlowFuse supports reading and writing persistent files and persistent context.
 
  ## Working with Instances
 
+ - [Instance States](/docs/user/instance-states.md) - List of states an instance can be in.
  - [Snapshots](/docs/user/snapshots.md) - Create point-in-time backups of your Node-RED instances.
  - [Environment Variables](/docs/user/envvar.md) - How to manage Environment Variables in your Node-RED instances.
  - [Change Project Stack](/docs/user/changestack.md) - How to change an instance stack, for example to upgrade Node-RED.