From 9059dc7795f6cc0d3124b018bc1e0424ee5eea97 Mon Sep 17 00:00:00 2001
From: Marko Anastasov <marko@superplane.com>
Date: Fri, 20 Feb 2026 11:15:53 +0100
Subject: [PATCH 1/2] Update CLI get canvas docs, give example YAML.

Changes made by Codex who had to reach for superplane source code to
understand how to add a component to a canvas.

Signed-off-by: Marko Anastasov <marko@superplane.com>
---
 src/content/docs/concepts/canvas.md  |  4 +--
 src/content/docs/installation/cli.md | 54 ++++++++++++++++++++++++++++
 2 files changed, 56 insertions(+), 2 deletions(-)

diff --git a/src/content/docs/concepts/canvas.md b/src/content/docs/concepts/canvas.md
index 79010a4..7c396a2 100644
--- a/src/content/docs/concepts/canvas.md
+++ b/src/content/docs/concepts/canvas.md
@@ -53,13 +53,13 @@ Use the SuperPlane CLI to manage canvases programmatically:
 
 ```sh
 # Export a canvas
-superplane get canvas <canvas_name> > my_canvas.yaml
+superplane canvases get <canvas_name> > my_canvas.yaml
 
 # Edit the YAML file
 # ... make your changes ...
 
 # Apply updates
-superplane update -f my_canvas.yaml
+superplane canvases update -f my_canvas.yaml
 ```
 
 ## The Canvas Page
diff --git a/src/content/docs/installation/cli.md b/src/content/docs/installation/cli.md
index 3b791fc..d70fc00 100644
--- a/src/content/docs/installation/cli.md
+++ b/src/content/docs/installation/cli.md
@@ -63,6 +63,60 @@ superplane canvases get <canvas_name> > my_canvas.yaml
 superplane canvases update -f my_canvas.yaml
 ```
 
+### Canvas YAML shape (minimal working example)
+
+When updating canvases via YAML, component nodes and edges must use the API field names.
+
+This example connects a `schedule` trigger to an `http` component that sends a keepalive
+request every minute:
+
+```yaml
+apiVersion: v1
+kind: Canvas
+metadata:
+  id: <canvas_id>
+  name: Store app
+spec:
+  edges:
+    - sourceId: schedule-schedule-w3mak1
+      targetId: http-keepalive-ping
+      channel: default
+  nodes:
+    - id: schedule-schedule-w3mak1
+      name: schedule
+      type: TYPE_TRIGGER
+      trigger:
+        name: schedule
+      paused: false
+      position:
+        x: 144
+        y: 0
+      configuration:
+        type: minutes
+        minutesInterval: 1
+        customName: Keepalive {{ now() }}
+    - id: http-keepalive-ping
+      name: http
+      type: TYPE_COMPONENT
+      component:
+        name: http
+      paused: false
+      position:
+        x: 456
+        y: 0
+      configuration:
+        method: GET
+        url: https://store-app-c6nr.examplepaas.com/
+        customName: PaaS keepalive
+```
+
+Notes:
+
+- For component nodes, `type` must be `TYPE_COMPONENT` and `component.name` is required.
+- For trigger nodes, use `type: TYPE_TRIGGER` and `trigger.name`.
+- Edge fields are `sourceId`, `targetId`, and optional `channel`.
+- Use `superplane components list` to find component keys (for example, `http`, `if`, `noop`).
+
 ## Discovering components
 
 ### List integrations

From ca6f2407147749ee9f711f47ca59ef134aa15029 Mon Sep 17 00:00:00 2001
From: Marko Anastasov <marko@superplane.com>
Date: Fri, 20 Feb 2026 11:23:39 +0100
Subject: [PATCH 2/2] Component positioning instructions for agents.

Signed-off-by: Marko Anastasov <marko@superplane.com>
---
 src/content/docs/installation/cli.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/src/content/docs/installation/cli.md b/src/content/docs/installation/cli.md
index d70fc00..590b5a8 100644
--- a/src/content/docs/installation/cli.md
+++ b/src/content/docs/installation/cli.md
@@ -116,6 +116,11 @@ Notes:
 - For trigger nodes, use `type: TYPE_TRIGGER` and `trigger.name`.
 - Edge fields are `sourceId`, `targetId`, and optional `channel`.
 - Use `superplane components list` to find component keys (for example, `http`, `if`, `noop`).
+- Positioning guideline for agents:
+  - Keep downstream nodes on the same row by default (`y` unchanged).
+  - Use `x = upstream.x + 480` as the default spacing for new connected nodes.
+  - Avoid changing positions of existing nodes unless explicitly requested.
+  - If overlap still appears in UI, apply a small horizontal nudge (`x +/- 80..120`) before changing `y`.
 
 ## Discovering components