Add instructions to work around counter-intuitive child ordering #28 #32

This is a temporary solution until the issue can be resolved in the API

mcp-server/data/prompts.yml

@@ -58,6 +58,7 @@ initial_instructions: |
     * The z-order of shapes is determined by the order in the `children` array of the parent shape.
       Therefore, when creating shapes that should be on top of each other, add them to the parent in the correct order
       (i.e. add background shapes first, then foreground shapes later).
+      CRITICAL: NEVER use the broken function `appendChild` to achieve this, ALWAYS use `parent.insertChild(parent.children.length, shape)`
     * To modify z-order after creation, use these methods: `bringToFront()`, `sendToBack()`, `bringForward()`, `sendBackward()`,
       and, for precise control, `setParentIndex(index)` (0-based).
 
@@ -69,7 +70,10 @@ initial_instructions: |
   **Hierarchical Structure**:
     * `parent` - The parent shape (null for root shapes)
       Note: Hierarchical nesting does not necessarily imply visual containment
-    * Reparenting: `newParent.appendChild(shape)` or `newParent.insertChild(index, shape)` - Move shape to new parent
+    * CRITICAL: To add children to a parent shape (e.g. a `Board`):
+      - ALWAYS use `parent.insertChild(index, shape)` to add a child, e.g. `parent.insertChild(parent.children.length, shape)` to append
+      - NEVER use `parent.appendChild(shape)` as it is BROKEN and will not insert in a predictable place (except in flex layout boards)
+    * Reparenting: `newParent.appendChild(shape)` or `newParent.insertChild(index, shape)` will move a shape to new parent
       - Automatically removes the shape from its old parent
       - Absolute x/y positions are preserved (use `penpotUtils.setParentXY` to adjust relative position)
 
@@ -92,9 +96,14 @@ initial_instructions: |
       - When a board has flex layout, 
          - child positions are controlled by the layout system, not by individual x/y coordinates;
            appending or inserting children automatically positions them according to the layout rules.
-         - CRITICAL: For for dir="column" or dir="row", the order of the `children` array is reversed relative to the visual order, but insertion indices correspond to visual order,
+         - CRITICAL: For for dir="column" or dir="row", the order of the `children` array is reversed relative to the visual order!
-           i.e. inserting at index 0  places the child visually first, but the child will actually last in the `children` array.
+           Therefore, the element that appears first in the array, appears visually at the end (bottom/right) and vice versa.
            ALWAYS BEAR IN MIND THAT THE CHILDREN ARRAY ORDER IS REVERSED FOR dir="column" OR dir="row"!
+      - CRITICAL: The FlexLayout method `board.flex.appendChild` is BROKEN. To append children to a flex layout board such that
+        they appear visually at the end, ALWAYS use the Board's method `board.appendChild(shape)`; it will insert at the front
+        of the `children` array for dir="column" or dir="row", which is what you want. So call it in the order of visual appearance.
+        To insert at a specific index, use `board.insertChild(index, shape)`, bearing in mind the reversed order for dir="column" 
+        or dir="row".
       - To modify spacing: adjust `rowGap` and `columnGap` properties, not individual child positions
     
     * **Grid Layout**: A CSS grid-style layout system