Editing

Read the baseline

Revisioned document sessions

Read the session contract for fields and bounds, and use vextcad vxl session schema for closed executable schemas. The public lifecycle recipe provides all ten local CLI commands and the hosted REST routes.

Local CLI actions: open, replace, set-overrides, undo, redo, status, cancel, entities, preview, publish.

Hosted REST actions: open, replace, set_overrides, undo, redo, status, cancel, entities, preview, publish.

The CLI uses set-overrides, the wire uses set_overrides.

Rounds on imported bodies

Booleans preserve source boundaries and edges left by prior edits on import-derived bodies. For tolerant operands, keep the fully protected candidate when its STEP read-back passes the existing two-cap admission; only a refused candidate enables affected-face rebuilding. Losing inherited classification alone does not merge a partition that certifies within the frozen created cap. Count retained faces and edges in expect for fillet/chamfer and shell selectors, and re-query the current result. New section edges follow the source face partition: a planar cut across two split cylinders gives four semicircles, so a selector for their two circles needs expect: 4. Requirements selecting imported faces must cover every intended patch; one analytic wall can still be several faces. Mirror keeps its own same-domain merging policy.

For tolerant_v1 input, prefer explicit analytic tools when the round's section is known. Remove a round by cutting excess material or filling missing material with an annular extrusion or revolved ring that restores the intended sharp stock. Add a round with a tangent arc in a revolved tool's meridian: cut for a convex edge, union for a concave root. Clip a ring to the intended whole sectors before applying it; do not affect neighbouring features. To resize, restore that local stock first, then apply the tool for the requested radius. These tools make the intended section explicit and avoid asking the blend builder to infer it. They still require valid connected results and cold certification; they are not a bypass. New blend-face contexts without proven inherited edges/faces retain the frozen 1e-5 mm cap; a uniquely inherited face may use its import cap (N154). Its N220a mirror (owner decision 2026-11-06, rule a) also permits a created face's context to use the opposite context's direct inherited import cap when the edge has exactly two incident faces, N220r certifies identical endpoints, carrier, trims and incident-face correspondence within 1e-7 mm, and the created context's certified bound is at most that cap; borrowed caps never chain. Raising the import allowance does not raise the cap for wholly new faces. Inspect K751/structural detail and verify preserved regions and the final radius independently; a permissive reader's validity result does not replace that check.

Replace and overrides

Keep authoring complete VXL documents using the gated loop. Open with standard padded base64 of the checked authored document, schema_version:1, the complete overrides and optional immutable timeout/TTL. Retain session_ref and read status for canonical document, overrides, revision, build refs and report/packet descriptors. Preserve questions and assumptions in edits. Each edit uses current base_revision and a fresh printable idempotency key; an equal retry reuses its key and body. Replace sends a whole document and whole overrides map; set-overrides replaces the whole map and {} clears it. Never send operation batches or display numbers as selectors; repair authored geometric predicates and expected counts.

# both roots must already exist.
vextcad vxl session open open.json --session-root PRIVATE --generation-root PUBLIC --cell-manifest CELL --idempotency-key KEY
# status.json contains {}.
vextcad vxl session status SESSION status.json --session-root PRIVATE
# replacement includes schema_version, base_revision, document, overrides.
vextcad vxl session replace SESSION replace.json --session-root PRIVATE --idempotency-key EDIT_KEY

Undo and redo

HOLD and RELEASE accept source; FAILED/check refusal/cancellation preserve the previous source and overrides. Read the revision packet and follow the same repair/stop rules; count session rebuild attempts, including an undo that must rebuild, toward the existing four-build cap. Undo restores the preceding accepted source at a higher revision; local redo restores the next undone source at a further revision (empty_redo if none remains). Entities queries measure retained STEP with explicit evidence; preview reads fixed captured PNGs unless a schema-2 diagnostic is requested.

Variants

Use variants[] for named finite override sets and when only for structure selected by finite-domain parameters. See the language card. Set-overrides replaces the whole map; {} clears it.

Compact replies

