Meshvault Live Editing

MeshVault Live Editing (agent over MCP)

Prerequisites

Every recipe here presupposes a reachable meshvault-mcp server (stdio MCP; operator installs: pip install "meshvault[mcp]" + playwright install chromium — agents must never self-install, report the absence instead). Verify the server answers BEFORE following any recipe — spawn it and call list_viewer_commands. If it is absent or fails to spawn, STOP and say so; do not improvise against a different tool surface.

Field-tested recipe for editing 3D objects through MeshVault's control surface. Distilled from live sessions (tattoo painting, haircut resculpts on a 120k-face photogrammetry portrait, primitive-assembly character and vehicle builds). Scope: the interactive editing loop (a separate generate → export pipeline walkthrough ships with the MeshVault repo, not with this skill).

Golden rules

1. Never guess coordinates. Every brush lands at world coords you must earn: pick {x, y} from a screenshot, raycast {origin, direction}, or inspect_region. A miss names the object actually hit — read the error.
2. Never repeat a failing call verbatim. An error is a verdict, not a flake: the same action + params returns the same error forever. Change the action or the params (the message usually names the fix), or report the blocker. A local pilot burned 60 steps ping-ponging two invented actions; colors are CSS hex STRINGS ("#ff0000"), never [1,0,0] arrays.
3. Look after every meaningful mutation — with your eyes if you have them. screenshot after each phase, not each stamp. If you are a vision model, actually LOOKING at the render is the highest-value action in this entire skill: judge shape, proportions, and paint contrast concretely, name what is wrong, fix, re-shoot. Multi-view views:["front","top","iso"] judges proportions like an artist turning the easel. Text-only agents must lean on quantified results instead — and should say so honestly in their report. A blind run declared a white blob "the Millennium Falcon, complete" (field lesson); eleven takes of looking made a portrait.
   • Screenshot economics (measured): cost is SYNC-bound, not pixel-bound — 192² and 1024² take the same 0.6-5 s steady-state, but every NEW capture size pays a 2.4-28 s one-time warm. Pick ONE size per session (512² is the sweet spot: cheap tokens, enough to judge) and keep it. ssao:false does NOT make renders faster (measured; ignore older guidance) — its value is only the look. Between shots, verify with quantified reads (get_bounds, list_objects, painted/ meanAlpha — 20-60 ms) instead of pixels.
   • Batch your probes: batch {commands:[...]} carries raycast and all reads — one 30-probe batch costs half the wall time of 30 calls through MCP (and probes are now BVH-accelerated engine-side: ~1 ms each even on 240k-triangle meshes). Probe-batch → compute → act-batch.
4. Quantified results are the truth. Trust stretchedEdges, meanAlpha, painted, openEdges deltas over your intention. If meanAlpha ≈ 0 the paint is invisible; if painted is tiny the brush missed.
5. The sculpt loop is: probe → sculpt → regularize → paint. Heavy grabs stretch facets into untexturable slivers — run regularize_region on the worked area before judging the shape or painting it.
6. Announce destruction before you rely on it. refine_region, regularize_region, simplify_region, split_object REPLACE geometry: the reset baseline moves and morphs drop loudly. Read the returned note.

Session setup

• The MCP server is the entry point: spawn meshvault-mcp over stdio (any MCP client). The whole tool surface is: load_model, describe_scene, viewer_execute {action, params} (THE workhorse — every command below), list_viewer_commands, get_state, screenshot, get_texture, export_model, save_scene/load_scene, compare_models, open_in_app/get_app_state. Everything in this skill is reachable through these tools — verified by full MCP-client builds (X-Wing, Falcon).

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
server = StdioServerParameters(command="meshvault-mcp",
    env={**os.environ, "MESHVAULT_SESSION_LABEL": "LIVE: my build"})
async with stdio_client(server) as (r, w):
    async with ClientSession(r, w) as s:
        await s.initialize()
        await s.call_tool("viewer_execute", {"action": "add_primitive",
                          "params": {"kind": "sphere"}})

