feat(cli): align with the current public API — Auto Split, Usage, new Creative Lab products, printability / animation / image params, polling + delete fixes [ENG-4062]

README.md

@@ -2,7 +2,8 @@
 
 The command line for the [Meshy AI API](https://docs.meshy.ai/): text-to-3D,
 image-to-3D, text-to-motion, remesh, convert, resize, UV unwrap, rigging,
-animation, retexture, 2D images, multi-color print, Creative Lab products, plus
+animation, retexture, 2D images, printability, auto split, multi-color print,
+Creative Lab products, usage records, plus
 the local helpers a 3D-printing or agent workflow needs. Built for people and
 AI agents: a terminal gets a readable view, a pipe or an agent gets JSON.
 

docs/scripting.md

@@ -80,7 +80,11 @@ one JSON document (`ndjson` streams emit one line per event plus a final
   that also bounds every in-flight GET: a response arriving after the deadline
   is a timeout (exit 8, last status kept, `result.task` null when none arrived
   in time), never a late success, and no request starts once the budget is
-  spent. `stream` follows Server-Sent Events with `--timeout` (total) and
+  spent. Between ticks it sleeps the server's `Retry-After` when one is sent;
+  a status request that fails with a `429`, a `5xx`, a read timeout or a
+  dropped connection is retried at the next tick (`result.wait.failed_polls`,
+  `last_poll_error` and a `poll_retried` warning say so), while a `401`/`404`
+  or a malformed task ends the wait at once. `stream` follows Server-Sent Events with `--timeout` (total) and
   `--idle-timeout` (silence, keep-alives reset it); `-o` downloads the assets
   in every output format, and in `ndjson` the final `outcome` line carries the
   download manifest.
@@ -119,6 +123,7 @@ one JSON document (`ndjson` streams emit one line per event plus a final
 | 11 | local I/O — refused overwrite, path outside the authorised root, journal/project write failure |
 | 12 | check failed (`inspect faces` over the limit) |
 | 13 | check unknown (`inspect faces` without a usable face count) |
+| 14 | conflict (`409`: `delete` of an IN_PROGRESS task — it cannot be stopped and its credits are spent; deleting it after it finishes is permanent, with no refund) |
 | 130 | interrupted (Ctrl-C); nothing was deleted server-side |
 
 ## Agent skill

docs/skill-parity/baseline.json

@@ -25,20 +25,16 @@
       "claude_manifest_version": "0.4.1",
       "usage": "read-only capability baseline; not modified"
     },
-    "meshyd_read_only_crosscheck": {
-      "commit": "69b7ff5dd29f7a75a3220987985037ecb5c13c2e",
-      "files_consulted": [
-        "pkg/server/server.go (public route registration: every task API group registers POST '', GET '', GET /:id, GET /:id/stream, DELETE /:id; openapi /v1/showcases; /web/public/animations/resources)",
-        "pkg/server/api_stream_handlers.go (SSE: event 'message' carries task DTO; event 'error' carries {message,status_code}; keep-alive re-emits 'message' every 10s; stream closes after terminal status)",
-        "pkg/server/internal/httpapi/response.go (APIStreamErrorResponse = {message, status_code})",
-        "pkg/server/internal/httpapi/dto.go (task DTO: model_urls object keys glb/fbx/gltf/usdz/obj/mtl/vox/blend/stl/3mf/pre_remeshed_glb; thumbnail_urls is an object keyed by view; alpha_thumbnail_url; consumed_credits optional; no face_count field)",
-        "pkg/server/creativelab/openapi_routes.go + api_creative_lab_{figure,lamp,keychain,fridge_magnet}_handlers.go (request structs)",
-        "pkg/model/task_creative_lab_{lamp,keychain,fridge_magnet}.go (options/output enums, artifact keys)",
-        "pkg/server/api.go (ListShowcasesForOpenAPIRequest: format oneof glb fbx usdz obj; showcase_type oneof all animate static; GetShowcaseForOpenAPIResult fields; ListAnimationsResourcesRequest: q/category/subCategory; AnimationResource fields)"
+    "api_behaviour_crosscheck": {
+      "observed": [
+        "every task resource answers POST '', GET '', GET /:id, GET /:id/stream and DELETE /:id; showcases are served at /openapi/v1/showcases; the Skill's animation catalog at /web/public/animations/resources",
+        "Server-Sent Events: event 'message' carries the task; event 'error' carries {message, status_code}; a keep-alive re-emits 'message' every 10 s; the stream closes after a terminal status",
+        "task responses: model_urls keys glb/fbx/gltf/usdz/obj/mtl/vox/blend/stl/3mf/pre_remeshed_glb; thumbnail_urls is an object keyed by view; alpha_thumbnail_url; consumed_credits optional; no face_count field",
+        "Creative Lab figure/lamp/keychain/fridge-magnet request fields, option and output enums, artifact keys",
+        "showcases accept format glb|fbx|usdz|obj and showcase_type all|animate|static; the animation catalog accepts q, category and subCategory"
       ],
       "notes": [
-        "internal source copies are not included in this repository",
-        "production deployment state, account gates and billing were not tested"
+        "account availability and billing were not tested"
       ]
     }
   },

docs/skill-parity/capability-matrix.json

@@ -303,7 +303,7 @@
         "T-053"
       ],
       "evidence": [
-        "meshyd api_stream_handlers.go: event message (task), event error {message,status_code}, keep-alive re-emits message every 10 s",
+        "API stream: event message (task), event error {message,status_code}, keep-alive re-emits message every 10 s",
         "stream.ts SSE parser + streamTask; task-command stream (ndjson events + outcome, json envelope); tests/sse.test.ts, T-053",
         "tests/codex-review-round1.test.ts R10/F10",
         "tests/codex-review-round2.test.ts N01 (stream -o), N05 (single outcome on post-stream failures)",
@@ -521,8 +521,8 @@
         "T-020"
       ],
       "evidence": [
-        "docs.meshy.ai/en/api/uv-unwrap (input_task_id|model_url, GLB only, 40k faces, Statsig-gated 404)",
-        "meshyd server.go: /openapi/v1/uv-unwrap registers POST, GET list, GET :id, GET :id/stream, DELETE :id",
+        "docs.meshy.ai/en/api/uv-unwrap (input_task_id|model_url, GLB only, 40k faces; the API returns 404 when the endpoint is not enabled for the account)",
+        "the API serves /openapi/v1/uv-unwrap: POST, GET list, GET :id, GET :id/stream, DELETE :id",
         "src/cmd/uv-unwrap.ts: exclusive source, GLB-only, 404 reported as not_found; tests T-021"
       ],
       "intentional_differences": [],
@@ -589,7 +589,7 @@
       ],
       "evidence": [
         "docs.meshy.ai/en/api/creative-lab-lamp (image_subject; prototype model_urls.glb; build options/output stl|zip; lamp_stl/base_stl/bundle_zip)",
-        "meshyd pkg/model/task_creative_lab_lamp.go artifact keys and enums",
+        "lamp task responses: artifact keys and enums as observed from the API",
         "src/cmd/creative-lab.ts lamp: image_subject, text rejected, options/output stl|zip, include_result_json rule; tests T-022..T-025",
         "tests/codex-review-round1.test.ts R04/F08 (lamp)"
       ],
@@ -639,7 +639,7 @@
       ],
       "evidence": [
         "docs.meshy.ai/en/api/creative-lab-keychain (relief options; output glb|obj|zip; obj is a ZIP bundle)",
-        "meshyd pkg/model/task_creative_lab_keychain.go",
+        "keychain task responses as observed from the API",
         "src/cmd/creative-lab.ts keychain relief options, output glb|obj|zip; tests T-022..T-025",
         "tests/codex-review-round1.test.ts R04/F08 (keychain)"
       ],
