@instruktlabs/kiln 0.0.0-stage → 1.0.0

package/skills/kiln-author-asset/references/geometry-recipes.md

@@ -0,0 +1,329 @@
+# Choose geometry by the shape you need
+
+Search `kiln_discover` for the shape or operation you need, then fetch exact `ids` for unfamiliar helpers. An overview supplies current `family` and `tags` labels when a filter is useful; `{ kind: "recipe" }` browses optional construction recipes. Each example below lives in `build()` with a named root and suitable material. Adapt or combine recipes freely, including with custom equations and topology.
+
+Parts use the asset frame: metres, +X forward, +Y up, +Z right. Forward is the direction the object faces; a bench's sitter faces +X. Part `rotation` is in degrees and follows the right-hand rule in this frame: `[0, 90, 0]` turns forward (+X) toward -Z, the object's left; `[0, 0, 90]` tips +X up to +Y; `[90, 0, 0]` rolls +Y toward +Z.
+
+For a gripper or carrier, define the payload's occupied volume as well as its
+attachment marker. Check the complete gripper housing, palm and jaws against that
+volume; separated fingers do not prove the central body clears it. Size the open
+jaw gap for approach and release, then verify the closed contact surfaces. Mating
+pins and grooves must agree in count, spacing, orientation, depth and clearance in
+one shared frame. A locator proves a pose, not a physical fit. Keep these mating
+dimensions in the asset brief and shared source parameters.
+
+For moving attachments, inspect intermediate poses along approach, pickup, travel
+and release. Matching endpoints can still produce a path through the payload or
+support. Keep joints, contact markers and payload motion in the intended hierarchy;
+repair the geometry or path where the swept volumes collide.
+
+For ears, handles or other details attached to a rotated or lofted body, derive
+their bases from the carrier's local surface and transform them through the same
+frame. A nearby world-space point can leave a visible gap after the body rotates.
+Use a small intentional base overlap for a solid join, then inspect the exported
+attachment from both sides and an oblique view. Preserve unrelated joints and
+animation tracks when repairing an attachment; matching names alone does not prove
+their transforms or motion survived the export.
+
+## Surfaces from equations
+
+An asymmetric canopy or corrugated sheet can be much shorter as a function than as many primitives:
+
+```js
+const canopy = parametricSurface(
+  (u, v) => [u, 0.35 * Math.sin(u * 2) + 0.12 * v * v, v],
+  { u: [-2, 2], v: [-1, 1], uSegments: 48, vSegments: 24 },
+);
+createPart('Canopy', canopy, metal, { parent: root });
+```
+
+Domains and segment counts are explicit. `orientation: 'uv'` follows increasing-U cross increasing-V; `'vu'` reverses winding. `periodicU`/`periodicV` require matching endpoints and retain wrapped UV seams. A sampled surface has no automatic thickness or caps.
+
+Collapsing an entire parameter row or column to one tip leaves degenerate grid triangles and can produce zero normals. Use a non-collapsed parameterization, or construct the intended tip with explicit `meshGeo` fan topology. `geometryDiagnostics` can expose degenerate triangles; changing normals alone cannot repair the topology.
+
+For authored topology, `meshGeo({ positions, indices, normals?, uvs?, tangents? })` uses flat numeric arrays. Triangle winding is counterclockwise. An open sheet is valid geometry; do not label it a watertight solid.
+
+Mirrored vertices alone do not establish a symmetric curved surface. The same
+diagonal through warped quads on both sides can produce different surfaces between
+vertices. Mirror the topology with corrected winding, or use symmetric patch
+tessellation, then compare corresponding surface points between stations. Changing
+normals cannot repair a positional asymmetry.
+
+For a hollow shell, distinguish the intended opening from unintended end seams.
+Separate inner/outer surfaces and a rim do not automatically join the bow, bottom
+or other end boundaries. Inspect those joins from both sides after resizing; a
+correct bounding box and accepted structural QA do not prove closure. Leave
+surfaces open where the brief calls for them rather than capping every boundary.
+
+For a solid wall, gable or roof, review the outside and intended inside separately.
+Matching edge coordinates do not establish a visible join: reversed triangle winding
+can cull the connecting surface even when vertex normals point outward. Repair the
+winding or missing geometry rather than hiding the defect with double-sided shading;
+deliberate thin sheets may need it. Check ceiling and trim extents against the actual sloping roof, including
+the eaves, rather than its bounding box.
+
+For a pane or panel fitted into a sloping frame, derive its corners and surface
+normal in the frame's coordinates. A bar's long axis and a sheet's plane may use
+different local axes, so copying a slope angle does not align them. Check all
+four transformed corners against the intended frame plane and opening, then
+inspect an oblique view where an out-of-plane pane is visible. Matching centers
+or bounding boxes alone cannot establish this fit.
+
+For attached veins, ribs or seams, discover `recipe:surface-detail-v1`. Its strip
+shares the carrier mesh's sampled boundary vertices and rises along local normals.
+A shared equation followed by a separately interpolated curve does not establish
+contact with the actual mesh. Check both attachment and final dimensions after a
+shape edit; a normal offset can change height as well as depth. This recipe is an
+optional open-surface construction, not a requirement to turn every detail into a strip.
+
+For a decal or lamp following a faceted body, ray-projecting the detail's vertices
+outside the body does not prove its connecting triangles stay outside. Coarse detail
+triangles can cut through the host between those vertices. Where the detail must lie
+flush, clip the actual host triangles to the intended footprint and retain their
+facet boundaries before applying a small controlled offset. Check the exported
+surface head-on and obliquely at every promised detail level; preserve the
+footprint and overall dimensions rather than covering the defect with a larger patch.
+Check the entire intended footprint, including points where no detail triangles were
+emitted: sampling only existing triangles cannot detect clipped-away holes. Use the
+first hit on the outward-facing host to distinguish missing coverage from backfaces.
+Contrasting body/detail colours can expose gaps; keep that diagnostic tint separate
+from the saved material design.
+
+## Interfaces that must fit or move
+
+Derive mating surfaces from shared dimensions and local frames. Surface contact at
+one point does not establish a flush joint along an edge. For a continuous-looking
+body, align profiles and transitions at the intended seam; unrelated interpenetrating
+primitives may hide a gap in one view while exposing a ledge in another. Separate
+rigid pieces, welded surfaces and deforming joints are all valid when they match the
+requested style and motion.
+
+For usable doors or passages, establish the actor envelope, finished floor,
+threshold, clear width and headroom. Split plinths, caps, trim and braces around the
+opening when they would obstruct it. Check the closed position, the hinge sweep and
+the open passage against exported geometry. A wide visible door leaf is not evidence
+of a traversable opening.
+
+For a seated operator, fit the posed body as well as the seat marker: pelvis/seat,
+knees/controls, feet/deck and hands/reach. Check relevant steering or pedal travel
+and access for mounting. Keep application-specific poses separate from promised
+asset clips, and report which one was tested.
+
+For articulated limbs, place roots and joint transitions within the intended body
+silhouette and inspect the moving seam from several sides. Identify the anatomical
+joint each pivot represents before reversing its bend direction. Correct exposed
+attachment caps, gaps and snapping through the motion, without assuming every
+stylized creature needs one rigging or deformation technique.
+
+Before mirroring a hand, inspect its local frame, palm, thumb web and any tool grip.
+Weak anatomical cues can look reversed without a left/right frame error. Refine the
+shape while preserving a correct wrist pivot and attachment frame, then check hand
+clearance through the relevant motion and against the complete carried tool.
+
+For a shield or other broad carried plate, define the intended support pose as
+well as its mounting frame: which way the plate faces, where the grip lies, and
+how the forearm runs along the inner surface. Solve the elbow within a plausible
+reachable pose, keeping it clear of both plate and torso. A clearance fix can
+still pull the elbow into the body or turn the plate away from its intended
+direction. Inspect rear and side views through carry, guard and recovery, using
+the actual arm and plate surfaces rather than only their centres or boxes.
+Keep the requested pose and dimensions in the asset brief; preserve unrelated
+geometry, materials and clip channels when refining its support or grip.
+
+When reducing draw calls, consolidate compatible geometry within the same rigid
+motion parent. Give independently moving groups real, named `Joint_*` pivots and
+put their rigid geometry beneath them. Preserve attachment markers and consumer
+lookups. In builds with rigid-group `full` optimization, the rigid-merge pass retains
+node names, but a named mesh outside a protected boundary can become empty or contain
+other parts' geometry. If each named part must keep its geometry, use `off` or
+`palette` optimization and disable the separate GPU-instancing pass, which can remove
+named instance nodes (`instance: 'off'` in library calls or `KILN_BAKE_INSTANCE=off`
+in the host). Recheck what each
+lookup controls, clip targets and intermediate poses after export; fewer meshes
+alone does not establish a successful optimization.
+
+Budget materials within each rigid group. Reuse the parent's material for tiny
+fixed details when it gives the intended appearance; a separate material adds a
+potential draw even when the detail is small. One material does not guarantee
+one draw: vertex layouts, protected parts, transparency and vertex-limit splits
+also constrain merging. Available `drawDiagnostics` can help locate these costs;
+read its scope and skip reasons, then measure in the destination.
+
+Avoid unintentionally overlapping coplanar faces on separate parts. Merging can
+change which face wins a depth tie even when geometry and colours are preserved.
+Use a shared surface, remove hidden duplicate faces or give a deliberate overlay
+the separation it needs. Inspect the actual exported surface from relevant views;
+do not offset every touching joint or treat a sampled coplanar flag as a defect.
+
+## Materials and directional UVs
+
+For a leaf-card alpha path, discover `recipe:foliage-cutout-v1`. It binds a real
+alpha-bearing approved texture to `foliageMaterial`; MASK alone does not create a
+leaf silhouette. Its bundled 4×4 texture is a teaching placeholder. Check current
+material capabilities before choosing a delivery resource, then inspect GPU views
+and destination filtering/backfaces. Raw `THREE.DataTexture` is not an available
+authoring route. Solid leaves and custom surfaces remain valid alternatives.
+
+For lengthwise grain or stripes through bends, discover `recipe:directional-sweep-v1`.
+It demonstrates sweep side U around the profile and V along path distance. Preserve
+that convention when editing the path; arbitrary atlas rotations suit baked detail
+but can disrupt directional tiling. Caps and physical texture scale need separate
+decisions. Read the GPU image: CPU geometry feedback cannot establish texture direction.
+
+## Shape an existing mesh
+
+```js
+const twisted = twist(column, { angle: 90 });
+const narrowed = taper(column, { endScale: [0.4, 0.7] });
+const curved = bend(rib, { angle: 60 });
+const rippled = displace(sheet, ([x, y, z]) => [0, 0.04 * Math.sin(x * 16), 0]);
+```
+
+All return owned geometry. They work along local +Y; bend turns +Y toward +X. Set `frame: { origin, rotation }` for another local frame; rotations are degrees. `interval: [minY,maxY]` selects local Y distances, with outside vertices unchanged. An optional `falloff(t)` returns 0..1. Displacement returns an offset, not a replacement position.
+
+Add enough segments before shaping. UVs remain, normals/bounds are recomputed, and stale tangents are removed. `creaseNormals(geometry, { angle: 45 })` then gives controlled hard/smooth boundaries. `subdivide(geometry, 1, { preserveUV: true })` preserves UV charts; legacy subdivision can discard them. Topology-changing subdivision drops old CSG face provenance rather than guessing.
+
+For ordinary geometry scale or rotation, retain the normals those operations already transform. An extra raw `computeVertexNormals()` can replace smooth analytic normals and leave unused sphere-pole vertices with zero normals that fail GLTF validation. Direct position-buffer edits or deliberate shading changes need an appropriate normal update; that is a different case from an affine transform.
+
+## Vary the cross-section
+
+```js
+const profile = [[-.12,-.2],[.12,-.2],[.12,.2],[-.12,.2]];
+const rail = sweepProfile(profile, [[0,0,0],[0,1,0],[.5,2,0]], {
+  twist: 20, scale: [[1,1],[.9,.9],[.7,.7]],
+});
+const housing = loftProfiles([
+  { profile },
+  { profile: [[-.2,-.1],[.3,-.1],[.2,.15],[-.2,.15]],
+    frame: { origin: [0,1,0], rotation: [0,15,0] } },
+]);
+```
+
+Profiles use local `[x,z]`; loft sections lie in local XZ planes. A sweep follows supplied polyline stations using transported frames. Sample a curve first if you need smooth curvature. `up` sets initial profile +Z and must not parallel the path.
+
+Caps default on; `cap: 'start'` or `'end'` caps one end of an open path. `creaseAngle` (default 60 degrees) keeps a rectangular or triangular profile hard-edged; raise it to 180 to smooth everything. `extrudeProfile` adds side-wall rings only when `divisions` asks for them. Closed sweeps omit the repeated path endpoint and require total twist to be a multiple of 360. Loft sections require matching point counts and deliberate index correspondence. These versions accept a simple outline without holes; use `extrudeProfile` for straight sections with holes. Review tight turns and nearby surfaces for self-intersections.
+
+## Preserve useful Boolean surfaces
+
+```js
+const housing = await boolDiff('Housing', body, portCutter, { preserveAttributes: true });
+```
+
+Preservation mode carries UV0 and material groups; exposed cuts inherit the cutter's UVs/material. Missing input UVs produce a warning. Normals are regenerated; tangents are not retained. Without the option, legacy calls keep the first material and discard UVs. Use `autoUnwrap` afterward for a new atlas. Convex hulls create new faces and cannot promise source UV/material provenance.
+
+`smooth: true` averages normals across sharp boundaries too. If a Boolean rim
+looks scalloped in lighting, compare `housing.geometry = creaseNormals(housing.geometry,
+{ angle: 60 })` before adding sections or changing the cutter. This changes normals,
+not the surface positions. Inspect the silhouette and relevant geometry separately:
+normal changes cannot repair a real gap, jagged outline or self-intersection. Choose
+the angle for the intended hard/smooth boundary rather than applying it everywhere.
+
+Keep the returned mesh transform. Its position carries the first contributing
+mesh's world origin; its vertices are local to that origin. Extracting geometry
+alone or overwriting the returned position loses that placement. Read world bounds
+with `new THREE.Box3().setFromObject(housing)` and preserve world placement when
+attaching beneath a transformed parent.
+
+`roundedBoxGeo` rounds a box's twelve edges. Profile beveling rounds profile corners; extrusion cap edges remain sharp. Subdivision is smoothing, not a dimension-preserving general bevel.
+
+## Reuse structure without a new language
+
+Node and material `userData` carries application metadata as glTF extras. Use plain
+JSON and stay within 4 KiB per object and 64 KiB per asset; keys beginning `kiln` are
+reserved. Build warnings name omitted values. `visible = false` preserves hidden
+subtrees in export through `KHR_node_visibility`; their triangles are listed apart
+from headline metrics. Verify visibility support in the target application.
+
+Use `markOpenShell(part, 'why the boundary is intentionally open')` for a sheet or
+open tube. This records an acknowledgment when solid overlap cannot be measured;
+it does not suppress a measured collision or certify topology.
+
+Track helpers accept `STEP`, `LINEAR`, `CUBICSPLINE`, `EASE_IN`, `EASE_OUT` and
+`EASE_IN_OUT` interpolation. The eased choices apply between each pair of keys and
+export standard cubic sampler tangents. For example,
+`rotationTrack('Joint_Lid', [{ time: 0, rotation: [0,0,0] }, { time: 1, rotation: [0,0,90] }], 'EASE_IN_OUT')`
+starts and ends a swing at rest. Discover the track helper for its exact key format
+before authoring other channels.
+
+Source export indexes unindexed geometry using exact full-vertex equality. The
+`indexBuffers` receipt measures accessor bytes before and after this pass. Host
+`KILN_INDEX_POLICY=asBuilt` preserves helper buffers with optimization off; this
+choice belongs to export settings, not asset source.
+
+Put repeated assemblies in ordinary functions with JSDoc parameters and named return values. Pass parent/material explicitly; return the assembly root and attachment markers. Change one parameter at the call site for a variant. Give such a function a name prefix or suffix and use it for every part it creates (`Leg_L`, `Leg_R`); calling it twice with the same names makes duplicate node names, which QA reports as `UNIVERSAL_DUPLICATE_NODE_NAME`. The runnable [reusable-frame recipe](reusable-frame.kiln.js) demonstrates this without imports or hidden dependencies.
+
+Include the assembly and element index in repeated child names as well, so each
+leaflet, slat or fastener remains addressable during revision comparison. When a
+resize must retain those children, keep their count explicit and redistribute
+their attachment positions; deriving the count from the new length can silently
+delete parts. Check the exported child inventory as well as the changed outline.
+
+When components must move or be replaced together, parent them under a real root
+at the assembly's placement datum. Name suffixes alone leave independent siblings.
+`recipe:editable-assembly-v1` demonstrates hierarchy replication and replacing one
+bracket beneath its retained connection root. Use `replicateAssembly(...).nodeMap`
+to find copied nodes; do not guess their generated names. Shared resources need
+copying before independent buffer/material edits. Flat hierarchies are still useful
+for independent components.
+
+## Levels of detail only when the brief asks
+
+Build one tier unless the brief asks for level-of-detail tiers. When it does, build
+every tier from one routine parameterised by level and emit the tiers as sibling
+groups under one parent, named with one stem and a level token: `LOD0`, `LOD1`,
+`LOD2`, or `Body_LOD0`, `Body_LOD1`. LOD0 is the full-detail tier. Parts every level
+shares, such as wheels, stay outside the set. Then declare the set once, LOD0 first:
+
+```js
+// Screen fraction of a bounding sphere of radius r at distance d (50 degree vertical FOV, 16:9).
+const coverage = (r, d) => (Math.PI * (r / (2 * d * Math.tan((25 * Math.PI) / 180))) ** 2) / (16 / 9);
+const tiers = [0, 1, 2].map((lod) => {
+  const group = new THREE.Group();
+  group.name = `Body_LOD${lod}`;
+  root.add(group);
+  buildBody(group, lod); // your routine, less detail as lod rises
+  return group;
+});
+// LOD1 from 60 m, LOD2 from 250 m, culled beyond 1.5 km, for a body of radius 2.5 m.
+defineLod(tiers, { screenCoverage: [coverage(2.5, 60), coverage(2.5, 250), coverage(2.5, 1500)] });
+```
+
+`screenCoverage[i]` is the smallest fraction of the screen, 0 to 1, at which level
+`i` still draws; the values strictly decrease, the set is culled below the last
+one, and a last value of 0 never culls. Compute each set's values from the bounding
+radius of that set's LOD0 and the brief's switch distances, with the brief's field
+of view or the one above when it names none. To make a shared part vanish with the
+last body tier, give it its own set with an empty group as its last level, named for
+example `Wheel_FL_LOD0` and `Wheel_FL_LOD1`, and declare
+`defineLod([wheel, farWheel], { screenCoverage: [coverage(0.35, 250), 0] })`.
+
+Two or more sibling tiers without `defineLod`, a gap in the levels, a missing LOD0
+or a set declared inside another tier fail the build with `LOD_SET`, which names
+the fix. A lone token is only a label. QA treats tiers as alternates instead of
+overlapping or disconnected parts. Every GLB Kiln writes carries each set as one
+`MSFT_lod` chain: LOD0 stays in the scene, the lower levels leave it, and LOD0's
+`extras.MSFT_screencoverage` holds your thresholds. A loader without the extension
+draws LOD0, so reported triangles and bounds are LOD0's and the parts outside every
+set; `levelsOfDetail` in the render result lists each level's triangles and path. A
+default sheet draws LOD0. To review a lower level, make that level's `path` a shot's
+subject, with `visibility: "isolate"` to see it alone; the shot draws the level in
+LOD0's place, and each chain's `drawn` says which level every view drew. An imported
+GLB's chains are kept through save and export.
+
+## Implicit fields are experimental
+
+```js
+const blob = await implicitSurface(([x,y,z]) => 1 - Math.hypot(x,y,z), {
+  bounds: { min: [-1.2,-1.2,-1.2], max: [1.2,1.2,1.2] }, edgeLength: 0.15,
+});
+```
+
+Positive values are inside. Bounds/resolution are required; smaller cells cost more and thin features can disappear. Explicit grid/evaluation limits apply. Output has no UVs. Use this for a deliberate organic/cellular experiment, not an unsupported promise of general shelling, remeshing, or CAD accuracy.
+
+
+For textures, preserve valid primitive UVs. Use `copyGeometry` before independent
+buffer edits, `remapUV` to scale/offset UVs, and `projectUV` for explicit planar,
+box or cylindrical mapping in a geometry-local frame. Fetch its exact Discovery
+contract for rotated frames, partial angular ranges, caps and seam sampling.
+`autoUnwrap` is the separate atlas operation. Removed shape unwrap names do not
+select a preservation or projection fallback.