• Load with load_model / add_primitive, then ALWAYS describe_scene and get_bounds first — sizes drive every radius you will pick.
• Radii are world units. radius_rel (fraction of bounding sphere) is safer across differently sized models.
• App discovery (seat polling, REST endpoints): read ~/.meshvault/app_session.json → {url, token}; send the token as X-MeshVault-Token. The MCP server does this automatically for its own publishing — you only need it for the observer-count etiquette below.

Probe-based targeting (the core trick)

Features you cannot click, you find with ray grids. Pattern from the haircut (find hair hanging below a hem line):

hits = []
y = ymin + 0.06 * ysz
while y < y_hem:                        # scan a horizontal band
    for x in (-0.4, -0.2, 0.0, 0.2, 0.4):
        h = ray([x, y, -3], [0, 0, 1])  # from behind, toward the face
        if h and h[2] < neck_guard_z:   # GUARD: hair only, never skin
            hits.append(h)
    y += 0.09 * ysz

• Add up-rays from below for thin downward spikes; side rays for silhouettes.
• Always pair probes with a guard plane (e.g. neck_guard_z) so cleanup brushes cannot touch protected surfaces (skin, face).
• Convergence loop: re-probe after each batch, act on the worst few, stop when the detector returns empty or a pass cap hits.
• Coarse detectors converge; fine detectors stall. A 5-column scan fixed in 14 passes what an 11-column scan diluted across 26 (too many weak targets splits your strength). Scan coarse, sort by severity, act on ≤8.
• The plateau rule (live-session lesson). Track your progress metric every pass. If it has not improved in 3 passes, STOP repeating — switch tools or accept the result. A live run spent 4+ passes burying the same 17 strands with zero progress; each ineffective grab still stretched facets, and the final regularize inherited 2400+ stretched edges it could no longer clean within budget.
• Interleave regularize_region into long sculpt campaigns (every ~30-50 grabs), never save it for one pass at the end: stretch compounds, later brushes (flatten/smooth) re-stretch what was cleaned, and a late equalize can even measure WORSE than before it started.

Sculpting SHAPES from stock (the shark playbook)

Organic forms come from ONE primitive + brushwork, not assembly. Validated by sculpting a recognizable shark from a single capsule (fins, tail, mouth, gills all brushed) — five takes distilled into these rules:

1. Work like a sculptor: proportions → features → detail → paint. Judge each stage from silhouette renders (views:["left","front","top"]) before moving on. The first take read as a beluga because the head stayed a capsule ball — one slimming pass fixed what no amount of fin detail could.
2. Brush centers live ON the surface. pinch at the medial axis touches nothing (its gather radius never reaches the skin). To TAPER a body: symmetric surface grabs pulling toward the axis — flanks with symmetry:"x", top and bottom as separate pulls.
3. symmetry:"x" on sculpt/sculpt_stroke/paint/paint_stroke mirrors every stamp across the object's local plane: direction/pivot/axis are reflected, hinge angles negated, exactness guaranteed. Bilateral anatomy (fins, ears, eyes, gills) in half the calls with zero drift. Keep the DENSITY symmetric too: refine both sides (or one centered region) before a symmetric pull, or the mirrored stamp lands on coarser facets.
4. Extrusions (fins, ears, limbs) = repeated soft pulls at descending radius, re-probing the crest between pulls. Each pull MOVES the crest; sculpting the old coordinates sculpts air. Guard the re-probe (reject hits that jumped away). Refine the region first (target ≈ pull radius/8).
5. Pull SOFT, then sharpen. falloff:"sharp" pulls crumple thin membranes into accordion folds (dorsal-fin take 2). Pull with the default smooth falloff, then pinch (mirrored) to thin the blade, then a smooth stroke along the base to blend it into the body.
6. Regularize the WHOLE body after proportion work (default target, 2 iterations), features after their own passes. Fine grooves (mouth, gill slits) still follow the groove recipe: refine to radius/3 → dig gently → re-probe before inking.
7. Counter-shading paint: spine stroke down the top, flank rows probed with SIDE rays at descending heights (top-down probes fall off the curve), symmetry:"x", then blur_paint along the transition to melt banding into an airbrush gradient.
8. Parametric circle paths are PLANAR — they ride the surface only where the surface still matches the circle. Dig/paint rings BEFORE doming or displacing the area (owl eye discs: rings dug after doming floated and missed); afterwards, build ring strokes from re-probed points instead.
9. Analytic coordinates die at the first sculpt. Any formula-derived surface point (sphere/ellipsoid math) is a lie once proportions were sculpted — a whole 70-stamp paint batch missed on the owl because the crown had been flattened 0.05 lower. After EVERY sculpt phase, re-probe before painting or digging: batch the raycasts (32 per call) so a full re-probe of 70 points costs three round trips. Order the build proportions → features → relief → paint so each phase probes once.

