Skill: Upload and Check 3D Models

mkdir -p .claude/skills/upload-and-validate-3d-models
curl -o .claude/skills/upload-and-validate-3d-models/SKILL.md https://benchy.world/skills/upload-and-validate-3d-models.md

---
name: upload-and-validate-3d-models
description: >-
  Upload 3D models to benchy.world and understand the file-check pipeline:
  ingest grants, single or multipart transfer, initial preflight, server-enforced
  marketplace policy, explicit check coverage, print-readiness assessment, and
  recovery. Use when uploading model files, publishing versions, debugging checks,
  or explaining publishing and paid-sale eligibility.
title: Upload and Check 3D Models
date: 2026-09-12
author: Benchy
tags: [benchy, 3d-models, validation, mesh, mcp, skill]
license: MIT
metadata:
  version: "2.2.1"
  schemaVersion: 2
  surface: "world_* MCP tools · benchy.world"
---

# Upload and check 3D models on Benchy

**Last verified:** 2026-08-20

Marketplace ownership and retired links corrected 2026-09-12; discover current
MCP schemas before using the workflows below.

Uploading, checking, and publishing are separate states. A completed upload
means the bytes were stored. It does not mean the file passed a publishing or
commerce policy.

## Pipeline at a glance

```text
world_request_model_upload
  → upload session + scoped grant
  → transfer bytes exactly as the response instructs
  → world_finalize_model_upload
  → finalized model key + byte evidence
  → world_create_model
  → hosted file checks
  → model state updated with the current policy result
```

## 1. Uploading

Supported upload declarations are `glb`, `gltf`, `stl`, `obj`, `usdz`, and
`3mf`, up to 250 MB per model file. The upload session has three steps:

Public publishing checks currently support GLB, glTF, STL, OBJ, and 3MF.
USDZ is private/unlisted-only for this release and cannot be published or
sold. STL and OBJ require an explicit coordinate-unit assumption:
`um | mm | cm | m | in | ft`.

1. **Request** — `world_request_model_upload { format, units?, expectedBytes,
   originalFilename }` returns an upload session and exact transfer
   instructions. `units` is required for STL and OBJ and must be one of
   `um | mm | cm | m | in | ft`.
2. **Transfer** — follow the response exactly, including its URL, grant, and
   single or multipart method. Do not derive a URL or storage key.
3. **Finalize** — `world_finalize_model_upload` verifies the completed session
   and returns the `modelKey`, exact size, and file evidence. Create the model
   only with those returned values.

The client never chooses a storage key. A stored upload remains available to
its owner even when later checks deny or cannot establish eligibility. A Public
create requires `primaryLens`, `license`, and
`provenance: "human" | "ai_assisted" | "ai_generated"`; STL and OBJ must reuse
the coordinate unit selected before transfer.

## 2. Initial preflight and server policy

The two runs have different contracts:

- **Initial preflight** uses `validationProfile: structural` and
  `executionMode: client_advisory`. It provides quick content-based format and
  framing feedback. It cannot grant paid-sale eligibility and cannot
  overwrite a completed server decision.
- **Marketplace policy** is the hosted, server-enforced result over the stored
  bytes. This is the only v2 context that can grant paid-sale eligibility.

Engine provenance does not confer authority. For v2, public or commerce
eligibility requires the complete current contract:

```text
schemaVersion == 2
policyVersion == current server policy
validationStatus == completed
validationProfile == marketplace_publish
executionMode == server_enforced
decision.verdict == allow
decision.reasonCodes is empty
required decision + print-readiness checks passed at their specified coverage
no error issues
high-confidence supported-format identification after bounded parsing
full finite geometry + topology evidence; known units
sha256 + byteLength + detected format + unit context match the current model
```

During migration, stored v1 results remain readable through the explicit
adapter, but no v1 result or engine-name prefix grants current eligibility.
Historical files are queued for a current v2 decision.

### Current validation availability by size