Use --compact (wire compact:true) on replace, set-overrides, undo, redo or publish. The reply projects the retained report: outcome, label, changed steps, all nonpassing requirements, first diagnostic, nullable measures delta and full report reference. Equal semantic key/body retries may request full or compact without rebuilding. Compact does not truncate failures, perform measurements or upgrade HOLD to RELEASE.

Entities and pages

Use --filter with AND predicates (kind, carrier, normal_near, within_aabb_mm), --limit (1–1024) and the returned --cursor for continuation. within_aabb_mm tests face centroids, not whole-entity containment. Exact edge centroids are unavailable; there is no step-provenance filter. Display numbers are observations, never authored selectors. Keep revision, build, terminal, topology and filter fixed across pages; inspect complete and next_cursor. Delivered mesh triangle pages are diagnostic-only. Use vextcad commands --with-entries to find real CLI/REST adapters; entries do not grant backend admission. See the session contract.

Diagnostic preview

The fixed build renders (iso, front, top, right, 1024²) are studio presentation images (generation_studio_v2) with the terminal’s display_color (default RGB [160,170,190]); iso has model and ground shadows with a 512² map, PCF radius 6, ground darkness 0.3 and key direction [-0.12,0.17,-1.0]; axis views have no ground or key-light shadows. Iso uses medium AO (automatic radius/default strength); all views use studio_gradient_v1 environment intensity 1.0. Axis views have AO off. Use the GAR for geometry checks and vxl render for diagnostic views.

Diagnostic preview: session preview uses schema 2. Add --azimuth, --elevation, --section OX,OY,OZ:NX,NY,NZ[:negative], repeatable --ghost/--solid, or entity highlight flags (--highlight-terminal, --highlight-faces, --highlight-edges, --topology-digest) to render delivered meshes at --size up to 2048. --target and --span set the orthographic framing. vextcad vxl render GENERATION_DIR --terminal T --section 0,0,5:0,0,1 --output section.png renders a finished generation. These images are diagnostic-only, never verification evidence; sections have no exact caps. For a presentation image (perspective camera, metal, transparent background), run vextcad studio-render GENERATION_DIR --source generation --terminal T --request studio.json --output hero.png --report hero.json with a vextcad.studio.render.v1 request; it uses each terminal's display_color and is presentation-only too.

Recovery and publish

Publish only the current build/ref at its current revision when the user's request calls for delivery. Publishing HOLD is allowed, retains its label and keeps it out of the release index. Publish does not close the session or increment revision. No idle native worker is retained; source and authenticated outcomes survive restart. Status distinguishes idle, building, publishing, recovering and expired. After a hosted precommit interruption, last_request.state is interrupted and current is unchanged; retrying its key replays that outcome, while a fresh key may rebuild. A durable committed source or commit journal is reconciled without modeling again. Unknown publication requires install reconciliation. Keep HOLD files labelled in private previews and published deliveries. Hosted calls require vxl_session; cancellation also requires request_cancel, and private file reads require artifact_read. Do not claim RELEASE from missing measurements.

Deliver a native document

After a successful accepted build, run vextcad vxl export-native RUN/generations/NAME --output model.vextcad using the native OCCT package for exact intake. It cold-authenticates the generation, retains canonical VXL, overrides and original assets with generation provenance, imports exact terminals as exact STEP parts and mesh terminals as native meshes, then saves/reopens the existing native format. Cold export with part export --format step|stl|3mf for exact parts or mesh export for a single mesh. Multiple exact parts require the returned --part-id; multiple meshes use mesh export --mesh-id UUID. Native mesh-chain editing currently requires a single mesh root.

For session history, publish every accepted revision and pass all generation directories in oldest-to-newest order (up to 33) before --output history.vextcad. Each generation becomes one native revision; failed builds are omitted. A final generation alone cannot recover earlier session revisions. Native bodies remain editable imported snapshots; keep the VXL recipe for parametric feature edits. This does not recover a native VXL feature tree, assembly constraints, or retained multires detail layers. See the VXL reference.

Examples

• when_variants
• provisional_open_question