Fusion: from assembly to ONE sculptable skin (merge_objects)

Primitives are the FIRST DRAFT, never the result. The advanced-sculpting loop: assemble the draft → FUSE it → sculpt the fused skin → texture.

• merge_objects {ids: [a, b, ...], mode?: "union", blend?: 0.05, name?} — true CSG union: overlapping volumes fuse where they intersect, interior shells disappear, and the result is ONE welded surface where brushes, digs and refines work ACROSS the old part boundaries (separate objects can never blend at their joints — each mesh welds only to itself).
• Overlap the parts deliberately (10-20% embedment): union fuses VOLUMES; surfaces that merely kiss produce degenerate seams.
• blend (world units) is the joint fillet: seam vertices on the intersection curves get deterministic Laplacian rounding with smooth falloff — an organic neck/shoulder/wing-root in one parameter (≈ the fillet radius you want). Follow with a smooth stroke along the joint for extra softness, or regularize_region over the seam area before fine sculpting.
• Union needs CLOSED sources (open rims refuse with counts — fix_mesh or mode:"concat", which concatenates + position-welds and never refuses, but keeps interior walls). Planes/shells → concat.
• Source paint/textures are DROPPED and UVs re-atlas per source (no paint cross-talk): texture AFTER fusion — which is the right order anyway.
• The fused object is a NEW id at identity placement; sources are gone; manifests can't rebuild it — export_glb persists. Budget: ≤400k combined source triangles.
• Order matters: get placements right FIRST (set_object_transform on the draft parts), because after fusion placement is baked.
• NEVER run fix_mesh {degenerate} on a fused mesh: CSG seams carry legitimate sliver triangles; dropping them OPENS the seam (field run: 2006 triangles dropped, open edges 51 → 570 — the "repair" punched holes in finished work). Multi-part unions also keep ~50-90 trace open edges — that is normal and harmless (sculpt/dig/paint all tolerate it).
• Refine budgets on freshly fused meshes run ~3× the formula (the union output is coarse and conformality cascades dominate) — take the nextPassNeeds number from the refusal instead of guessing upward.

Building FROM primitives (hard-surface and character assembly)

Composed models (a spaceship, a cartoon character) are ASSEMBLIES: one primitive per part, placed with transform at creation. Lessons from the Mickey and X-Wing builds:

• add_primitive {kind, params, name, transform: {position, rotation, scale}, frame: false} places the part in one command. frame: false keeps the camera yours. NAME every part; keep an id map (set_active_object {name} also works — exact match, then case-insensitive; ambiguity errors with the roster) — set_active_object before every per-part fill/paint/sculpt (paint always lands on the ACTIVE object).
• set_object_transform's scale is a NUMBER (uniform); per-axis arrays go in scale_xyz. An array passed to scale fails validation loudly — but the transform option of add_primitive routes through the viewer and takes either. Prefer placing at creation.
• Symmetric parts (4 wings, 4 engines, limb pairs): loop over sign products for sx in (-1,1): for sy in (-1,1) and derive positions/rotations from the signs. One code path = no left/right drift.
• Raycast-probe every paint center on placed primitives — never trust parametric math (sphere/cone formulas) after transforms: a scaled sphere is an ellipsoid, and a silently wrong assumed radius paints air ("Brush touched no surface"). Probe from outside toward the part, REQUIRE the hit object id to match the part you mean.
• Per-part texture tiers: 2048 for the hero part (head, fuselage), 1024 for mid parts, 256-512 for small trim. Fill each part's base coat at creation so later strokes need no layer setup.
• Detail passes that read at a distance: panel seams as paint_stroke path:{type:"line"}, low-opacity (0.12-0.2) shape:"square" plates for panel variation, weathering smudges at opacity ≈ 0.2 with hardness ≈ 0.3.
• Brush centers on curved shells: compute the surface point analytically or probe it — a stamp centered far off the surface ("Brush touched no surface") or a circle path floating above a dome paints NOTHING. For an ellipsoid saucer: y = cy + b·√(1−(x/a)²−(z/c)²); for everything else, raycast. Batches of 30 stamps with ~60% misses (Falcon take 1) all traced back to centers hovering off the hull.
• Circle/line paths clamp at 64 samples: a full 360° dig ring at fine spacing exceeds it and scallops into dotted craters; a LONG thin paint line (1.7 units at radius 0.006) renders as perforation dots for the same reason. Split rings into arc segments (start_deg/sweep_deg, e.g. 6 × 60°) and long lines into segments of length ≤ 60 × radius/2 each.
• Trench walls need edges ≈ brush radius / 3 BEFORE digging (refine the annulus/strip first, then dig gently — several shallow passes beat one clamp-depth stamp). Digging 0.022 facets with a 0.03 brush at clamp depth tears the shoulders into crumble that no amount of smoothing tidies.
• Realism at flat-shaded scale is carried by PAINT MOSAIC + grime, not micro-geometry: mismatched grey plates (5-8 tones, opacity 0.35-0.75), radial rust streaks, scorch blooms, one glow accent. Greebles help at rim scale; dig trenches read only if refined first (target ≈ radius/5).

Grooves + inked lines (order matters)

• Ink BEFORE dig when a painted line must follow a groove (a smile, a panel line): paint the stroke on clean texels first, then dig along the same path — the paint rides the surface down. Digging first stretches the wall texels and the ink lands dotted ("teeth").
• Refine BEFORE dig on coarse meshes: refine_region to ≈ groove radius/5, then dig with remesh OFF. Digging coarse facets with remesh:"auto" leaves crumbly shoulders and texel drift that a re-fill cannot hide (it is shading, not texture).
• Prefer parametric path {type:"line"|"circle"} over hand-sampled point lists for BOTH paint_stroke and sculpt_stroke: server-side auto-spacing. Sparse explicit points render as dots/scallops; a circle path needs its center + axis + the SURFACE radius at that cross-section.

Adaptive resolution (adjust density on the fly)

Mesh density is a budget you spend where the shape needs it. Three ops, one loop:

1. Survey: inspect_region {grid: 3} maps density (triangles, edgeLength median/p95) across the object, sorted by simplification opportunity; inspect_region {center, radius} probes one spot.
2. Densify before detail: refine_region {center, radius, target_edge} with target ≈ brush radius / 5. React to budgetHit by re-issuing with the returned nextPassNeeds.
   • Budget sanity BEFORE you refine: triangles needed ≈ 2.5 × π·r² / (0.43 × target_edge²). If that number is over ~20k, your radius or target is wrong for the feature — refine the BRUSH footprint (radius = stamp radius), not the neighborhood.
   • Grade the density: one fine ring is rarely needed everywhere. Nested rings — fine at the feature center, 2-3× coarser one radius out — sculpt identically at ~13% of the triangles (measured on identical fin pulls; the rim never carries brush-scale detail).
   • A refusal quoting a huge nextPassNeeds is a diagnosis, not a dare. If the error notes that marked edges dwarf the over-target ones, the MESH QUALITY (slivers) is forcing cascades: run regularize_region with an explicit target_edge over the area first, then refine. Never reflexively raise max_triangles.
   • You should never need 100k triangles in one refine. A fin, an eye socket, a groove — thousands, not hundreds of thousands. Counts beyond that mean the request shape is wrong (radius too big, target too fine, or sliver stock underneath).
