@vention/vention-skills 0.1.0

package/skills/vention-design/SKILL.md

@@ -0,0 +1,522 @@
+---
+name: vention-design
+description: Create, build and edit Vention machine designs and design graphs for agentic layout. Use when the user wants to start a new design, lay out an automation cell, add or reposition components in a Vention design, generate a machine layout from a description, add or place a floor plan image under a design, list a design's versions, or inspect an existing design graph. Trigger on MachineBuilder designs, design graphs, assembly graphs, extrusions, actuators, robot mounting, cell footprints, floor plans, or a machine-builder URL.
+license: MIT
+metadata:
+  version: "0.1.0"
+  author: Vention
+---
+
+# Vention Design Graphs
+
+Build and modify Vention designs through the Vention MCP server.
+
+## Before you start
+
+Confirm the Vention MCP server is connected by calling `whoami`. If it fails, tell the
+user to connect it and stop.
+
+Everywhere below, `design` accepts either a numeric design id or a MachineBuilder URL
+(`https://vention.com/machine-builder/<id>`). A version segment in a URL is ignored by
+the save tool; `parent_version` is the only version input. Pass version and id values as
+strings (`parent_version: "0"`, `floor_plan_id: "401"`) — that is the verified form.
+
+The available design tools are:
+
+| Tool | What it does |
+| --- | --- |
+| `design_categories_list()` | The category codes `design_create` accepts |
+| `design_create(name, category_code, ...)` | Create a new, empty design; returns `id`, `name`, `url` |
+| `design_versions_list(design)` | Versions newest-first with `num_parts`, `md5`, and the version's floor plan — no graph download |
+| `design_graph_download_url(design, graph_version?)` | Presigned GET for a version's graph; omit `graph_version` for current |
+| `design_graph_upload_create(design)` | Presigned POST for uploading a new graph |
+| `design_version_save(design, upload_key, parent_version, floor_plan_id?)` | Commit an uploaded graph as a new version |
+| `design_floor_plan_upload_create(design, content_type)` | Presigned POST for a floor plan image |
+| `design_floor_plan_create(design, metadata, file_upload_key\|image_id)` | Attach the uploaded image to the design as a floor plan |
+
+The save and floor-plan tools are marked **EXPERIMENTAL — provided without support**,
+and they change real designs. State plainly what a write will change before you make it.
+Get the user's explicit go-ahead before the first write into any design you did not
+create in this session; after that, keep narrating each write without re-asking.
+
+There is no tool to list the user's designs, rename or delete one, or delete a floor
+plan. If you need an existing design, ask for its id or URL — never guess one.
+
+## Creating a design
+
+`design_create(name, category_code, description?, tags?, visibility?)` makes a new,
+empty design in the user's account and returns its `id`, `name` and `url`.
+
+- `category_code` is required and must come from `design_categories_list`. Codes come in
+  two shapes: two letters for a top-level category (`MF` Manufacturing, `AS` Assembly,
+  `MH` Material Handling, `PZ` Packaging, `ME` Other Equipment), and two-plus-two for a
+  subcategory (`MF-RC` Machine Tending, `PZ-CB` Cobot Palletizer, `MH-CV` Conveyors, and
+  so on). Those shapes are just the pattern — the codes above are real, but the list is
+  longer and can change. **Never guess a code.** Call `design_categories_list` and match
+  the user's words; if several plausibly match, or the user named no category, ask.
+- `visibility` is `TEAM` (the default), `ORGANIZATION` or `PRIVATE`. The default shares
+  the design with the user's team — if that's not obviously what they want, ask before
+  creating rather than after.
+- A created design starts with **no graph and no versions at all**:
+  `design_versions_list` returns `[]` and `design_graph_download_url` errors with
+  `NotFound: Design has no assembly graph`. Both are expected, not failures.
+
+### Saving the first version
+
+There is no parent version to start from, so pass **`parent_version: "0"`** on the
+first save into a freshly created design. That is verified to work and produces version
+`1`. You must supply a complete graph yourself, including the `config` vertex — an
+API-created design does not come with one (see the note under the schema below).
+
+## Understanding the design graph
+
+A Vention design is stored as an assembly graph: a set of parts (extrusions, plates,
+actuators, robots, end effectors, loose hardware) plus the mating relationships
+("edges") that position them relative to one another. Editing a design means
+transforming that graph, not editing a 3D scene directly. There is no concept of an
+instanced/referenced sub-assembly in the graph — everything is flattened to individual
+parts, every time.
+
+Graphs are multi-megabyte files. They move by reference, never inline.
+**Never read a graph into the conversation — download it and process it with code.**
+
+### Schema (as observed; may evolve — treat as a map, not a spec)
+
+Field names and shapes below come from reading real graphs, and the app may add or
+change keys. What is dependable is the *structure* — vertices with ids, edges
+referencing vertex ids, the `nextVID`/`nextEID` counters, and the column-major
+`local_matrix`. Preserve keys you don't understand rather than dropping them.
+
+Top level:
+```
+{
+  "format_version": <int>,          // schema version; can differ design-to-design
+  "format_version_initial": <int>,
+  "label": <string>,
+  "attributes": {
+    "design_id": <int>,
+    "design_version": null,
+    "design_bbox": {"min": {x,y,z}, "max": {x,y,z}},
+    "cloned_from": {"design_id": ..., "graph_version": ...},   // optional
+    "measurements": {"type": "face", "visible": true},
+    "feedback": {...}, "cut_to_length": {...}                  // optional
+  },
+  "vertices_by_index": [ <vertex>, ... ],
+  "edges": { "by_id": { "<edge_id>": <edge>, ... } },
+  "nextVID": <int>,   // next free vertex id — must be > every vertex id used
+  "nextEID": <int>    // next free edge id — must be > every edge id used
+}
+```
+
+Vertex (one part/node):
+```
+{
+  "id": <int>,
+  "attributes": {
+    "part_number": <string>,        // absent on the "config" vertex
+    "short_name": <string>,
+    "vertex_type": "part" | "imported_part" | "addon" | "panel" | "config",
+    "local_matrix": {"m": [ ...16 floats... ]},  // absent on some addon parts
+    "opacity": <number>, "visibility": <bool>, "dofs": [...], "hoops_id": <int>
+  },
+  "edges": [ <edge_id>, ... ]   // ids of every edge incident on this vertex
+}
+```
+- `local_matrix.m` is a **column-major 4x4** matrix flattened to 16 values; translation
+  is at indices 12 (x), 13 (y), 14 (z). To rigidly move a part, only touch those three.
+- **Y is Vention's vertical axis — the floor is Y=0.** Not Z. (HOOPS/Three.js viewers
+  default to Y-up, and this matches it.) Confirmed the hard way: a merged design's
+  bbox looked entirely Z-negative, which read as "the whole thing is below the floor
+  on Z" — but the actual symptom (a design sitting sunk about halfway into the ground)
+  came from its Y range straddling 0. Shifting Z did nothing for the sink; shifting Y
+  (`m[13]`) so the bbox's min Y lands at 0 fixed it. **Don't infer the vertical axis
+  from bbox magnitude — check Y first.**
+
+### Coordinate and part reference
+
+An extrusion's own local space runs its length along local Z (0 to L), with a
+45x45mm cross-section (local X/Y ∈ [-22.5, 22.5]) for the common `ST-EXT-001-XXXX`
+line — `XXXX` is the length in mm and must be a multiple of 45. Never invent a length
+that isn't.
+
+Connector strings follow `cma_TYPE|PART_NUMBER|GENDER|FACE_ID`. On extrusions:
+`ca1`-`ca4`/`cb1`-`cb4` are the male end faces (near/far), `ba1`-`ba4`/`bb1`-`bb4` are
+the female T-slots along the length (near/far). `edges.by_id[...].attributes.distance1`
+is the position in mm along the female slot. Gussets (`ST-GP-003-0001`) expose male
+faces `a1`/`a2` (front) and `ab1`/`ab2` (back of the same arms) — using the wrong pair
+flips the gusset's orientation.
+
+This is enough to sanity-check a graph you're editing. For full worked recipes (a
+table-frame leg/rail/gusset layout with exact corner-by-corner rotations, and straight/
+curved conveyor assemblies with their full BOMs and connector maps), see
+`vention-ai-design-skill.md` at the project root — it drives the same graph through
+live browser manipulation (Playwright + webpack-extracted `loadScene`) rather than the
+download/upload/save API this skill uses, but the graph schema, coordinate convention,
+and connector system it documents are the same ones described above.
+
+Two more notes on vertices:
+
+- `vertex_type: "addon"` parts (cable ties, loose hardware counted for BOM only) often
+  have no `local_matrix` and no edges. Don't try to position them.
+- A design that has ever been saved carries one `vertex_type: "config"` vertex holding a
+  `configModels` root object. It is not a physical part. **Preserve it as-is** when
+  merging content into a design; don't delete or overwrite it. A design created through
+  `design_create`, by contrast, has *no graph at all* until your first save — so when
+  you author that first graph, include a config vertex yourself:
+  `{"id": <vid>, "attributes": {"vertex_type": "config", "configModels": {}}, "edges": []}`.
+  Note that `num_parts` in save results and `design_versions_list` counts this vertex,
+  so a graph with one real part reports `num_parts: 2` (verified). Don't read `num_parts`
+  as a BOM count.
+
+Edge (one mating/joint relationship):
+```
+"<edge_id>": {
+  "id": <int>,
+  "attributes": {
+    "connector1": <string>, "connector2": <string>,  // "cma_1|<part_number>|male/female|<port>"
+    "user_specified": <bool>, "distance1": <number>, "edge_type": "connection"
+  },
+  "vertices": [ <vertex_id_1>, <vertex_id_2> ]
+}
+```
+Connector/distance attributes are relative between the two parts, not world-absolute —
+they stay valid under a rigid translation of the parts involved.
+
+IDs (`vertices_by_index[].id`, `edges.by_id` keys) are plain counters, unique within a
+single graph and carrying no meaning across designs. The one invariant that matters is
+that `nextVID`/`nextEID` sit strictly above every id in use; `max(id) + 1` is the
+obvious way to satisfy it. Vertex ids and edge ids count independently.
+Real graphs are not guaranteed to start counting at 1 — vertex ids beginning at
+`4294967296` (2^32) and edge ids at `8589934593` (2^33 + 1) are common. Read the
+existing counters rather than assuming a range.
+
+## Reading a design
+
+Start with `design_versions_list(design)` — it is cheap, downloads nothing, and answers
+most questions on its own. Per version, newest first: `version`, `version_name`,
+`num_parts`, `size_bytes`, `md5`, `created_at`, plus that version's floor plan
+(`floor_plan_url`, `floor_plan_file_name`, `floor_plan_metadata`; all `null` when the
+version has none). Use it to see whether a design has content, how big it is, how many
+parts it holds, and which version you should download — before spending a download.
+
+Two quirks: `size_bytes` and `md5` can come back `null` for a version saved seconds
+ago and fill in shortly after, and `floor_plan_url` expires — call the tool again for a
+fresh link rather than reusing an old one.
+
+Then, only if you need the geometry:
+
+1. `design_graph_download_url(design)` — omit `graph_version` for current. The result
+   gives you `graph_version` — keep it, you'll need it as `parent_version` if you save.
+2. Download the gzip file with a shell command (the tool gives you the exact `curl`)
+   and parse it in code. If it errors `NotFound: Design has no assembly graph`, the
+   design has never had content saved — treat it as blank, but still download it once
+   more right before you save (see below) since that can change.
+
+## Writing a design
+
+1. Transform the graph in code, writing the result to a local file. If you're adding
+   content to an existing design (rather than working from scratch), start from its
+   *current* downloaded graph and append to it — keep its `config` vertex and any
+   existing content, and continue its `nextVID`/`nextEID` counters rather than
+   restarting them.
+2. **Validate before uploading** — cheap and catches most mistakes:
+   - every vertex id and every edge id is unique
+   - every edge's `vertices` entries exist in `vertices_by_index`
+   - every vertex's `edges` entries exist in `edges.by_id`
+   - `nextVID` > every vertex id used, `nextEID` > every edge id used
+3. **Settle `parent_version` before you upload.** Check the design's current version with
+   `design_versions_list` (or `design_graph_download_url`) — don't reuse a number from
+   earlier in your work, since a design can advance versions with no content change (see
+   gotcha below). If it has moved past the version you transformed in step 1, go back to
+   step 1 and redo the edit on the current graph; the work you already did is stale.
+   For the first save into a design created by `design_create`, there is no current
+   version — use `parent_version: "0"`.
+4. `design_graph_upload_create(design)` — mint an upload. Gzip your file, then **POST**
+   it (multipart form) to `post_url` using the returned `form_fields` verbatim, with
+   the file field last. This is not a plain PUT. A `204` with an empty body is success;
+   there is no other confirmation, and the upload changes nothing on its own.
+5. `design_version_save(design, upload_key, parent_version, floor_plan_id?)` — commit as
+   a new version. Rails assigns the number; never pick one yourself. Pass
+   `floor_plan_id` if this version should keep a floor plan (see Floor plans below).
+   If it's rejected as stale, the error names the actual current version; download that
+   version, reapply your change on top of it, **re-upload** (see the next gotcha), and
+   retry.
+
+Saves **append a new immutable version**. They never overwrite the version you started
+from, so the user can always roll back. Saves are only accepted on top of the current
+version — editing an older version is not supported.
+
+### The app normalizes what you save
+
+A minimal hand-authored graph is accepted and then tidied up the next time the design is
+opened and saved in MachineBuilder. Observed across one such round trip:
+
+- `configModels: {}` on the config vertex was replaced with a real root object
+  (a uuid keyed to `{"id", "type": "root", "properties": {"version": 37}, "parentId":
+  null, "childrenIds": []}`). So an empty object is a valid thing to author — the app
+  fills it in.
+- `opacity: 1` and `visibility: true` were added to the part vertex.
+- `format_version` was rewritten `28 → 29`, with `format_version_initial` left at `28`.
+  Don't hardcode a `format_version`; carry over whatever the design currently reports,
+  and expect the app to raise it.
+- `design_bbox` was reset to all zeros, discarding the extents that were written into
+  it. Treat the bbox as app-maintained: read it for sizing decisions if it looks
+  populated, but don't count on a value you write surviving, and don't treat zeros as
+  meaning the design is empty.
+
+Geometry itself came back untouched — part number, `short_name` and `local_matrix`
+survived exactly. The lesson is to author the minimum honestly and let the app enrich
+it, rather than trying to synthesize fields you haven't observed.
+
+### Gotcha: a rejected save destroys your upload
+
+A stale-`parent_version` rejection consumes the uploaded file anyway. Retrying the save
+with a corrected `parent_version` and the same `upload_key` fails with
+`NotFound: no uploaded file at this key`. Every save attempt — including a retry after
+a rejection — needs a fresh `design_graph_upload_create` and a fresh POST. Verified.
+
+### Gotcha: a live browser session can fork the version history
+
+If the user has the design open in MachineBuilder while you save via the API, its tab
+keeps auto-saving on its own timeline — even with zero content changes (observed: v3 →
+v5 with an identical empty graph). Your API save branches off whatever version was
+current *at that moment* (e.g. v5 → v6), but the live tab has no idea your v6 exists
+and just keeps auto-saving its own sibling branch (e.g. v5 → v5.1). The user opening
+the design in their browser will see the live branch, not yours, even though yours has
+your changes.
+
+Fix: tell the user to open the specific version number you saved in MachineBuilder and
+save from there — that makes the editor adopt it as the branch it continues on. Warn
+them about this explicitly whenever you save into a design you know is open live.
+
+## Floor plans
+
+A floor plan is a plan-view image (JPEG, PNG or BMP) attached to a design so a layout
+can be built on top of the real building. It lives entirely on the version pin —
+**a downloaded graph contains no reference to the floor plan at all** (verified by
+diffing a graph before and after a floor plan was added), so `floor_plan_id` on the save
+is the whole mechanism. Nothing about it needs to go into the graph JSON.
+
+Adding one takes **four** steps — three to create it, then a save to pin it. Stopping
+after step 3 attaches the floor plan but displays it nowhere; that is the step most
+easily forgotten:
+
+1. `design_floor_plan_upload_create(design, content_type)` — mint a presigned POST.
+   `content_type` must be one of `image/jpeg`, `image/png`, `image/bmp`, and must be
+   sent back as the `Content-Type` form field (unlike the graph upload, the floor-plan
+   form fields include it). **The cap is 5 MB** (`max_bytes: 5242880`) — much tighter
+   than the graph upload's 100 MB. Check the file size before minting; if it's over,
+   downscale the image rather than retrying.
+2. POST the image multipart to `post_url` with every `form_fields` pair verbatim and
+   the file part last. A 204 is success.
+3. `design_floor_plan_create(design, metadata, file_upload_key: <key>)` — turns the
+   upload into a floor plan on the design. Returns `floor_plan_id`, plus `image_url` and
+   `image_file_name`. **Record the `floor_plan_id` and the image id from `image_url` in
+   your reply to the user** — see the recovery note below for why. (`image_file_name`
+   will be the upload key's UUID, not the user's filename, since the API mints the key;
+   a UI upload keeps the original name. Nothing depends on it.)
+4. `design_version_save(design, upload_key, parent_version, floor_plan_id: "<id>")` —
+   pin it. Until a version pins it, the floor plan is displayed nowhere.
+
+Step 4 is a normal graph save, so it needs a graph: follow "Writing a design" above. To
+add a floor plan without changing geometry, download the current graph and re-upload it
+unmodified with the `floor_plan_id` set.
+
+### Pinning is per-version, and silently drops
+
+`floor_plan_id` is not sticky. **Omit it on a later save and the new current version has
+no floor plan** — verified: v1 saved with `floor_plan_id` had the plan, v2 saved without
+it came back with `floor_plan_url: null`, and the design showed no floor plan even
+though nothing was deleted. Nothing warns you.
+
+So before any save into a design that has a floor plan, check the current version's
+floor plan with `design_versions_list` and restate its `floor_plan_id` on your save.
+
+### Recovering a floor_plan_id you don't have
+
+`design_versions_list` returns `floor_plan_url`, `floor_plan_file_name` and
+`floor_plan_metadata` — **not `floor_plan_id`**. The only place the id appears is the
+return value of `design_floor_plan_create`, so an id created in an earlier session is
+not directly recoverable, and there is no tool that lists a design's floor plans.
+
+What *is* recoverable is the **image id**, from the `floor_plan_url` path
+(`.../design_floor_plan_image/file/396/…` → `396`). So to keep a floor plan whose id you
+have lost: read the current version's `floor_plan_metadata` and image id from
+`design_versions_list`, call `design_floor_plan_create` again with that `image_id` and
+that same metadata, and pin the fresh `floor_plan_id` it returns. The image is not
+re-uploaded and the placement is preserved — you just get a new record pointing at the
+same image.
+
+Because of this, always surface the `floor_plan_id` to the user when you create one, so
+it is in the conversation rather than only in a tool result.
+
+### Reusing and repositioning an image
+
+`design_floor_plan_create` takes **either** `file_upload_key` (a fresh upload) **or**
+`image_id` — never both. `image_id` is the numeric id in the returned `image_url` path
+(`.../design_floor_plan_image/file/396/...` → `image_id: "396"`), and it lets you create
+a second floor plan from an image already uploaded. That is how you reposition or
+rescale a plan: create a new floor plan record from the same `image_id` with different
+`metadata`, then pin the new `floor_plan_id`. Verified. Don't re-upload the image to
+move it.
+
+Floor plans accumulate on the design and there is no delete tool, so don't churn out
+records experimentally.
+
+### The metadata field
+
+`metadata` is required, stored **verbatim**, and **not validated by the tool** — a wrong
+shape is accepted happily and then simply fails to place the image. So write exactly
+what MachineBuilder itself writes. This is the shape the UI produces, read back from a
+UI-created floor plan (verified):
+
+```json
+{
+  "version": 1,
+  "fileSize": 179580,
+  "dimensions": { "width": 578, "height": 596 },
+  "matrix": [12731.246649383824, 0, 0, 0,
+                             0, 1, 0, 0,
+                             0, 0, 13127.721458534186, 0,
+                             0, 0, 0, 1]
+}
+```
+
+- `version` — the metadata schema version. `1` at time of writing. Copy the existing
+  value when editing a design that already has a floor plan.
+- `fileSize` — the image's size in bytes.
+- `dimensions` — the image's pixel width and height.
+- `matrix` — a **flat 16-float column-major 4x4**, at the top level. Note it is *not*
+  nested under a `transform` key and there is no `fileName` key. Don't add keys the app
+  doesn't write.
+
+### How the matrix works
+
+It scales a unit plane onto the floor, in the graph's own Y-up convention:
+
+- `matrix[0]` = the plan's **X extent in mm**, `matrix[10]` = its **Z extent in mm** —
+  both horizontal, matching Y being vertical.
+- `matrix[5]` = `1`. The plane has no thickness; leave it at 1.
+- `matrix[12..14]` = translation, `0, 0, 0` in the observed case. Off-diagonal terms
+  were all zero — no rotation or shear.
+
+The two extents encode one uniform scale. In the observed floor plan,
+`12731.2466 / 578 == 13127.7215 / 596 == 22.026378` mm per pixel, and the extents'
+ratio matches the image aspect ratio exactly. So to build a matrix:
+
+```
+s  = millimetres per pixel          # from the user, or from a known real-world dimension
+sx = dimensions.width  * s
+sz = dimensions.height * s
+matrix = [sx,0,0,0,  0,1,0,0,  0,0,sz,0,  tx,ty,tz,1]
+```
+
+That plan was 578 x 596 px at 22.026 mm/px — 12.73 m x 13.13 m of floor. **Ask the user
+for the scale**; never assume one. The cleanest question is what a known distance on the
+drawing measures in the real building, then divide by its pixel length.
+
+> **Still unverified:** where the plane's origin sits — whether zero translation puts
+> the image's corner or its centre at the world origin — and whether the app honours a
+> non-zero translation or rotation written through the API. Only the zero-translation
+> case has been observed. When you write a floor plan, say the placement needs a look,
+> ask the user to confirm the image lands where they expect, and offer to adjust. Don't
+> call a floor plan correctly placed because the API calls succeeded.
+
+## Duplicating / placing a copy of an existing design
+
+There's no sub-assembly instancing in this graph format — "place a copy of design X"
+means deep-copying its parts and joints, not inserting a reference:
+
+1. Download the source design's current graph.
+2. For each copy you want: deep-copy every vertex and every edge, assigning fresh ids
+   (continue counting up from the target's `nextVID`/`nextEID`), remapping the vertex
+   ids referenced in each edge's `vertices` and each vertex's `edges` list consistently.
+3. Rigidly offset each copy so copies don't overlap: add a delta to `m[12]`/`m[13]`/
+   `m[14]` (x/y/z translation) on every vertex in the copy that has a `local_matrix`.
+   Skip vertices without one (e.g. `addon` parts) — leave them untouched. Size the
+   offset using the source's `design_bbox` extent plus a margin, along **X or Z** — a
+   horizontal axis. Offsetting along Y (`m[13]`) would lift the copy off the floor or
+   sink it into the ground, since Y is the vertical axis.
+   Leave edge attributes (connector strings, `distance1`) unchanged — they're
+   part-relative and remain valid under a rigid translation.
+4. Merge the copies' vertices/edges into the target's existing `vertices_by_index` /
+   `edges.by_id` (keeping the target's own `config` vertex and any existing content),
+   recompute `design_bbox` as the union, and set `nextVID`/`nextEID` past every id used.
+5. Run the validation pass above before uploading.
+
+If the source's `format_version` differs from the target design's, treat the merge as
+unverified: the JSON can be structurally self-consistent and still render wrong if the
+app expects newer-schema shapes the older source never had. Say so to the user and ask
+them to visually confirm the result in MachineBuilder rather than asserting it worked.
+
+## Working practice
+
+Establish the requirement before building anything. Ask for whatever is missing:
+
+- The part or payload — dimensions, weight, orientation
+- The process — pick and place, palletizing, machine tending, assembly
+- The robot, if one is specified, and its reach and payload needs
+- The available footprint and any fixed obstacles — if they have a plan-view drawing of
+  the space, offer to attach it as a floor plan and lay the cell out on it
+- Throughput target
+
+Then plan the layout before writing any graph: place the robot first, then position
+peripherals inside its reach envelope, then add structure.
+
+## Rules
+
+- Never invent a Vention part number. Use parts you found in an existing graph or that
+  the user supplied.
+- Never invent a `category_code`. Read them from `design_categories_list`.
+- Never invent load ratings, reach figures, or payload capacities.
+- Report what you changed, in plain language, before the user opens the design.
+- If a save fails validation, show the user the errors rather than retrying blindly.
+- The save and floor-plan tools are experimental and act on real designs in the user's
+  account. Confirm before the first write into a design you didn't create this session.
+
+## Safety
+
+A generated layout is an engineering starting point, not a validated machine. Never
+describe one as safety-validated, compliant, or ready to build. Always tell the user to
+review the result in MachineBuilder, run the Automated Design Checker, and have any
+safety-relevant design reviewed by a qualified engineer before anything is built.
+
+## Common mistakes
+
+- Downloading a graph into context instead of into a file. Graphs are far too large.
+- Assuming a save overwrites the current version. It appends a new one.
+- Assuming the vertical axis from a bbox's magnitude or sign instead of checking Y
+  directly. Y is the floor-level axis (Y=0); guessing Z produced a fix that moved the
+  design sideways and left it still sunk into the ground.
+- Reusing a `parent_version` from earlier in a session instead of re-checking current
+  right before saving — sessions and live browser tabs can both advance it.
+- Saving into a design that's open live in the user's browser without warning them
+  about version forking (see gotcha above), leaving them looking at the wrong branch.
+- Treating a graph download error as fatal without retrying. Read the message:
+  `NotFound: Design has no assembly graph` means the design is genuinely blank — accept
+  it and move on. Anything else, including a version that was saved moments ago and
+  isn't downloadable yet, is worth one retry before you report a problem.
+- Designing past the robot's reach envelope because the reach figure was assumed rather
+  than looked up.
+- Treating `design_versions_list` returning `[]`, or `NotFound: Design has no assembly
+  graph`, as a failure. On a freshly created design both are the expected answer.
+- Guessing a `parent_version` for the first save into a new design instead of using `"0"`.
+- Retrying a stale-rejected save with the same `upload_key`. The file is already gone —
+  mint a new upload and POST again.
+- Omitting `floor_plan_id` on a save into a design that has a floor plan, silently
+  dropping it from the new current version.
+- Uploading a floor plan image and stopping there. Nothing is attached until
+  `design_floor_plan_create`, and nothing is visible until a save pins the id.
+- Re-uploading a floor plan image just to move it, instead of creating a new floor plan
+  from the same `image_id` with a different transform.
+- Sending a floor plan image over the 5 MB cap, or with a `content_type` other than
+  JPEG/PNG/BMP.
+- Reporting a floor plan as correctly placed because the API calls succeeded. The
+  metadata is stored unvalidated; only the user looking at the design confirms placement.
+- Inventing a floor-plan `metadata` shape. Write the UI's shape — flat top-level
+  `matrix`, `version`, `fileSize`, `dimensions` — not a plausible-looking alternative.
+- Assuming a scale for a floor plan image. Ask what a known distance on the drawing
+  measures in the building.
+- Hardcoding `format_version`, or trusting a `design_bbox` you wrote to survive a save.
+- Downloading a graph to answer a question `design_versions_list` already answers
+  (part count, size, whether the design has content, which version to use).