@@ -686,7 +686,7 @@
       ],
       "evidence": [
         "docs.meshy.ai/en/api/creative-lab-fridge-magnet (own defaults: rounded-rect, 60 mm, 3.3 mm relief, 2.0 mm base)",
-        "meshyd pkg/model/task_creative_lab_fridge_magnet.go",
+        "fridge-magnet task responses as observed from the API",
         "src/cmd/creative-lab.ts fridge-magnet relief options; tests T-022..T-025",
         "tests/codex-review-round1.test.ts R04/F08 (relief options shared with keychain)"
       ],
@@ -728,7 +728,7 @@
       ],
       "evidence": [
         "Skill pipelines.md: GET /web/public/animations/resources?category=…; response {result:{total,list}}",
-        "meshyd api.go AnimationResource + ListAnimationsResourcesRequest (q, category, subCategory)",
+        "the animation catalog accepts q, category and subCategory",
         "src/cmd/animation-catalog.ts: public transport, no credential, local search; tests T-026"
       ],
       "intentional_differences": [],
@@ -760,7 +760,7 @@
       ],
       "evidence": [
         "docs.meshy.ai/en/api/enterprise-api (1 credit per request; page_size 1-10; sort_by; format; showcase_type)",
-        "meshyd api.go ListShowcasesForOpenAPIRequest: showcase_type oneof all animate static (docs say animated)",
+        "the API accepts showcase_type all|animate|static (docs say animated)",
         "src/cmd/showcases.ts: single billable GET, alias warning, no retry; tests T-027"
       ],
       "intentional_differences": [
@@ -1344,7 +1344,7 @@
         "T-082"
       ],
       "evidence": [
-        "meshyd httpapi/dto.go: public task DTO has no face_count → unknown semantics required",
+        "the API's task responses do not include face_count → unknown semantics required",
         "src/internal/inspect.ts judgeFaceCount/judgeTask + src/cmd/inspect.ts (--max-faces required; unknown exit 13; fail exit 12; remesh only described); tests/inspect.test.ts T-080..T-082"
       ],
       "intentional_differences": [