Document direct state diagram authoring workflows

crates/oa-desktop/src/guide.rs

@@ -467,18 +467,26 @@ fn article(topic: Topic) -> Article {
             const {
                 Article {
                     summary: "Describe the conditions in which the operation or system behaves differently. States and modes belong to regions within a state machine.",
-                    keywords: "state machine mode region initial final transition trigger guard effect entry exit do availability degraded nominal",
+                    keywords: "state machine mode region initial final transition trigger guard effect entry exit do availability degraded nominal diagram draw reconnect local internal timed fold unfold placement pan zoom undo",
                     sections: &[
                         walkthrough(
                             "Build a state machine",
                             &[
-                                "In Behavior & scenarios, create a State machine and select it. Use + Region to give its state structure an owner.",
-                                "Use + State for conditions such as Nominal and Degraded, and + Initial for the starting pseudostate. Select a region and use Create element for other supported state kinds.",
-                                "Select a source state and choose + Relationship → State transition. Pick a compatible target in the same state machine.",
-                                "Edit the transition's Trigger, Guard and Effect in Properties. These distinguish what initiates the transition, what must be true, and what follows.",
-                                "Review the rendered state view and numbered transition list. Model checks calls out unfinished structures so they can be corrected during authoring.",
+                                "In Behavior & scenarios, create or select a State machine, then choose Create diagram. This places its existing regions and vertices in a saved view. + View creates another independent layout.",
+                                "Choose + Region and click the highlighted machine, or a State/Mode for a nested region. Choose Initial, State, Mode or another kind from + State / symbol, then click its highlighted owning region. Rename the new element in Properties.",
+                                "Choose Transition and drag from a source vertex to a compatible target, or click the source and then the target. In Select / move, drag states or containers to arrange them; a container moves its descendant placements without changing ownership.",
+                                "Select a drawn transition and drag its endpoint handle to reconnect it. Its right-click menu also offers Reconnect source and Reconnect target; choose one, then click a compatible vertex.",
+                                "Right-click a state or the background for New transition with details… to create Local, Internal or timed behavior. Right-click an existing transition and choose Edit transition to edit its kind, triggers, guard and effects. EntryPoint outgoing transitions use Local. Apply accepts the complete form; invalid drafts remain available for correction.",
                             ],
                         ),
+                        explain(
+                            "Navigate and recover a view",
+                            "Middle-button drag pans; scroll or use −/+ to zoom, and Fit frames the diagram. Right-click a container for Fold contents or Unfold contents, or choose Placement properties for exact coordinates and size. Hide from this diagram removes only its placement; Show an element not yet in this view restores missing elements. Escape cancels a drawing gesture. Undo restores each completed gesture or menu edit, and Model checks identifies unfinished structures.",
+                        ),
+                        explain(
+                            "One saved diagram across editors",
+                            "Each state view stores a reference to its state machine and its own placements. Text, JSON and REST edit those same diagram records, including the persisted machine context; saving and reopening retains them. Merely opening the behavior page does not create a diagram. State-view edits preserve other diagram layouts.",
+                        ),
                         explain(
                             "Availability and state actions",
                             "Availability links a participant or behavior to a State/Mode in which it is available. State action links a State/Mode to an Activity/Function and records its entry, do or exit phase. Use these typed relationships when work depends on operating conditions.",