diff --git a/crates/oa-desktop/src/guide.rs b/crates/oa-desktop/src/guide.rs
index 6f478f0f..01347c0f 100644
--- a/crates/oa-desktop/src/guide.rs
+++ b/crates/oa-desktop/src/guide.rs
@@ -310,7 +310,7 @@ fn article(topic: Topic) -> Article {
                                 "Use the diagram selector or + View to work with a focused diagram. View properties edits its name, perspective, projection and Saved view visibility. Apply changes commits the view settings.",
                                 "Choose Containment for semantic children, Architecture · allocated work for responsibilities, Functional dataflow for work and exchanges, or Missions & capabilities for outcomes. All relationships explores one layer; OA ↔ SA traceability can show placed elements from both layers and their correspondence lines alongside ordinary relationships.",
                                 "Select an element and edit Semantic parent to change ownership. Use the Allocation palette tool to connect a performer to existing unallocated leaf work in Containment. The relationship can appear as a line there; Architecture · allocated work shows responsibility through nesting instead. Saved visibility filters can hide a line without removing the relationship.",
-                                "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.",
+                                "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 (Arrange elements) arranges the whole view and replaces saved bends and label positions on visible connections whose endpoints are not promoted by folding. Attachment preferences and port anchors stay saved. Undo restores the previous arrangement. Export SVG produces a shareable view.",
                                 "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.",
                             ],
                         ),
@@ -357,7 +357,7 @@ fn article(topic: Topic) -> Article {
                             &[
                                 "Select an architecture connection and drag a segment to add a bend. Right-click a line for Add bend here; right-click a circle for Remove bend. With the canvas focused, Insert adds a bend and Delete removes the selected bend. Drag the label independently. Escape cancels a gesture; Undo reverses one completed drag. Shift+F10 opens the selected diagram item's context menu; use arrow keys and Enter to choose an action.",
                                 "Automatic orthogonal routing avoids cards and container headers where space permits. Amber connections need attention: move an obstructing element or a bend. In Select / move, drag a port to any border of its owner. Manual positions are per diagram; right-click Reset automatic position restores connection-aware placement. Ports remain attached to their actual owners. Manual routes are saved separately for each diagram and appear in source, API and SVG export.",
-                                "Select a connection and drag a square endpoint handle along its element boundary to move its attachment in this view without changing what it connects. If handles overlap, right-click the selected connection or use its Actions menu and choose Move source attachment or Move target attachment, then drag the handle. Connections to semantic ports retain their port attachment; move the port instead. Reset source attachment or Reset target attachment restores that end's automatic placement while preserving the other end, pins and label. Reset routing clears all these route overrides in this view. Auto-layout preserves pins. Moving one endpoint keeps pins fixed; moving a container carrying both endpoints translates their pins. When folding promotes an endpoint, expand it again to resume and edit its saved route.",
+                                "Select a connection and drag a square endpoint handle along its element boundary to move its attachment in this view without changing what it connects. If handles overlap, right-click the selected connection or use its Actions menu and choose Move source attachment or Move target attachment, then drag the handle. Connections to semantic ports retain their port attachment; move the port instead. Reset source attachment or Reset target attachment restores that end's automatic placement while preserving the other end, pins and label. Reset routing clears all these route overrides, including both attachments, in this view. Auto-layout replaces saved bends and label positions on visible connections with their actual endpoints shown; it retains attachment preferences and port anchors. Hidden or folded routes keep their overrides, though saved pins can move with their endpoint owners during arrangement. Undo restores the prior arrangement. During ordinary movement, moving one endpoint keeps pins fixed; moving a container carrying both endpoints translates their pins. When folding promotes an endpoint, expand it again to resume and edit its saved route.",
                             ],
                         ),
                         explain(
diff --git a/docs/language.rst b/docs/language.rst
index 028db93b..06e43fcf 100644
--- a/docs/language.rst
+++ b/docs/language.rst
@@ -1255,6 +1255,55 @@ translates pins when both actual endpoint owners move by the same delta; label
 offsets remain relative. Raw ``EditNode`` and source position edits are exact
 record edits and do not implicitly translate pins.
 
+Explicit ``Layout(diagram)`` (Auto-layout / Arrange elements) is an exception to
+route-override preservation. Immediately before this operation changes geometry,
+it MUST determine eligibility from the staged Project's ordinary filtered
+projection. An edge is eligible only if it is visible, both actual endpoint-owner
+placements exist, both projected owner nodes exist, and its projected source and
+target equal those actual owners in stored orientation. A semantic Port belongs
+to its actual owning placement; hiding its marker does not make the edge
+ineligible. An endpoint promoted to a folded ancestor does. Missing owners MUST
+NOT be inferred. In a Batch, this input includes preceding staged operations;
+determining eligibility MUST NOT introduce separate validation of a batch prefix.
+
+For each existing eligible route entry, Layout MUST clear ``waypoints`` and the
+entire ``label`` override (both fraction and offset). It MUST retain the entry,
+its list position, edge identity, and both attachment values, including dormant
+attachments at semantic ports. Empty and attachments-only entries MUST NOT be
+removed. Layout MUST NOT create route entries merely to record generated elbows
+or automatic label placement. Node port-anchor records remain exact, although
+moving or resizing their owners can change their physical positions.
+
+Ineligible routes, including hidden, filtered and promoted edges, MUST NOT be
+reset. Their labels, attachments, identities and list order remain exact. Their
+waypoints follow the existing movement rule: translate only when both actual
+endpoint-owner placements receive the same nonzero original-to-final delta,
+subject also to the existing State boundary movement rule. For a State Entry/Exit
+endpoint whose owning State boundary has a placement, that boundary placement
+must move with the same delta before the stored pins translate. Otherwise retain
+the waypoint values.
+Promotion to a visible ancestor alone does not authorize translation. Eligibility
+limits route reset, not placement scope: ordinary Layout may still reposition or
+resize hidden and folded descendant placements. Other diagrams remain unchanged.
+
+Placement changes and eligible resets form one atomic Layout mutation. A changed
+standalone Layout creates one history entry; Layout within Batch or execute_many
+shares the enclosing transaction's entry, even when that transaction contains
+several Layout operations. Validate the complete candidate through the ordinary
+transaction path. Rejection leaves the accepted Project and history unchanged;
+an identical enclosing transaction creates no entry and preserves Redo. Undo
+restores the pre-transaction placement and route records. A separately applied
+desktop property draft retains its own history entry; Layout does not merge it.
+
+This exception does not change ordinary dragging, group movement, reconnect,
+folding, filtering, raw ``EditNode`` or source position edits. Reset routing
+remains the distinct whole-entry removal operation, including both attachments.
+Internal State transitions have no external edge eligible for reset. Process
+generated topology is unchanged; saved Scenario layout retains its dedicated
+operation and rejects this Layout command. Automatic elbows remain derived;
+resetting constraints does not guarantee an intersection-free or collision-free
+arrangement.
+
 This is an additive schema-3 field. Earlier schema-3 JSON/source that omits
 ``routes`` loads as an empty list. Frozen schema-1 and schema-2 readers do not
 accept this new field; migration creates empty route lists. Source projects keep