feat(3d): expose the Meshy 7 surface and correct the stale model docs

[raybobo]

Why

The 3D commands were written when the server's latest meant Meshy 6. It has since moved to Meshy 7 on image-to-3d, multi-image-to-3d and retexture — so the CLI has been running Meshy 7 for a while while telling users otherwise. --model-type --help still read "standard (default; meshy-6 full-detail generation)", and three source headers claimed latest = meshy-6.

None of the Meshy 7 knobs were reachable except through --data.

What changed

image-to-3d	new --ultra-mode <bool>
retexture	new --multiview-image-urls <csv> (1–4 views of the same object)
image-to-3d / multi-image-to-3d	help text + comments corrected to meshy-7
text-to-3d	comments now state its model set has no meshy-7

--multiview-image-urls goes through the normal file-input resolver, so local paths work like every other media flag. The three style inputs (--text-style-prompt / --image-style-url / --multiview-image-urls) now reject each other instead of letting the API silently drop one.

Verified against production, not against the changelog

Every claim below came from zero-credit 400 probes on the live API. Two of them contradict what was written down:

1. ultra_mode does not exist on multi-image-to-3d.

POST /multi-image-to-3d {"ultra_mode":123}
→ no unmarshal error; the field is silently ignored
POST /image-to-3d       {"ultra_mode":123}
→ "cannot unmarshal number into Go struct field CreateImageTo3DRequest.ultra_mode of type bool"

Silently ignored is worse than rejected — a flag there would have looked like it worked. So --ultra-mode lands on image-to-3d only, and a surface test pins it there.

Its gate, confirmed:

{"ai_model":"meshy-6","ultra_mode":true}            → "ultra_mode is only supported for meshy-7"
{"model_type":"smart-topology","ultra_mode":true}   → "ultra_mode is only supported for meshy-7"
{"ultra_mode":true}  (no ai_model)                  → passes the gate

Omitting ai_model passes, so the "mode is the model" contract survives untouched; the smart-topology combination is refused locally rather than on the wire.

2. multiview_image_urls requires the literal "meshy-7".

{"multiview_image_urls":[...]}                      → "multiview_image_urls requires ai_model meshy-7"
{"ai_model":"latest","multiview_image_urls":[...]}  → "multiview_image_urls requires ai_model meshy-7"
{"ai_model":"meshy-7","multiview_image_urls":[...]} → passes

The public docs say "requires ai_model: "meshy-7" (or latest)". It does not accept latest. Leaving the model to the server — what every other 3D command here does — is a guaranteed 400, so this is the one command that pins a version. It's pinned in the defaults layer, so --data '{"ai_model":"..."}' still wins if the gate ever loosens, and a test locks it because deleting the pin silently breaks the feature.

3. Model sets, straight from the enum errors:

image-to-3d       → [meshy-4 meshy-5 meshy-6 meshy-7 latest meshy-t1 meshy-t2]
multi-image-to-3d → [meshy-5 meshy-6 meshy-7 latest]
text-to-3d (v2)   → [meshy-4 meshy-5 meshy-6 latest]        ← no meshy-7

text-to-3d is therefore left alone, and that asymmetry is now written down in its header instead of being rediscovered.

Notes for review

• --ultra-mode help text carries no credit figure — tests/surface.test.ts forbids prices in the command surface, and pricing stays in the skill/docs.
• retexture.ts gains one test-only export (retextureSpec) so the meshy-7 pin is assertable. Happy to drop it if you'd rather not open that seam.
• Not touched: make (unchanged chain), pricing estimates, version bump.

Test plan

• pnpm run typecheck clean
• pnpm test — 360 pass / 0 fail (3 new)
• Manual, against production with a real key:
  • --ultra-mode true --model-type smart-topology → exit 2, local error
  • retexture with no style input → exit 2
  • --text-style-prompt + --multiview-image-urls → exit 2, mutually exclusive
  • 5 images → exit 2
  • wire check: ultra_mode: true present in the image-to-3d payload; multi-view retexture payload carries ai_model: "meshy-7" and clears the gate (fails later on my 2×2 test pixels, as it should); non-multi-view retexture carries no ai_model

🤖 Generated with Claude Code