package/skills/kiln-author-asset/references/program-contract.md

@@ -0,0 +1,44 @@
+# Kiln source contract
+
+A `.kiln.js` file is ordinary JavaScript evaluated with Kiln globals. Do not add imports, exports, or TypeScript syntax. JSDoc and local helper functions are supported.
+
+```js
+const meta = { name: 'Reading lamp' };
+function build() {
+  const root = createRoot('ReadingLamp');
+  const metal = gameMaterial(0x556677);
+  createPart('Base', cylinderGeo(0.25, 0.25, 0.06, 32), metal,
+    { position: [0, 0.03, 0], parent: root });
+  return root;
+}
+```
+
+`meta.name` identifies the asset. No `meta.category` is needed to discover or use helpers. If retained in existing source, it is descriptive metadata and does **not** select validation or QA policy: the host-owned requirements are authoritative so generated source cannot weaken its own checks. Discovery families and tags describe catalog entries, not the category of the asset being built. `meta.role` describes its scene role when composition needs one: `ground`, `building`, `wonder`, `poi`, `prop`, `fill`, or `vehicle`.
+
+`build()` returns a `THREE.Object3D` and may be async. Use `async`/`await` for Boolean operations, `roundedBoxGeo`, `extrudeProfile`, `revolveProfile`, `implicitSurface`, approved texture loading, and other catalog signatures marked async. `sweepProfile`, `loftProfiles`, and ordinary deformations are synchronous.
+
+Optional `animate(root)` returns an array of `THREE.AnimationClip`. Follow catalog keyframe signatures: rotation tracks use a `rotation` field, position tracks use `position`. Grounded and moving parts need meaningful named pivots.
+
+To review that motion, `kiln_screenshot_animation` needs the clip **by name** -- `clip` is required, and a name that matches nothing comes back as an error listing the clips that do exist. `frameTimes` is optional and is expressed as **phases in 0..1**, not seconds: 1 to 9 strictly increasing values, scaled by the clip's own duration. Omit it and six frames are sampled evenly from start to end. A track whose target name binds to no node surfaces in `unresolvedTracks`, which is what a clip that renders frozen actually means -- a joint-name mismatch, not a broken clip.
+
+## Frames and ownership
+
+- Asset coordinates: metres; +X forward, +Y up, +Z right.
+- Kiln helper rotations and deformation frame rotations: Euler XYZ degrees.
+- Direct Three.js `object.rotation`: radians.
+- `createPart` prefixes mesh names with `Mesh_`. `createPart(..., { parent })` attaches the part; do not separately add its return value to another parent.
+- `createPivot(name, position?, parent?)` is positional and prefixes the node name with `Joint_`. Rotate the returned object directly if needed.
+- The prefixes are a naming convention, not a requirement. When a delivery contract needs an exact node name, assign `.name` after creation; exported node names, selectors and QA all use the final name.
+- `gameMaterial` and `lambertMaterial` default `flatShading` to true, but glTF has no flat-shading flag: the GLB, the local viewer and GPU views shade from the geometry's normals, and CPU views are flat-lit per face whatever the flag. For hard edges in the delivered asset, split vertices at the edge (for example `sweepProfile` `creaseAngle`, or separate faces).
+- Cached primitives may share geometry. Use `copyGeometry` or `.clone()` before direct vertex/geometry mutation. `copyMaterial` copies material properties while sharing referenced textures.
+- The former `cloneGeometry` and `cloneMaterial` aliases are removed. When migrating saved source, use the original value directly to preserve sharing, or `copyGeometry`/`copyMaterial` when an independent copy is intended.
+
+## Geometry and execution boundaries
+
+Custom `THREE.BufferGeometry` is available. `meshGeo` helps validate flat positions, indices, normals, UV0, and tangents. Read export warnings for unsupported attributes; arbitrary Three.js features do not automatically survive GLB export. The host may select `geometryPolicy: 'strict'` to reject unsupported attributes instead of dropping them with warnings. In a local runtime, `KILN_GEOMETRY_POLICY=strict` configures this host policy; generated source and tool arguments cannot weaken it.
+
+Use deterministic equations or explicit seeded recipes when repeatable builds matter. Avoid ambient state in reusable geometry functions.
+
+The source policy rejects host-global access, network access, dynamic imports/evaluation, constructor chains, and raw `THREE.DataTexture`, `ShaderMaterial`, or `RawShaderMaterial`. Use approved texture/material helpers. Generated code runs in strict mode: `this` is allowed inside object-literal and class methods (an object whose `add` method reads `this.parts`), not at the top level or in a plain function; an assignment to an undeclared name, `with` or a legacy octal literal is an error. Source checks are not an operating-system sandbox; evaluator process boundaries belong to the host.
+
+`kiln_validate` checks source without building geometry. `kiln_render` evaluates and returns images and structural findings. A valid program can still make an unsuitable shape or fail a later export check.

