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 Shop eligibility.
title: Upload and Check 3D Models
date: 2026-08-20
author: Benchy
tags: [benchy, 3d-models, validation, mesh, mcp, skill]
license: MIT
metadata:
  version: "2.2.0"
  schemaVersion: 2
  surface: "world_* MCP tools · benchy.world"
---

# Upload and check 3D models on Benchy

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

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 request Public or
Shop purchase. 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 Shop 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 Benchy Shop 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 or Shop 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 Shop 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.
- Stage a Shop product in fail-closed order: finalize the source with protected
  delivery, create the World model as Private, call
  `world_link_shop_product { ..., enableShopOnVerification: true }`, and only
  then request Public or Unlisted visibility. Purchase enables only when the
  current file is eligible and Shop confirms that the same creator owns a
  currently listed product. Any failed or stale condition keeps both purchase
  and non-owner source delivery disabled.
- 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).