Write a VXL document

Connected Vextor MCP: When mcp__vextor__* tools are available, work only through them. Read docs with read_docs/search_docs (they match the server's engine), validate with check_vxl, build with start_build + get_build, render with get_preview, and upload STEP/STL inputs with upload_asset. Do not read local skill files or run local vextor/ scripts/vextonline.py in that session. Otherwise, follow this skill as written.

Authoring rules

Write and maintain VXL documents directly. No script writes *.vxl.json; scripts may prepare captured inputs, build committed documents, read delivered files or inspect slicing.
Use native profiles[] for mechanical geometry that follows dimensions and parameters. Use SVG regions for fixed artwork and organic outlines.
Put families in one document with variants[]; use when only when finite-domain parameters change structure.
Use each and templated names for repeated arrays and statements, and functions[] for shared formulas. Do not paste expanded copies.
Keep scans, photographs, sculpt captures, fonts and requirement-named STEP/STL files as assets. Declare descriptors from captured bytes with vextor vxl asset describe or refresh them with vextor vxl assets sync.
Self-review with vextor vxl fmt, vextor vxl check --preview DIR, vextor vxl check, and vextor vxl reference. A static check is not a measured build.

Start

VXL is a closed JSON design-document language for exact (B-Rep) and triangle-mesh parts. Read CONVENTIONS.md, then choose one card and one checked example. Write one <name>.vxl.json directly. vxl check is not geometric acceptance. Requirements are independent of the model. An unresolved problem means HOLD.

Choose a card

MODELING.md: representation, frames, modeling cards, language and selectors.
EDITING.md: revisioned sessions, undo/redo, compact replies, pages and recovery.
CHECKING.md: independent requirements, evidence grades, repair and delivery.
STD.md: sealed library signatures; remote-build.md: hosted builds.

Gated loop

Do these in order. The common failure is writing geometry before noticing a missing fact.

Facts → needs[]. One fact per need: split the request into its separate claims and restate each in the user's words rather than copying a compound sentence wholesale. Add source: "user".
Gap scan. For each feature ask: position? size? orientation? count? side? Treat a missing value or ambiguous instruction as a question when resolving it chooses among geometrically different parts, unless the user already authorized that choice. A declared assumption alone does not resolve it; ask for the undetermined attributes or name the competing readings explicitly. An assumption without a question is allowed for a value derived from supplied facts, an unambiguous documented default, or a sourced standard dimension for an already determined component and function; identify the basis and adopted value. A complete request needs no question. Scan every requested feature, including ones omitted from a draft; ask explicitly about each undetermined size, position, orientation, count, side or interface attribute, not just whether a proposal is acceptable. For a useful provisional model, keep unresolved questions in both the document and the answer, mark provisional choices in assumptions[], and call it provisional until resolved; open questions cap the build label at HOLD while every file is delivered, and answering means removing the question and recording the user's answer as a need, parameter or assumption (assumptions alone do not cap the label). See the worked example.
Frame recipe. Apply the coordinate-frame recipe before writing any geometry.
Values. params[] for user-supplied facts (with domain when a reopen is expected); lets[] for derived values; checks[] for design inequalities.
Geometry. In each part, write creators first, then Booleans, holes, patterns/mirror, then fillet/chamfer last. When a shape repeats, or a screw axis needs its hole and keep-out, reach for a use: std.mount_hole for a verified hole, std.tool_access for the keep-out, a defs[] fragment for anything else. State a use's target when the fragment drills or unions into it.
Requirements. Every measurable need gets a requirement with covers. For an unmeasurable exact-part claim, use kind: "unmeasured" with describe; it needs exactly one of subject or operands (VXL-S011 if both are given; VXL-R660 if neither is given), and a mesh subject is refused (VXL-R761). For a mesh disclosure, put the reason in that need's unmodeled field. A need may instead use a reserved gap kind where appropriate. Every need must be covered or marked unmodeled.
Check loop. Run vxl check and read the CLI check result. Fix one code at a time and re-run. Hard cap 6 checks.
Build and revise. For retained source, open the checked document, then replace it or set the full overrides map, inspect status/entities/preview, undo when needed, cancel a named request when abandoning work, and publish labelled files for delivery (see the session workflow). One-shot vextor vxl build FILE --output-dir DIR (or the hosted upload) builds the part and writes DIR/report/summary.json; on failure or HOLD it also writes DIR/report/revision-packet.json. Read the packet, fix the document, rebuild. A chamfer_size row with outcome: fail shows setbacks_mm and support_signed_offsets_mm: compare each with nominal; a station that differs means the chamfer is on other stock or between other faces than between says. Hard cap 4 builds.

On a Mac, the result is development-only. vextor vxl build on macOS arm64 runs in the unqualified development_macos_arm64 cell with the resident OCCT package and no --cell-manifest. Every summary, build report, manifest and banner carries that cell and the build is capped HOLD/development_unqualified: it can never read RELEASE, and an exact clearance requirement is reported not-measured (development_cell_unqualified). Use it to iterate and to get STL/3MF (plus STEP for exact terminals), but do not quote it as a qualified or RELEASE result; only the sealed Linux x86_64 cell qualifies.

No local vextor, or need a Linux-cell result from a Mac? Use the hosted service. With the user's API key, python3 scripts/vextonline.py check|build ... replaces vxl check and vxl build and returns the same out/ layout. See Remote build.

Deliver

Read the output contract and delivery decision. Deliver labelled files and the report; use native export when requested.

Stop

Keep the six-check/four-build limits above, including session rebuilds. Read HOLD and repair; unresolved intent, required nonpass or unavailable evidence stays HOLD. Compact replies, filters and previews never decide RELEASE.