package/skills/kiln-author-asset/references/projects-and-materials.md

@@ -0,0 +1,158 @@
+# Optional projects and exact material dependencies
+
+A workspace provides Kiln's tools and local storage. A project adds a versioned brief,
+inventory, design profile, references, delivery intent and material lock for related
+assets. A collection stores saved asset revisions. The default collection is named
+`project`; saving there does not require or create a project record.
+
+The dashboard's Library aggregates configured storage collections. Register another
+asset store explicitly with `node kiln.mjs collections add <alias> <absolute-directory>`
+(on Windows a drive or share path such as `C:/Users/you/assets`; a Git Bash `/c/...`
+path is refused) and restart the host; `assets --all` / `kiln_assets` action `catalog` list them together.
+Keep collection IDs in exact asset references because IDs can collide across stores.
+Use named project inventory links for membership, independently of where bytes live.
+The viewer can link, replace or remove a membership; CLI/MCP use the same expected-
+revision project update with the intended inventory. Removing membership never deletes
+an asset. One asset can belong to multiple projects; standalone remains valid.
+
+For live iteration, optionally set `KILN_WORK_ITEM` to a stable lowercase identifier
+for one asset/candidate before starting CLI/MCP. Keep it across that item's revisions,
+use distinct IDs for independent candidates, and restart MCP to change it. Historical
+unbound operations remain ungrouped. `view --observe-workspace <directory>` can inspect
+another explicitly registered observation source without merging its project identity.
+
+Use a project when shared art direction or an inventory helps the requested work.
+An individual asset, experiment or environment can stay standalone. Do not infer
+project membership from its presence in the same directory. Different projects can
+use different styles, materials and budgets.
+
+## Standalone authoring
+
+Normal authoring needs no project setup. Omitted selection stays standalone unless
+the host explicitly configured `KILN_PROJECT`. CLI `--no-project` or MCP
+`projectId: null` overrides that default. Do not combine an explicit opt-out with
+a project revision. Materials and Live Review work in either mode.
+
+```sh
+node kiln.mjs render asset.kiln.js --no-project --out asset.glb --views review.png
+node kiln.mjs view
+```
+
+The CLI writes the review image to disk; read it before judging appearance. The
+browser loads retained GLB artifacts and does not build another copy. When GPU
+material evidence is required, add `--render gpu` and check actual view fidelity.
+
+For library materials, use CLI `material create-preset --file options.json`, then
+`material get MATERIAL_ID REVISION` for the code-ready `portableSpec`. Custom recipes
+use `material procedural --file draft.json`. These CLI paths do not need an internal
+`dist/` import or an extra TypeScript loader. Copy the returned spec into source,
+compile it with `compilePortableMaterialSpecV2`, and supply the exact pins below.
+
+## Create and revise a project when useful
+
+Discover optional `kiln_project`, `kiln_material` and `kiln_review` tools from the
+connected host. A custom embedding may omit them. These are equivalent entry points:
+
+```sh
+node kiln.mjs project create --id my-pack --name "My pack"
+node kiln.mjs project get my-pack
+node kiln.mjs project update my-pack --expected RETURNED_REVISION --file patch.json
+```
+
+```json
+{"action":"create","draft":{"projectId":"my-pack","name":"My pack"}}
+```
+
+Pass that JSON to `kiln_project`. To update, use
+`{action:"update", projectId:"my-pack", expectedRevision: RETURNED_REVISION, patch}`.
+Copy the returned revision exactly. A stale revision reports a conflict: read the
+current configuration and reconcile changes before retrying. Every supplied top-level
+field replaces its previous value. Read and merge the full `design` object before
+changing one nested preference; sending only `design.style` also clears omitted
+palette, material roles and conventions to defaults. Preserve array entries the
+task does not remove.
+
+Fill only the fields useful to the user's request. An example `patch.json` is:
+
+```json
+{
+  "brief": "A coherent set of workshop props for a browser game",
+  "design": {
+    "style": "Readable stylized shapes with restrained surface detail",
+    "scale": "Metres; +Y up; objects rest at Y=0",
+    "palette": [{"role":"paint","color":"#526D75"}]
+  },
+  "inventory": [
+    {"id":"workbench","name":"Workbench","kind":"asset","brief":"A usable work surface"}
+  ]
+}
+```
+
+Project creation and dashboard selection do not activate a project for future
+authoring. Select it on each operation:
+
+```sh
+node kiln.mjs render asset.kiln.js --project my-pack --project-revision RETURNED_REVISION --out asset.glb
+```
+
+MCP authoring uses `projectId` and optional `projectRevision`. Omit only the revision
+when the intended configuration is the project's current revision. A project is
+editable design guidance, not trusted requirements or release authorization.
+
+## Use library materials with or without a project
+
+Inspect `kiln_material` with `action: "presets"`, `"list"` or `"get"`. CLI equivalents
+are `material presets`, `material list`, and `material get ID REVISION`. Creation
+and import preserve creator, license, recipe/seed and source provenance. Copy the
+returned `portableSpec` into source and call `compilePortableMaterialSpecV2(spec)`;
+the host provides the selected immutable map bytes before evaluating source.
+
+A pin uses the returned material ID as `resourceId`; both hashes equal its returned
+immutable revision. `pins.json` is an array:
+
+```json
+[
+  {"resourceId":"RETURNED_MATERIAL_ID","revisionId":"RETURNED_SHA256_REVISION","sha256":"RETURNED_SHA256_REVISION"}
+]
+```
+
+For standalone work, pass this array as MCP `materialDependencies`, or use
+`node kiln.mjs render asset.kiln.js --no-project --materials pins.json --out asset.glb`.
+Use the same pins on later edit, inspect, animation and save calls that evaluate
+the source. The source reference alone does not restore dependency context.
+
+For a project, put the pins in its `materialDependencies` through a revision-aware
+update. A project-bound invocation (`projectId`, plus `projectRevision` for an exact
+configuration) implies that revision's pins, so the call need not repeat them.
+Call-level pins add resources, and a call-level pin for a resource the project
+already pins replaces the project's for that call. Update the lock deliberately when
+changing shared art direction. A missing resource or mismatched hash must be resolved
+before building; neither source URLs nor material names authorize an implicit download.
+
+Material records carry physical repeat scale, but the author controls mesh UV scale.
+Review seams, repeats, roughness and normal strength on representative geometry with
+actual GPU views. A project palette is guidance, not automatic recoloring.
+
+## Retain and deliver the work
+
+`kiln_review` can list/get observed operations, pin them against ordinary eviction,
+and save an exact reviewed operation using its `expectedRevision`. Pinning does not
+pause the agent; feedback still belongs in the agent's conversation. Saved collection
+revisions are durable; observation history is bounded and disposable.
+
+Preserve the returned collection, asset and revision IDs. When an asset belongs to
+an inventory entry, bind that exact saved revision with a project update. A later
+asset revision does not silently update the project inventory.
+
+Deliver a standalone asset directly through its collection exports. When delivering
+a pack, `project export ID --revision REVISION --profile editable|runtime --out FILE`
+packages the linked saved inventory. Editable delivery needs source, build settings
+and complete normalized material resources; runtime delivery needs the GLB and its
+metadata. Project packages exclude referenced concept-image and original acquisition
+archive bytes. Verify the actual exported files and rebuild resource-dependent editable
+deliveries in an independent workspace. Do not create a dummy project for delivery.
+
+After import, `node kiln.mjs asset ASSET_ID ASSET_REVISION --rebuild --out rebuilt.glb`
+uses the saved dependency revisions and exporter settings. It reports artifact hash
+equality; historical assets without complete settings need an explicit new build.
+Building or saving does not establish visual, game-runtime or release acceptance.

