Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

docs: explain explicit via endpoint coordinates (#357)

Sparkle2e197aef68d8
diff --git a/archify.zip b/archify.zip
index 9f943839..d0d5f691 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/references/authoring-contract.md b/archify/references/authoring-contract.md
index ae9bae9a..8e2cb4d6 100644
--- a/archify/references/authoring-contract.md
+++ b/archify/references/authoring-contract.md
@@ -112,6 +112,46 @@ in the generated viewer.
- Container borders are intentional pass-through geometry, but a long edge running along a structural border is not.
- An edge crossing an unrelated opaque node is always a hard failure, independent of quality profile.
+### Explicit `via` coordinates
+
+Use the resolved departure anchor `S = [sx, sy]` and arrival anchor
+`T = [tx, ty]`. Anchors start at side midpoints, but automatic routing and
+Port Spread can move them as described above; do not assume an anchor copied
+from an automatic route is the anchor of a newly authored explicit route.
+Explicit `via` routes do not receive automatic Port Spread.
+
+For the first waypoint `F = via[0]` and last waypoint `L = via[via.length - 1]`,
+use these alignments and directions (SVG y increases downward):
+
+| Side | Departure (`fromSide`): `S` → `F` | Arrival (`toSide`): `L` → `T` |
+| --- | --- | --- |
+| `top` | `F[0] === sx`, `F[1] < sy` | `L[0] === tx`, `L[1] < ty` |
+| `bottom` | `F[0] === sx`, `F[1] > sy` | `L[0] === tx`, `L[1] > ty` |
+| `left` | `F[1] === sy`, `F[0] < sx` | `L[1] === ty`, `L[0] < tx` |
+| `right` | `F[1] === sy`, `F[0] > sx` | `L[1] === ty`, `L[0] > tx` |
+
+For example, given a bottom departure anchor `S = [180, 160]` and a left
+arrival anchor `T = [360, 260]`, this relationship fragment leaves downward
+and enters the target rightward:
+
+```json
+{
+ "from": "source",
+ "to": "target",
+ "fromSide": "bottom",
+ "toSide": "left",
+ "via": [[180, 200], [300, 200], [300, 260]]
+}
+```
+
+The full path is `[180, 160] → [180, 200] → [300, 200] → [300, 260] → [360, 260]`.
+Changing only the first waypoint to `[200, 200]` makes the departure diagonal;
+changing it to `[180, 120]` keeps its x aligned but leaves upward through the
+source instead of outward from its bottom. Both violate `fromSide: "bottom"`
+and produce `clean-flow/endpoint-side-direction`. The example establishes
+endpoint direction only: keep the full route clear of unrelated nodes and
+apply the other geometry rules above.
+
### Spacing and labels
Spacing recommendations mean clear gap between boxes, not center distance. A 200px center distance between 165px-wide nodes leaves only 35px of clear gap.