Compose reviewed attachments and State bends with saved Scenario

docs/api.rst

@@ -329,6 +329,37 @@ authored files and revision. JSON/source imports may omit ``port_anchors``;
 it defaults to ``[]`` and empty lists are omitted on export. The normative
 diagram semantics and source spelling are in ``language.rst`` section 5.
 
+Diagram connection attachments
+-------------------------------
+
+``EdgeRoute.source_attachment`` and ``target_attachment`` are optional
+``{"side":"Bottom","offset":0.25}`` records. Side and a finite offset in
+``[0,1]`` are required within a supplied record; unknown fields are rejected.
+Absence/null means automatic placement. Omitted fields in older schema-3
+models retain that meaning. The normal transaction endpoint accepts::
+
+    {"commands":[{"SetEdgeRoute":{
+      "diagram":"<diagram UUID>",
+      "route":{"edge":"<relation or trace UUID>",
+        "source_attachment":{"side":"Bottom","offset":0.25},
+        "waypoints":[],"label":null}
+    }}]}
+
+``SetEdgeRoute`` replaces the complete route entry. Clients changing one end
+must retain its other attachment, bends and label; omit/null only the intended
+attachment to restore that end's automatic position. ``RemoveEdgeRoute`` resets
+all presentation for that edge. Both support ETag checking, dry runs, atomic
+validation and source-project writeback. Invalid offsets reject the whole
+transaction without changing files or revision.
+
+These are per-view presentation preferences, not a semantic reconnect. Fractions
+follow the projected shape, including moves/resizes; semantic reconnect retains
+them as preferences of the same edge-end slots. Real semantic ports take
+precedence, and promoted folded endpoints suspend authored routing. The complete
+boundary mapping, lifecycle and generated-view limitations are normative in
+``language.rst`` section 5. GET model/source, PUT source, desktop and transactions
+share this representation; no separate attachment endpoint exists.
+
 Contextual process and chain topology
 -------------------------------------