package/skills/kiln-author-asset/references/reusable-frame.kiln.js

@@ -0,0 +1,32 @@
+// Ordinary JavaScript: copy this function into your asset source.
+/** @param {{width:number,height:number,depth:number,post:number}} spec */
+function makeFrame(name, spec, material, parent) {
+  const { width, height, depth, post } = spec;
+  if (![width, height, depth, post].every(v => Number.isFinite(v) && v > 0)
+      || post * 2 >= Math.min(width, height)) throw new Error('Invalid frame dimensions');
+  const root = createPivot(name, [0, 0, 0], parent);
+  createPart('LeftPost', boxGeo(depth, height, post), material,
+    { position: [0, height / 2, -(width - post) / 2], parent: root });
+  createPart('RightPost', boxGeo(depth, height, post), material,
+    { position: [0, height / 2, (width - post) / 2], parent: root });
+  createPart('Header', boxGeo(depth, post, width - 2 * post), material,
+    { position: [0, height - post / 2, 0], parent: root });
+  const top = createPivot('TopAttachment', [0, height, 0], root);
+  const base = createPivot('BaseAttachment', [0, 0, 0], root);
+  return { root, anchors: { top, base } };
+}
+
+const meta = { name: 'Three portal frames' };
+function build() {
+  const root = createRoot('PortalFrames');
+  const steel = gameMaterial(0x3b7278);
+  const near = makeFrame('Near', { width: 2.4, height: 2.6, depth: 0.18, post: 0.14 }, steel, root);
+  const middle = makeFrame('Middle', { width: 2.4, height: 3.1, depth: 0.18, post: 0.14 }, steel, root);
+  const far = makeFrame('Far', { width: 2.4, height: 2.8, depth: 0.18, post: 0.14 }, steel, root);
+  near.root.position.x = -1.5;
+  far.root.position.x = 1.5;
+  // An attachment follows this frame's dimensions without duplicated coordinates.
+  createPart('Marker', sphereGeo(0.09, 12, 8), gameMaterial(0xe6b65c),
+    { position: [0, 0.09, 0], parent: middle.anchors.top });
+  return root;
+}