3. Equalize after deformation: regularize_region is a FULL remesher — splits over-long edges, collapses needles (link-condition safe), flips edges toward valence 6, then relaxes. Read stretchedEdges {before, after} (after ≈ 0) and valence567Share (≥ 0.9 = regular graph). On mixed regions pass an explicit target_edge (a blended median lies).
4. Coarsen what no longer earns its facets: simplify_region {center, radius, ratio} (ratio = fraction kept); check achievedRatio — seam-dense regions decimate less and the result says why.

Sculpt results now carry an under-sampling advisory: if a stamp moved fewer than ~6 vertices, the result note says the mesh is coarser than the brush (a "success" that reads as a spike, not a shape) and names the refine parameters. React to notes, not just errors.

Material response (the realism lever paint alone cannot reach)

Albedo-only paint shades as matte clay. Surfaces read REAL through their light response — paint it per texel:

• paint/paint_stroke/fill_paint with channel:"roughness" or "metalness" + value: 0..1 (0 = polished/dielectric, 1 = rough/metal); channel:"emissive" + color (glows — engine exhausts, eyes, screens); channel:"height" + value (data layer for relief workflows).
• Recipes that carry: worn metal = fill metalness 1 + paint_pattern {type:"grunge", channel:"roughness", value:0.2, value2:0.9}; glazed ceramic/varnish = roughness 0.08 wash over the lit areas; oiled wood = roughness gradient 0.3→0.7 along the grain; scorch = albedo smudge PLUS roughness 0.9 (burnt = matte).
• roughness+metalness share ONE packed canvas (glTF native) — exports to GLB losslessly and reloads identically (round-trip verified). clear_paint restores the original material response.
• Verify gloss under set_lighting {exposure ~1.0} and a specular angle — flat presets can mute highlights and you'd paint roughness blind.

Procedural patterns (one command, not 160 stamps)

paint_pattern {type, seed, scale, ...} fills the object (or a region:{center, radius}) with a WORLD-SPACE pattern — continuous across UV seams, scale-consistent, bit-deterministic per {seed, scale}:

• noise (fBm color blend) — mottle, camouflage, organic tone variation.
• grunge (ridged fBm + contrast) — wear streaks; best on channel: "roughness".
• cells (Worley) — cracks, scales, dry earth.
• speckle {density} — dots, rivets-ish, stone grain.
• stripes {direction, density} / gradient {direction} — bands and ramps. ANTI-PATTERN (owl v3): stripes on ORGANIC surfaces — geometrically perfect world-space bands read mechanical on plumage/fur/skin. Organic banding wants hand paint_stroke paths with wobble (probe the surface, vary spacing); save stripes for hulls, decks, awnings.
• noise/grunge with direction STREAK along it (falcon field ask): the noise domain compresses along the axis so features elongate — rust runs under gravity [0,-1,0], airflow grime along the fuselage axis. stretch 1-20 (default 4) sets elongation; works on channels (streaky roughness = the wet-run look).
• Combine: albedo noise + roughness grunge + a sparse speckle = a hull that reads weathered in three calls. scale = world units per feature (default object/12); same seed replays identically.

Noise sculpting (micro-relief the brush domes cannot make)

sculpt {tool:"noise", wavelength, octaves, seed, ridged, bias} displaces along weld normals by seeded fBm — feathers, bark, rock, fabric:

• wavelength = feature size in world units (default radius/2); refine_region the patch to ≈ wavelength/4 FIRST or the noise aliases.
• octaves 2-4 for natural surfaces; ridged:true for crests/bark; bias>0 grows more than it cuts (plumage), <0 pits (corrosion).
• Sampled at object-LOCAL coordinates: the pattern sticks to the object and repeated stamps re-evaluate the same field. Same seed = same relief.
• Pair with a matching paint_pattern at the same scale so color follows relief (noise albedo over noise geometry reads as one material).

Region deformers (one call, not a grab salvo)

deform_region {kind, axis: {from, to}, ...} applies a closed-form deformation along a spine — from is ANCHORED, the effect eases (smoothstep) to full at to:

• taper {factor} — cross-sections scale to factor at the tip. A mandible/tail/limb taper is ONE call (the shark tail took 9 grabs and terraced). factor 0.35 = tip a third as wide.
• bend {angle_deg, direction} — progressive rotation about direction (must be perpendicular to the spine): curved necks, drooping wings.
• twist {angle_deg} — cross-sections rotate about the spine.
• stretch {factor} — elongate by a fraction (0.3 = 30% longer).
• Welded (seams never tear), deterministic, honest refusals (parallel bend axis, zero-touch). regularize_region after strong tapers/bends — compressed cross-sections need re-equalizing.

Swept strokes (panel lines that don't bead)

sculpt_sweep {points|path, radius, strength, profile} computes ONE distance-to-curve weight field — the cross-section is constant along the path, so grooves and ridges come out clean where stamp chains scallop:

• profile:"crease" = sharp V center — THE panel-line profile. strength NEGATIVE cuts (panel lines, seams, mouth lines); positive raises (welts, cables, raised trim). "round" = soft dome; "flat" = plateau trench.
• Majority-side guard: welds facing away from the stroke's mean normal are skipped — a top-skin panel line won't groove the wing's bottom skin even when both are within radius. Force direction:[x,y,z] to override.
• symmetry:"x" sweeps the mirrored curve as a SEPARATE polyline (verified bit-symmetric crests). remesh:"auto" and meshQuality work like sculpt.
• Resolution rule unchanged: refine along the curve to ≈ radius/4 first, or the profile can't form (the result warns below ~4 verts/segment).
• Line-campaign budget (x-wing v3 blowup: 225k → 1.48M triangles): the refine formula is per-REGION and a panel-line campaign multiplies it by every strip. Keep refine strips NARROW (strip radius ≈ 1.2× sweep radius, not 2-3×), refine ONE strip covering several parallel lines when they sit within a few radii, and CHECK the triangle count between lines (describe_scene). Recovery is brutal at scale: whole-model simplify on ~1.5M tris runs ~20 minutes with no progress output, and simplify_region refuses above its 50k-vertex cap — prevention is the only cheap path.
• Ring sweeps (falcon v3): a CIRCLE-path refine strip costs by its ANNULUS area ≈ 2πR·2w (w = strip radius), far less than the enclosing disc — but a TIGHT ring (R ≲ 3w) is effectively a disc: budget with πR² instead, or the refusal will surprise you mid-campaign.
• Crease DEPTH must match viewing distance: ~0.2-0.5% of hull size reads at close range only; features meant to read in a full-body shot need ~1-2% (the owl's facial disc carried at 1.5%; its 0.4% wing arcs vanished). bake_ao roughly doubles perceived depth for free.
• Sweep beats a dig-stroke for LINES: dig makes craters (flat floor, per- stamp), sweep makes constant profiles (per-curve). Use dig for pockets.

Cavity grounding (paint that sits IN the surface)

bake_ao {strength, highlight, contrast} darkens concavities and optionally lightens convex rims, baked into the albedo:

• The single cheapest "painted-on → carved-in" fix: run it ONCE after sculpting is final (later sculpts won't move the shading).
• strength 0.5-0.8 pools shadow/dirt in seams, folds, nostrils, panel lines; highlight 0.2-0.4 = worn edges (metal, stone). contrast lower on soft organic curvature, higher to pick faint detail.
• Honest method note: Laplacian curvature (local crevices), NOT ray-traced occlusion — it won't shade one part's shadow onto another. Refuses when curvature is uniform (perfect sphere) instead of pretending.
• Order matters: albedo/patterns → bake_ao → roughness/metalness channels (AO multiplies albedo only). undo_paint reverts a bad bake.

Height → normal baking (relief that costs no triangles)

Paint relief into the HEIGHT channel, then bake it to a normal map:

1. paint/paint_pattern {channel:"height", value/value2} — 0.5 = flat, above raises, below recesses. cells at height = hammered metal; noise = rough stone; stripes = corrugation; brush strokes = carved lines.
2. bake_normals {strength} (1 subtle, 3-5 pronounced) — Sobel-derives a tangent-space normal map, wired to the material and exported as a standard glTF normalMap. Re-run after further height painting.
3. Shading-only relief: survives simplify_region, costs zero triangles, reads at grazing light. Honest limit: height features crossing UV island borders can seam. For relief the SILHOUETTE must show, use real geometry (tool:"noise" sculpt) — bakes never change the outline.

Texture resolution (choose per quality need)

• The layer size is fixed at creation: fill_paint {color, texture_size} — tiers low=512, medium=1024, high=2048, xhigh=4096.
• Pick the tier from the feature size: inspect_texture gives texel density (texels per world unit); a brush of radius r paints ~(r × density) texels — if that is under ~8 texels the stamp is a blur, go up a tier or paint wider.
• 512 for blockouts and flat fills, 1024 for general work, 2048 for close-up detail, 4096 only when a hero close-up demands it (memory: a 4096 RGBA layer is 64 MB; the scene texel budget refuses beyond 32M texels).

Sculpting

• Tools: draw, inflate, smooth, flatten, pinch, grab, hinge, dig. sculpt_stroke takes a path (line/circle) with server-side spacing.
• dig removes material (crater/groove): fixed inward axis, flat plateau (flat_fraction, default 0.5) with a smooth shoulder; depth clamps per stamp to (1−flat_fraction)×radius (read appliedDepth, re-issue for deeper); a 13-ray probe REFUSES stamps that would pierce a thin shell and names the max safe strength — through-cuts are split_object territory. Prefer one stamp at the clamp over many repeats; tidy a rough rim with a smooth ring + regularize_region.
• Dig STROKES scallop and compound (Death Star trench lessons): a dig stroke is a chain of crater stamps — rims bead at stamp spacing (de-bead with smooth strokes along both shoulders), and overlapping stamps compound depth well past strength, so RE-PROBE the groove floor (raycast) before painting it — the surface you dug is not where it was. Grooves crossing an existing groove are safe (the piercing guard only counts true back-facing far walls).
• Fine intentional grooves trip needsRemesh on every stroke — that is the trigger seeing detail finer than the local median, not damage. It measures the region's STANDING state, so even smooth strokes passing over intentional detail re-flag it (28 benign advisories in one live build). Keep remesh OFF during a micro-detail pass, ignore advisories whose region you deliberately detailed, and run ONE regularize_region per worked band at the end; save remesh:"auto" for shape-changing pulls.
• Every sculpt result carries meshQuality ({outOfBandFraction, maxOverMedian, needsRemesh}) — the facet-degradation trigger. Pass remesh: "auto" to run the full remesher automatically when it fires (geometry is REPLACED: reset baseline moves; morphs suppress it loudly). Explicit regularize_region remains for manual control.
• grab displaces along direction — it moves surface, it cannot delete it. Pulling a curtain of geometry "away" only relocates it. To bury residue: pull toward the volume interior with an upward bias; downward or purely inward pulls re-bunch mass that pierces back out as spikes.
• Thin spikes: small radius (≈0.15 of the feature), falloff: "sharp", moderate strength — big soft brushes smear instead of removing.
• "Brush touched no vertices" → the mesh is too coarse there: refine_region {center, radius, detail_rel} first (target ≈ brush radius / 5).
• After heavy displacement: regularize_region {center, radius} — check stretchedEdges.before/after reaches ≈ 0. On mixed-density regions pass an explicit target_edge (the region median lies when dense and stretched areas share the brush).
• Honest limit: reshaping a photogrammetry shell (hair, cloth) with displacement brushes has a ceiling. dig carves into thick volumes but REFUSES on thin shells (piercing guard); "cut off" needs geometry removal (split_object + delete part) — plan choreography around what each tool class can actually do.

Verifying with pixels, not hope (portrait-repaint lessons)

When painting features onto a blanked model, measure — never guess:

1. Render the ORIGINAL first; pixel-analyze it for anchors (darkest clusters constrained to the inner face = pupils; reddest inner-face cluster = mouth; large-region medians = skin/hair tones). Gate detections with anthropometry (inter-pupil / face width ≈ 0.35–0.55) and RETRY with wider scans instead of proceeding on a failed gate.
2. Derive the palette from the model's own sampled tones, warmed toward a canonical skin anchor — dead-even color reads unnatural; warm shadows and subtle blush washes are what read as skin.
3. After each phase, render and VERIFY against the measurements (painted pupil positions, mouth centroid, cheek tone distance) and only continue on OK. A screen-fraction guess that drifts 0.05 puts eyes on temples.
4. Dark facial features pass any "dark = hair" test — fence eyes/mouth/chin geometrically before classifying hair pixels by chroma distance.

Painting and texture healing

• Paint needs a layer: fill_paint {color, texture_size} on unpainted models; tiers low/medium/high/xhigh = 512/1024/2048/4096.
• Blanking / repainting from scratch: fill_paint floods the whole atlas with one color — it IS the eraser. Fill with a neutral base (#b0b0b0 or a skin base tone) at the tier you intend to paint at, then rebuild the texture with paint/paint_stroke layers coarse-to-fine. clear_paint is the opposite move: it restores the ORIGINAL texture.
• paint/paint_stroke with color, opacity, hardness; results carry painted + meanAlpha — verify both.
• Healing: clone_paint (donor → target, world-space), blur_paint (masked blur), mirror_paint after detect_symmetry. Donors: pick clean skin/material from the symmetric or adjacent region.
• undo_paint reverts the last brush; group multi-call gestures with undo_group tokens.
• Decorative fields (panel plates, window dots): use batch — hard cap 32 commands per call, PROBES INCLUDED (a 60-raycast batch refuses; split probe batteries into ≤32 chunks). Deterministic pseudo-random layouts (seeded LCG — replays stay identical). Expect 1-2 misses per batch near clamped edges ("Brush touched no surface" in sub-results) — scan sub-results rather than treating the batch as failed. Judge paint contrast under neutral lighting: set_lighting {exposure, ambient} has NO preset param — lighting presets live on screenshot {preset: "neutral"} — and the studio look washes out light grays.
• After regularize_region, texture in the region drifts slightly (vertices slide within the surface) — blur_paint or repaint to tidy.

Performing for humans (observation seat)

• Checkpoints are AUTOMATIC: the publisher snapshots scene state after any

  2 s command and at session end, so humans join/scrub your session in seconds even when your build contains monster remeshes. You owe them nothing extra — but a simplify on a 1.5M-tri mesh still takes ITS OWN 20 minutes live; prevention (refine budgets) beats any replay machinery.

• Publish a session (the MCP runtime does this automatically when the app is running); the app's eye icon lists joinable sessions.

• Wait for your audience. Poll /api/observe/sessions for observers > 0 before the first stroke — a performance nobody saw did not happen:

while time.time() < deadline:
    if observers() > 0: break
    time.sleep(2)
else:
    end_session(); return          # never perform to an empty room

• Pace for watchers: orbit the camera between phases, sleep 0.3–0.5s between stamps (pump), keep a narrative arc (reveal → work → inspect → finale). Observers see your persistent brush ring (radius = area of influence) and the panel tool readout automatically.
• End with verification screenshots at canonical angles, plus a close-up of the riskiest region (e.g. the nape after a haircut).

Verification battery (end of any editing session)

1. screenshot front/side/back + close-up of the worked region.
2. get_mesh_stats — openEdges unchanged unless you split something. Fused-mesh exception: multi-part unions legitimately keep ~50-90 trace open edges (see Fusion section) — compare against the post-fusion baseline, not zero.
3. fix_mesh {operations: ["degenerate"]} — expect trianglesDropped: 0 after a clean sculpt/regularize loop. SKIP THIS STEP on fused meshes: CSG seams carry legitimate sliver triangles and dropping them punches the seams open (the NEVER rule in the Fusion section — 2006 dropped triangles opened 51 → 570 edges in the field); expect nonzero drops there and do not "repair" them.
4. export_model round-trips paint and geometry; check the file size is sane.

Traps

• Radii in screen pixels or normalized units — they are world units.
• Sculpting while a morph influence is active is refused; set_morph to 0 or delete_morph first.
• Painting right after refine on pole-cap fans can leave hairlines — known, disclosed in the refine_region description; paint slightly wider.
• simplify_region after refine is safe (guards added), but expect the reset baseline to move; take a fresh screenshot as your new reference.
• A stroke over a UV seam heals per-island; use mirror_paint or project_paint for cross-seam fixes.