| Stored file size | Current server-enforced validation |
|---|---|
| ≤ 4 MiB | The hosted marketplace check can produce an eligibility decision |
| > 4 MiB, up to the 250 MB upload limit | The upload remains stored and owner-accessible, but the current policy returns `FILE_TOO_LARGE`; it cannot grant public publishing or paid sales eligibility until an attested large-file lane exists |

This is the server-enforced behavior verified on 2026-08-03. Upload capacity
is not the same as validation capacity.

A creator-declared unit may be used as a policy assumption for formats that do
not declare units; the report then marks `unitBasis: assumed` and emits
`UNITS_ASSUMED`.

## 3. Reading schema v2

The current report uses `schemaVersion: 2` and the policy version reported by
the service:

- `identification`: `detectedFormat`, confidence, inferred media type, and
  evidence. Detection is not structural validation.
- `decision`: `verdict` (`allow | deny | inconclusive`) and stable
  `reasonCodes`.
- `checks[]`: stable check id, `status`
  (`passed | failed | not_run | unsupported`), `coverage`
  (`full | sampled | header_only | metadata_only | none`), and evidence or
  issue codes.
- `issues[]`: stable code, severity, check id, message key, display message,
  and optional typed parameters. Automations branch on codes and parameters,
  never on English messages.
- `printReadiness`: `assessment`
  (`ready | needs_attention | not_ready | not_assessed`), prerequisite checks,
  notes, and limitations. Product copy renders `needs_attention` as **Ready
  with notes** so it cannot be confused with the blocking overall **Needs
  attention** state. There is no numeric score or quality band.
- `metadata`: observations such as counts, bounds, unit basis, coverage, and
  topology. Closed-surface and edge-manifold conclusions appear only when
  explicit topology evidence supports them.
- `engines`: implementation provenance.

A temporary compatibility projection remains for old consumers. New logic must
use the v2 decision, check, issue, identification, and readiness fields.

## 4. Product-state mapping

| Contract state | User-facing language |
|---|---|
| Upload stored; checks not started | **Uploaded** |
| Pending or running | **Checking file** |
| Server marketplace `allow` | **File checks passed** |
| Server marketplace `deny` | **Needs attention** |
| Retryable server execution failure | **Checks incomplete** — no publishing decision; select **Retry checks** or replace the file |
| Other server marketplace `inconclusive` | **Checks incomplete** — no publishing decision; replace the file or contact [Benchy support](mailto:help@benchy.studio) |
| Unsupported format issue | **Unsupported file type** |

Do not say “safe,” “verified,” “printable,” “watertight,” or “manifold” unless
the exact named property was checked with sufficient coverage. Do not infer a
policy decision from the engine name.

## 5. Publishing and paid-sale gates

- Public is an intent while checks run: the row stays unlisted until a current
  bound v2 allow arrives. Choosing Unlisted or Private cancels that intent.
- Prepare a paid offer from the World model's existing release and protected
  files. Read the current offer, package inspection, file-check, and seller
  payout state before reporting purchase availability. Discover the hosted
  server's current marketplace tools and schemas; use
  [Selling on World](https://benchy.world/docs/selling) for the product workflow.
- Pending, client, structural, standalone, inconclusive, v1, stale-byte, and
  stale-unit results do not qualify.
- Fix a denied file and publish a new version. Retrying identical bytes under
  the same policy is idempotent; a changed decision requires changed bytes or a
  changed policy version.

## 6. Troubleshooting

- PUT returns 401/403 — the grant expired or does not match the key. Request a
  new upload session; do not reuse grants.
- PUT returns 413 — the payload exceeds the grant or must use multipart.
- Model creation cannot find the object — finalize the upload before create.
- UI remains on **Checking file** — re-read later. If the owner view offers
  **Retry checks**, use it; otherwise contact Benchy support rather than
  diagnosing internal services.
- **Needs attention** — inspect stable issue and reason codes, repair the file,
  and publish a new version.
- **Checks incomplete** — no publishing decision was made. If the owner UI
  offers **Retry checks**, select it; otherwise use a supported
  self-contained format, replace the file, or contact
  [Benchy support](mailto:help@benchy.studio).