package/skills/kiln-batch-dispatch/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: kiln-batch-dispatch
+description: Run requested Kiln asset batches or compare coding-agent harnesses and models in isolated workspaces. Use for repeatable trials, source-reference workflow checks, and distinguishing provider, tool, and asset-quality failures.
+license: MIT
+metadata:
+  kiln-workflow: workspace
+---
+
+# Run comparable asset trials
+
+Use the user's requested harness and exact model identifier. Verify what the provider actually ran; do not silently substitute a default or older model.
+
+1. Create a fresh workspace for each candidate using [clean-room evaluation](references/clean-room-evaluation.md). A named Kiln project is optional; use matching project configuration only when the trial calls for it. Keep the engine checkout and example collection outside the agent's task context.
+2. Give each candidate the same brief, installed skills, image budget, time limit, and starting asset where applicable. Record inherited tools, instructions, memory, and permissions.
+3. Verify tool access and actual image delivery with one small run before dispatching a batch. Model vision support and harness image forwarding are separate checks.
+4. Exercise the whole revision loop: render source once, use the returned `programRef`, read a source window, edit an exact anchor, inspect a part, and export the same revision. Check that later calls do not resend the program and that unrelated source survives the edit.
+5. Retain the brief, exact model, harness version, requested and independently confirmed thinking effort, transcript, source, images, package/skill hashes, and outcome. Leave unexposed effort unknown. Keep the original author and each later refiner distinct. Rebuild the saved source independently of the agent's success claim.
+6. Review shapes under consistent cameras and lighting. Separate provider outages or quota limits, harness failures, tool/schema failures, engine failures, and visual quality. An interrupted run is not a completed asset.
+
+After a shared package or skill change, rerun the affected workflow with the final candidate. A successful earlier revision does not validate later instructions. Record manual repairs separately from model output.
+
+Adding a reviewed asset to a gallery is a separate task. Do it only when that addition is requested, retaining model provenance and later edits.

