Specify focused removal semantics and document diagram shortcuts

crates/oa-desktop/src/guide.rs

@@ -310,7 +310,7 @@ fn article(topic: Topic) -> Article {
                                 "Choose Containment for semantic children, Architecture · allocated work for responsibilities, Functional dataflow for work and exchanges, or Missions & capabilities for outcomes. All relationships is a broader exploration view; OA ↔ SA traceability displays counterparts.",
                                 "Select an element and edit Semantic parent to change ownership. Use an Allocation relationship to change responsibility. Apply changes validates the semantic change.",
                                 "Scroll to zoom and use Fit to frame the current view. In allocated-work views, dragging work changes its assignment and placement together. Choose Arrange next drag or press Alt+A to move work without changing responsibility for that one drag; Escape cancels the armed action. Auto-layout arranges the whole view. Export SVG produces a shareable view.",
-                                "Select a diagram node to access Placement, Fold / unfold and Hide. Hide removes its view placement; Delete from model removes model records and requires review of the affected references.",
+                                "Select a diagram node to access Placement, Fold / unfold and Hide. With the canvas focused, Delete hides its placement; Shift+Delete asks to remove the model element. Other views retain a hidden element. Undo restores either change.",
                             ],
                         ),
                         explain(
@@ -570,7 +570,7 @@ fn article(topic: Topic) -> Article {
                         ),
                         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.",
+                            "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. With the canvas focused, Delete hides a selected state placement; Shift+Delete confirms model removal. Delete on an action or internal-transition row confirms removal of that relation, preserving its states and referenced work. Escape cancels a drawing gesture. Undo restores each completed edit, and Model checks identifies unfinished structures.",
                         ),
                         explain(
                             "One saved diagram across editors",
@@ -978,6 +978,10 @@ fn article(topic: Topic) -> Article {
                             "Shortcuts act on the current project. In Textual model, undo and redo affect the source draft.",
                             "Ctrl+N          New project\nCtrl+O          Open model\nCtrl+S          Save all\nCtrl+Shift+S    Save as\nCtrl+Z          Undo\nCtrl+Shift+Z    Redo\nCtrl+Y          Redo\nEscape          Cancel the active dialog",
                         ),
+                        explain(
+                            "Remove a diagram item",
+                            "Click the diagram to give it keyboard focus. Delete hides an architecture or state placement; Shift+Delete asks to remove its model element. A selected route bend is removed first. Process and scenario items, links, and state action rows use confirmation for either key because they have no separate placement. Removing an occurrence preserves its reusable definition. Removing a scenario participant retains its messages with affected participant references cleared; removing a fragment also removes its owned branches and steps. Read the captured target and effect before confirming. Escape cancels, and Undo restores the complete change. Inside an expanded reusable process, open its definition to edit its contents, or select the outer reference to remove that use. Text fields keep their normal Delete behavior.",
+                        ),
                         walkthrough(
                             "Save and share a model",
                             &[

docs/language.rst

@@ -2083,6 +2083,46 @@ exchanges it references. Cross-layer counterparts are not owned descendants.
 Text edits describe a complete candidate and must remove or repair dependencies
 explicitly before Apply succeeds.
 
+8.1. Focused diagram removal
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Delete is scoped to the focused diagram and the exact visible selection.
+Text fields retain their own Delete behavior; diagram shortcuts MUST NOT apply
+pending property, source or behavior drafts. Keyboard traversal retires diagram
+input admission before subsequent keys in the same event batch are processed.
+Active placement, creation, connection, reorder and pan gestures do not authorize
+removal. A stale document, revision, owner or selection MUST NOT redirect removal.
+
+For an explicit architecture or state placement, Delete removes that placement
+only. The semantic element and its placements in other views remain. Shift+Delete
+requests confirmed deletion of the semantic element, including when selection
+originated from Placement properties. A selected architecture route bend takes
+priority: plain Delete removes the bend without removing its edge.
+
+A visible relation with no placement, including a state action or internal
+transition row, uses confirmed relation deletion for either key. States and
+referenced Activity/Function definitions remain. Hidden or collapsed rows are
+not keyboard deletion targets.
+
+Process and scenario projections have no independent occurrence placements.
+Delete and Shift+Delete request confirmed removal of the selected occurrence,
+participant or maintained link. A link's endpoints and outbound reusable
+definitions are preserved. Removing a fragment or branch removes its owned
+subtree. Removing a scenario participant preserves its represented element and
+retains occurrences with affected participant references cleared; resulting
+incomplete references remain visible for repair. The modeled scenario Delete
+message is a separate domain event and is not this editing shortcut.
+
+A qualified selection inside an expanded reusable process MUST NOT silently
+delete the outer reference or shared definition item. The editor directs the
+user to open the definition or explicitly select the outer reference.
+
+Confirmation identifies the captured object and removal effect. Cancel and
+Escape preserve model, source and history. A confirmation token belongs to one
+dialog; changes to its document, revision, owner or selected identity invalidate
+it. Accepted deletion uses one ordinary model/source transaction, and Undo
+restores the exact complete accepted source bundle and model.
+
 9. Persistence and explicit migration
 -------------------------------------