package/skills/kiln-batch-dispatch/references/clean-room-evaluation.md

@@ -0,0 +1,35 @@
+# Clean-room evaluation
+
+Workspace creation, harness choice and verifying that the tools came up are covered by the `kiln-setup-workspace` skill; this file covers only what an evaluation adds on top. Create the workspace with `--skills batch` so this workflow is present in the candidate, and use a separate fresh workspace per candidate.
+
+Keep evaluation notes and output in the workspace. Do not give the model the engine implementation or prior examples unless that is the comparison being tested.
+
+## What isolation means
+
+A clean workspace limits task context. It is not an operating-system sandbox or a requirement to create a Kiln project. Record inherited global instructions, tools, memory, authentication, and filesystem permissions without copying secrets into receipts. Do not alter user-wide configuration to make a run appear isolated. Use a separate Hermes profile when required by its launcher; give headless harnesses absolute workspace and artifact paths.
+
+Use a new workspace when testing changed skills. `--repair` repairs generated integration files while preserving existing copied skills; it is not a way to refresh a candidate silently.
+
+Hash the package and every installed skill resource recursively, not only `SKILL.md`. Keep the exact model identifier and harness version beside the run. When a provider reports a resolved model identity, retain it as well.
+
+## A small but complete trial
+
+Use a brief with three recognizable parts and one requested revision. Save the first `programRef`; render, source-view, source-edit, and inspect by reference. Export the revised source and GLB. Compare unrelated source text before and after, and verify the changed part in a targeted image. A source handle proves revision reuse; it does not by itself prove a render-cache hit.
+
+Check the actual transcript for tool images received by the model. Metadata that labels a model as vision-capable is insufficient evidence. Keep camera framing and image count comparable between candidates.
+
+Repository scripts such as `scripts/dispatch-asset.mjs`, `scripts/check-vision.mjs`, and harness smoke commands are optional developer tools in the engine checkout, not files promised in an installed authoring project. Provider-backed runs can incur usage. Use them only within the requested run and budget.
+
+Report completed, interrupted, and failed trials separately. Keep provider availability, image forwarding, tool correctness, source reuse, exported geometry, and visual quality as distinct findings. Do not turn a quota interruption into an engine failure or count an unreviewed partial image as a completed result.
+
+Read the final native terminal event and process result when classifying a run.
+A recovered stream error can precede successful completion; retain the error
+without overriding the later result. A live or unknown process is not terminal
+because a poll timed out. Inspect saved artifacts independently of either claim.
+
+For Antigravity, use the generated `node agy.mjs` launcher. Print mode disables
+automatic slash-command and skill expansion. In the brief, require the project skill
+copies and `kiln_workspace` server; use absolute task-file paths. Before asset work,
+call that server's `kiln_discover` with `{ capabilities: true }` and retain the
+runtime/store receipt. Global plugins may still be available: audit which server
+and skill paths were actually used, rather than trusting the final message.