Skip to content

armgit / kiln

Public Imported from GitHub
0

Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.

246 KB
Raw Blame

Changelog

Changes to @instruktlabs/kiln (previously the private @kiln/engine package). Source releases and installable package publication are separate milestones. Published versions and tags are recorded by the npm registry; changing this file does not publish a package.

Unreleased

  • Calls on an artifact the host already loaded skip the load, and long host steps no longer hold up other calls on the same MCP process. Measured on the 2,635,224-triangle cathedral against a warm GPU service (two runs each):

    • kiln_render, kiln_inspect, kiln_screenshot_animation and kiln_view_interior borrow the review scene from a host cache keyed by the artifact hash. Each call has the scene to itself. A concurrent call on the same artifact loads its own copy rather than wait. A scene goes back only if its state key matches the one taken at load; a scene a call left changed, posed or added to is dropped, as is one left with a lower level of detail drawn or a level set aside changed. A lease has its own copies of the scene's lists (reason codes, clips). The host keeps up to two idle scenes, 6,000,000 triangles and 256 MiB of scene arrays and encoded textures, measured off each scene (the cathedral holds 136 MB). A scene no call asked for in 32 leases is dropped, and clear() drops all. A fully cached 9-shot call goes from 2.7–2.8 s to 1.4–2.0 s, a default-grid repeat from 1.5–1.6 s to 0.7–0.8 s, and a repeated isolated or kiln_inspect shot from 1.6–1.9 s to 0.7–1.0 s.
    • Every shot of a call frames against bounds walked once per scene state.
    • Scene loading, shot planning and drawing, the capture cache's cell checks and the CPU rasterizer pause for the event loop. They pause per batch of vertices or triangles, per shot or per cell, and the call's cancellation takes effect at the next pause. Pauses are counted in work, never timed, and change no output. The longest wait a concurrent call saw during a cached 9-shot call goes from 1.4–1.5 s to 0.35 s. On the CPU route the longest wait during rendering goes from 5.5–6.1 s to 3.0–3.1 s. A derivative export (about 2 s on this asset, most of it atlas provenance validation) is still one stretch.
    • Images, hashes, receipts and tool schemas are unchanged.
  • --draws minimal names each batch node after its first copy, <copy>_Instances, and drawReduction.instancing records which node names went into each batch, in instance order. A batched copy loses its mesh, and a mesh-less copy with no children or extensions is removed. Clips kept only as the review copy (scenes[].extras.kilnReviewClipsV1) now protect the nodes their tracks name, as native animations do. Such a file is not batched (batchingSkipped: 'review clips'), and a node a track names is never merged, which also holds for optimize: 'full'. The KILN_BAKE_INSTANCE pass skips these files too, so an instanced build of one now has its copies as separate nodes. Tests now show the draw reduction keeping animated, LOD, hidden, semantic and relationship-target parts.

  • A review shot no longer exports the same derivative GLB, or decodes the same frame, more than once. Measured on the 2,635,224-triangle cathedral against a warm GPU service (two runs each):

    • Shots that draw the same scene state share one derivative export, within a call and across calls on the same artifact. A repeated isolated shot goes from 3.8–4.2 s to 1.6–1.9 s, the same part from a new camera from 6.0–6.2 s to 2.3–2.8 s, and a repeated kiln_inspect shot from 5.6–5.9 s to 1.5–1.7 s. The key is read off the scene as the shot leaves it, not off the request. It covers:

      • the artifact hash and the export options;
      • every node's visibility, transform and place in the tree;
      • each geometry attribute's identity and edit version;
      • every material property, and each texture's identity, version and transform;
      • morph weights, skinned bone poses and instance buffers;
      • the lower levels of detail set aside.

      A hidden part, a posed clip or a lower level of detail drawn therefore exports its own bytes. A scene holding anything added after it was loaded has no key and exports every time, as before. Two calls that export one state at once store it once. The host keeps up to 64 MB of derivatives for its lifetime.

    • The capture cache's check, the port's trust check and the annotator decode one frame once between them, keyed by its bytes. A fully cached 9-shot call goes from 4.0–4.6 s to 2.8 s. The host keeps up to 64 MB of decoded frames for its lifetime.

    • Images, hashes and receipts are unchanged.

  • kiln_render and kiln_edit draw shots that change only the camera from the artifact itself, in one request per projection and service limit, after asking the capture cache. On a 2.6M-triangle cathedral on Node 22.23.4, nine shots at 1000 px on a built program went from 301 s to 7.1 s, all nine cached from 260 s to 4.2 s, and one shot from 42 s to 3.6 s. Same-camera images differ by at most one level per channel. A shot that changes what draws (visibility: 'isolate', hide, or a subject in a lower level of detail) keeps a derivative for that shot, which now skips the QA, validator, metrics and manifest work that derivative discarded (9.1 s to 2.5 s for one isolated shot). kiln_inspect shots stay on the derivative route. Results change where they report this: derivativeReceipts[].inputGlbSha256 of a camera-only shot is the artifact's hash, its compact receipt can omit the hash when viewFidelity already states it, a receipt on a host with no retained artifact reads reasonCodes: ['IN_LOOP_BUILD_NOT_PERSISTED'], and on a host with one viewFidelity.exactArtifact is true when every shot was exact. ./render exports renderReviewDerivativeGlb.

  • Camera bounds, GLB accessor decode and the integration manifest allocate and read less on large assets: bounds no longer build a record per triangle, unnormalized accessors copy directly, and drawnSceneBounds visits each referenced vertex once per placement. Cameras, review geometry, bounds and the manifest are byte-identical on the cathedral.

  • output: 'separate' is no longer charged for a grid sheet it never builds, and a refused capture states the shots, the size and the largest size that fits as a grid and as separate images.

  • A missing evaluator worker file now names the rebuild instead of Evaluator worker pipe failed., and Windows' EOF on the worker pipe waits for the worker to close like EPIPE.

  • GPU instancing now draws what the copies drew as separate nodes, in both KILN_BAKE_INSTANCE and the three runtime target's repeatInstances. A mirrored copy no longer shares a batch with unmirrored ones, where it drew inside out: single-sided surfaces vanished. Mirrored copies form their own batch on a node scaled [-1, 1, 1], with no second copy of the geometry. three r186's WebGPU renderer does not transform instance tangents, which shaded a quarter-turned normal-mapped copy black. The bake pass now batches tangent-bearing copies by the rotation they share and puts it on the batch node, and the runtime target keeps a turned, stretched or mirrored tangent-bearing child separate. The bake pass also keeps a sheared copy separate, because instance transforms cannot state shear. EXT_mesh_gpu_instancing is now required wherever Kiln batches, so a viewer without it refuses the file instead of drawing one copy. Batches and draws change on affected assets, including role: 'fill' assets under the default auto. A saved revision built with instancing on can now rebuild with matchesSavedArtifact: false; the saved GLB is unchanged.

  • kiln export ... --profile runtime --draws minimal [--draw-cell M] (and draws: 'minimal' in exportAssetGlb) derives a file with fewer draw calls. Every repeated mesh becomes a batch, and parts with a single-user mesh merge per material within cells of M metres (default 15). It runs no palette() or weld(), and the saved revision is unchanged. The sidecar's drawReduction reports the result. On the 1,834-draw cathedral revision it gives 283 draws, with the same triangles and 1% fewer bytes. mergeRigidGroups gains opt-in cellSize and positionTolerance; optimize: 'full' is unchanged.

  • Three repeated costs on large assets are paid once. Measured on the 2,635,224-triangle cathedral, whose 1,707 meshes share 184 geometries:

    • The open-surface penetration rule measures each shared geometry's topology once per pass. The pass goes from 3.9 s to 0.5 s and an in-process cold build from 23 s to 20 s. The evidence is byte-identical.
    • An unchanged atlas provenance table is validated once rather than by every reader. Loading the review scene goes from 1.4 s to 1.1 s. An entry answers only while the table's canonical JSON is unchanged, so an edit in place is validated again.
    • A host that found no render service at startup now knows the capture identity before its first render. That first capture is cached like any other: its repeat is a hit, where before it rendered again (4.9 s instead of about 2 s for the default grid). The identity follows the port's own connection, so the start it makes is the one the first request would make.
  • The GPU render service samples the UV set a texture names, with its KHR_texture_transform. The service replaces each decoded map with a DataTexture for upload and copied only colour space, flip, wrap and filters, so a map with texCoord: 2 sampled UV0 and a transformed map drew untransformed: four assets whose base colour sampled UV0..UV3 rendered pixel-identical. The replacement now keeps channel, offset, repeat, rotation, center and the texture matrix.

  • A perspective view drawn after orthographic ones in one render-service request is shaded for its own camera. three compiles a node material's view direction for the first camera that draws it, and its program cache ignores the camera, so the legacy beauty view, and any perspective camera after an orthographic one in camera mode, reused the orthographic program: on a glossy metal sphere 9% of the beauty's pixels differed by up to 97/255 from the same camera drawn alone. Materials are now keyed by projection, so the beauty matches a perspective-only render byte for byte; orthographic sheet views are unchanged. A request that switches projection builds one more program per material. Both changes alter render-service source, so its build identity changes and a running service of the previous build is reported as incompatible rather than joined.

  • scripts/check-vision.mjs works on OpenCode 2.x. OpenCode 2.2 rejects opencode models --verbose, so the gate reported every model as unverified. On 2.x it now reads the catalogue from opencode api --standalone GET /api/model and its capabilities.input; a 1.x install still uses --verbose. The docs say the script covers OpenCode models only. docs/harnesses.md records that OpenCode 2.2.0 delivers MCP images to the provider in Code Mode and with codemode: false.

  • KILN_EVALUATOR_TIMEOUT_MS now works above 60,000, as documented. Only the host read it: the worker kept its own 60-second timer, so a build that yielded to the event loop after that failed with DEADLINE_EXCEEDED at any limit, usually once the abandoned build had run to its end. The worker now takes the protocol maximum and leaves the deadline to the host, which kills it at the limit in force. The worker's own timer moves from 60 to 120 seconds, so a worker left behind by a host that died stops a build that yields at 120 seconds rather than 60. The default stays 60 seconds, a host calling evaluateEvaluatorRequestV2 directly keeps its own 60-second default, and the isolated transport keeps its fixed 65-second CPU-time limit, which the setting does not raise.

  • The maintainer toolchain moves to Node 22.23.4, a security release, retaining Bun 1.4.2, npm 12.2.0 and consumer Node compatibility. The site takes astro 7.4.7 and @astrojs/react 7.1.4, which require it, and declares @emnapi/runtime 1.11.3: @astrojs/astro2tsx needs that runtime without declaring it, and rolldown's WASM binding otherwise hoists a 2.0 beta in its place, which stops astro check from loading.

  • dist/ is built, not tracked, so two source pull requests no longer conflict on it. A clone needs bun run build:runtime before its bundles, MCP server or tests work, and a pull needs it again; bun run test refuses a missing or stale build and names the command. The npm package is unchanged: it already shipped what CI builds. CI listens for merge_group, ready for a merge queue on main.

  • Project inventory items can state where they stand, and a project can be measured as it is composed (#277). placement on an inventory item holds optional translation, rotation (Euler XYZ degrees) and scale; {} means the shared origin, and a missing placement means the item is not composed, never identity. kiln project check <id> [--revision <r>] and kiln_project action check load the exact pinned GLBs of the placed items, compose them on the host, and run the existing part-volume and open-surface passes over cross-module pairs only, naming the module and part on each side with volume or depth. kiln_save records the same report as composition and in build.composition when the call's bound project pins this collection and asset at a placement, measuring the revision being saved rather than the older pin. A pin that cannot be read is reported unmeasured with coverage partial, never clear; a positive is a measurement rather than a verdict and never stops a save. Standalone assets get no report and no warning. A draft is not measured until it is saved. The key is omitted when absent, so existing project revisions keep their ids; a record that states one is refused by an engine older than this one, whose project schema is strict. The kiln_project schema gains the action.

  • Procedural materials have a periodic cellular (Worley/Voronoi) layer (#312). op: 'cellular' is a V2 layer, so it also reaches V3 through legacy-v2: integer cellsX/cellsY per tile, a seed, per-axis jitterX/jitterY and metricX/metricY, and optional additive weight. Its feature maps onto colorA→colorB: f1, f2, f2-f1, a flat cell tone, border (joints opened by an order-independent hash of the two cell ids, with borderOpen and borderWidth) and facet (a tilted plane per cell, blended without a step, for height). The search is exact for every seed, by a stated bound that tests hold against an unbounded search. Golden pixel hashes pin each feature, because a V2 recipe hash has no compiler id. In V3 it is charged measured work, about 50 units per texel, instead of the flat 4: one default layer fits at 1024, and a facet or a stack is refused there and fits at 512. Existing recipes keep their hashes and compiler ids. kiln discover --query voronoi and --query worley find it, with recipe:cellular-stone-v1 as a worked example. Cellular layers has the fields and the bound.

  • The floating-parts warning and GEO_PART_CONNECTIVITY now see primitives merged into one mesh (#304). One mesh was one bounding box, so a welded component was never compared with the rest at any distance. Each mesh is now split into its connected components, through triangles and shared positions, and each gets its own box; the 2 cm floor is unchanged. Many loose components of one mesh collapse to one finding that locates the nearest one and what it sits nearest to. Instanced and skinned meshes, LOD alternates and foliage or decal names stay whole, as does a mesh over 262,144 vertices or 256 components, which a finding names. Over the 86 historical examples this moves connectivity findings from 18 in 8 assets to 43 in 9, beside part-volume's 3,575 in 86 and open-surface's 916 in 50. All 25 new ones are in demo-dauntless-cv-08, whose per-material meshes had bridged unrelated parts: its deck markings were one box across the whole deck. A split can therefore report parts that no welded mesh contains. partsAnalyzed now counts components, and connectivity groups gain a node field.

  • A build over the evaluator's output budget now says which budget it reached (#317). The error names the stage (glb or response), the limit, the size and, for a GLB, the triangle count, and says what to try next; it was Evaluator output limit exceeded. alone. The fixed wire message is unchanged, and the numbers travel in a closed limit field that the protocol validates, so a new worker needs a host that knows the field. KILN_EVALUATOR_MAX_GLB_BYTES raises the GLB limit to 64 MiB, with the response budget following to at most 96 MiB. It is host-only and the defaults stay 16 and 32 MiB. The subprocess worker now bounds its response by the protocol's ceiling and leaves the budget to the host, which stops reading at it; without that, a raised limit would have failed inside the worker at 32 MiB, and an over-budget response was reported as invalid input. Large assets gives the measured sizes and the supported routes.

  • Material revisions can record their parent (#310). parentRevision on a V1 or V2 draft, or kiln material procedural --parent <sha256:revision>, must name a saved revision of the same materialId; get, list and the kiln.material-maps.v1 sidecar report it, and it survives export and import. It is optional, and the key is omitted when absent, so existing records keep their revision ids. A record that carries it is refused by an engine older than this one, whose manifest schema is strict.

  • Materials accept a generated source for maps from a local deterministic program (#311). It needs no assetUrl, which is what forced an invented URL before, and requires a generator record: the program's name, version and sha256, its toolkit hashes, the seed when it takes one, and runtime versions. Kiln verifies the shape and the stored bytes, and does not run the generator or prove the bytes came from it. external still requires an HTTP(S) URL and existing records keep their revision ids. A record with this source is refused by an engine older than this one.

  • kiln_export takes a programRef, so a destination audit can read the built GLB before a save instead of after one (#309). It returns a kiln://programs/{program}/{sha256}/asset.glb resource with the size, hash, triangle count and draw diagnostics, and writes nothing. The bytes are the ones kiln_save then persists. The URI pins the hash it was issued for and the build runs again on read, so a program this host now builds differently is refused rather than served as the same bytes. The runtime profile still needs a saved revision. This changes kiln_export's input schema: assetId and revisionId are now optional in the advertised shape and checked when the tool runs. kiln_present and kiln_export_to are unchanged.

1.6.0 (2026-10-27)

  • kiln_export_to takes textures: 'manifest', so an MCP author can act on the texture duplication kiln textures reports instead of only seeing it. The runtime sidecar gains textures[] naming each embedded image by sha256 and mime type, which lets a destination share one copy across assets rather than loading the embedded copy in every GLB. The option is runtime-only; editable publishes the exact saved GLB without calling the exporter, so that combination is refused at the tool rather than accepted and dropped. Exported GLB geometry and images are unchanged, but the GLB is not byte-identical and must not be: provenance binds the sidecar's hash (kilnProvenanceV1.metadata.sha256), so adding textures[] necessarily moves it and the pair stays verifiable. Discovery capabilities report the option under assets.exportTo.

    Two deliberate exclusions. textures: 'external' stays a CLI delivery: it writes x.gltf, x.bin and textures/<sha256>.<ext>, while kiln_export_to writes one GLB and one sidecar through an atomic pair write, so carrying it would mean new file kinds and a path contract that is not .glb. And kiln_export does not take the option at all, because it returns resource links that readAssetResource re-derives with no options from a fixed filename allowlist -- a link would advertise a size that a later resources/read of the same URI would not deliver (#287).

  • Source between the program store's 1 MiB limit and the evaluator transport's 512 KiB is named as the size problem it is. Such a program saved, edited and validated, then failed evaluation through the generic invalid-request path, which reported the size as something else in each of three ways: a host-injected transport threw a bare invalid evaluator request with no outcome code; the local subprocess and isolated evaluators degraded to PROTOCOL_ERROR, "Evaluator returned invalid data", because a request the worker cannot decode returns without the request id the host matches on; and a host handing raw request JSON to the evaluator handler got INPUT_INVALID, whose message advises updating host and worker together and reading docs/migration.md. Both request builders now refuse an oversize source before it leaves the host, naming both byte counts and the repair. The worker keeps reporting a request it cannot decode as the malformed request it is: each host rebuilds the message from the outcome code and discards the wire message, so a cause named inside the worker could not reach a reader, and the engine gains no new outcome code an older host would decode as a protocol error. kiln_validate and a render: false kiln_edit report the same finding as a warning at save time -- in MCP and in kiln validate / kiln edit, which declare that one host fact rather than building a host -- and the source stays valid, because it is. Trusted KILN_EVALUATOR_MODE=in-process evaluation builds no request, has no such limit and is not warned about. The two limits are unchanged and still differ on purpose: a stored revision is read, imported and exported without ever being evaluated, so the range is a documented gap rather than a mistake to close, and docs/programs.md now states both (#299).

  • QA measures open surfaces against the closed solids they meet. GEO_OPEN_SURFACE_PENETRATION samples each open surface's vertices against every closed solid whose bounds it overlaps and reports how far inside one it reaches, naming both parts and the depth. A cloth, canopy or ivy card encloses no volume, so the part-volume observer could only ever report it unmeasured -- which meant a throw resting on a seat and a throw running through a wall produced the same sentence. Reproduced before fixing: the two cases were byte-identical GEO_PART_SELF_INTERSECTION_UNMEASURED findings, and a closed-solid overlap across two modules composed at one origin was already reported, so what was missing was the open-surface measurement rather than neighbour awareness. Distance is measured before sign: a vertex within the 0.005 m contact tolerance is contact, and no sign is claimed there, which is why a cloth authored exactly flush is silent -- that is the one position where a parity ray grazes the face it starts on. The tolerance is deliberately not the 0.02 m adjacency tolerance FLOATING_EXPAND and EXTERNAL_SUPPORT_TOLERANCE share: measured fixtures put authoring slop at 1-3 mm and real defects at 30-60 mm, and 2 cm would let a surface sink unreported into a cushion, a canopy panel or a wall cap. Synchronous, offline and deterministic: the open/closed split comes from edge topology, so no solid is built. Observation only, bounded, and reporting what it left unsampled; a clean result is not a fit audit, and a solid thinner than the sampled surface's facet spacing can pass between two of its vertices. A positive is a measurement, not a verdict: measured over the 86 shipped examples it reports 916 findings across 51 of them, against 3,575 from the part-volume pass across all 86, and the dominant real case is a fitting socketed into a structural shell -- correct geometry, reported the same way a bolt in a hole is (#277).

  • kiln textures <files-or-folders> [--json] reports the texture duplication a delivered set ships: embedded image occurrences against distinct images, the bytes sharing would save, and each distinct image's hash, size and the assets carrying it. The duplication is between assets, never inside one -- measured over 160 assets in four real worlds, within-asset duplicate images were 0 every time -- so a per-asset receipt count cannot see it and the report is scoped to a set. It reads bytes and writes nothing, so exported and canonical GLBs stay byte-identical; acting on it is the existing --textures external or --textures manifest from #213. Library export: textureSharingReport from @instruktlabs/kiln/asset-export (#287).

  • Every material helper takes an optional name, written to the exported glTF materials[].name: gameMaterial, basicMaterial, glassMaterial and lambertMaterial in their options object, pbrMaterial and foliageMaterial in theirs. Both exporters already carried a name that was set, and it survives the sandbox, dedup and every optimize level; what was missing was any way for an author to set one, so delivered assets arrived with unnamed materials and the authored distinctions were lost. A name is 1..200 visible characters, matching the portable material spec's own bound, and control characters are rejected. This gives a destination runtime a stable authored key to group draws by, instead of hashing material factors. materialRecipe and the portable material specs already named their output and are unchanged (#288).

  • remapUVToAtlas takes an optional axes. The default uv is unchanged and replaces both components, which silently destroys a per-vertex gradient carried in V — a foliage wind sway weight read as uv-y is the known case, and the asset still validates and renders. axes: 'u-only' rescales U into the named region and passes V through bit-for-bit, requiring inputOrigin: 'top-left' over a region spanning the full atlas height, so a column sheet keeps the gradient while U can still be inset to texel centers. A packed or vertically inset region is rejected rather than remapped. The binding records axes only for u-only, so existing stamps and exported extras are byte-identical. The helper contract, Discovery notes and authoring guidance now state what replacing V costs (#293).

  • The floating-parts warning and the part-connectivity observation state their coverage: both read the bounding boxes of drawn meshes at a 2 cm tolerance, so a smaller gap reads as contact and primitives welded into one mesh are never compared with each other. The QA integration reference says to measure millimetre contacts in the destination before saving. Reproduced from a reported clean pass on a 2 mm detached part; the checks behaved as specified and the tolerance, not welding, is what admitted it. No check changes behaviour (#289).

  • The delivery contract states how to read a Kiln GLB without a DOM. three's GLTFLoader reads self.URL for every image, so parseAsync on a textured GLB throws ReferenceError: self is not defined under Node, and under Bun, which defines self, it binds a null map instead. An untextured GLB parses either way, so test scaffolding written against one passes and the same pattern fails on the first textured asset. The supported DOM-free path is loadGlbReviewScene from @instruktlabs/kiln/views, already public and already what the CPU view path uses; a reader assembled from gltf-transform directly drops the MSFT_lod chain unless the extension is registered. A new test loads a textured GLB through the reader with self deleted, so the documented guarantee cannot regress. Engine behaviour, exported bytes and browser loading are unchanged (#292).

  • The draws cap in defineBudget states its pass scope. Discovery and the delivery contract already said the figure is what the GLB stores before any consumer batching; both now also say it counts the main pass only, because shadow, reflection and depth passes belong to the destination, where a shadow-casting part can cost a further draw in each. Wording only: no measured value, receipt field or tier status changes (#291).

  • defineBudget accepts zero material caps. images: 0 and decodedBytes: 0 are now valid: zero is the honest declaration for an untextured asset, and the evaluator already measured it correctly, passing at measured 0 and failing the moment a texture appears. A new capacity() validator takes non-negative integers for the material caps, while count() still requires a positive integer for triangles and draws, which describe what an asset must have rather than what it may carry. This relaxes a deliberate contract: { images: 0 } was previously rejected, and a test asserted that rejection. Specs that were valid before remain valid (#286).

  • The repair advice shown when a delivery helper fails states the defineBudget contract in full. It described the helper as defineBudget({ triangles, draws? }), omitting images, decodedBytes and materialTier, which Discovery's helper spec and the SPEC_SHAPE string both list — so an author whose call failed for an unrelated reason was told those fields did not exist. A test now asserts the advice names every field the validator accepts, so the text and the validator cannot drift apart again.

1.5.0 (2026-10-25)

  • Generated Codex workspaces forward KILN_EXPORT_ROOT to the MCP server, so kiln_export_to is advertised under Codex as under the other harnesses, and Discovery capabilities report the tool as assets.exportTo (null when absent, never the absolute root) (#207).
  • The delivery contract explains every delivery finding: what it checks, its tolerance and units, and that all are advisory. DELIVERY_COLLIDER_NO_OVERLAP is collider-to-geometry overlap, not contact between colliders (#199).
  • Document optional SDK setup for generated workspaces. The compose and QA integration references gain an "Optional SDK use" paragraph: a workspace has no package.json, so @instruktlabs/kiln/render and /composer fail with ERR_MODULE_NOT_FOUND until the author installs @instruktlabs/kiln pinned to the runtime version in use; CLI/MCP-only authoring is unchanged (#179).
  • The optional compose-scene workflow now says how a scene's aggregate export receipt follows a changed asset revision: regenerate it from fresh kiln export … --json receipts, check revision id, GLB bytes and hash and sidecar hash against the emitted files before claiming delivery, and keep superseded entries as immutable history[] rather than rewriting them. Guidance only; standalone assets and the engine surface are unchanged (#180).
  • State plainly in Discovery that extrudeProfile, revolveProfile and roundedBoxGeo output no UV0, and relate projectUV and autoUnwrap from the first two. The MAT_TEXTURE_UV_MISSING repair now names both projectUV (for example box projection) and autoUnwrap instead of a generic "unwrap". The block is unchanged: a texture-backed material on geometry without UV0 still fails QA, and no projection is added automatically (#177).
  • kiln --version prints the installed version and exits 0 (#202). docs/programs.md lists the sandbox globals and refused host capabilities, and docs/geometry.md states the exact-equality export weld that was documented only in the migration notes.
  • Budget receipts state that draws caps unbatched LOD0 draws (unchanged) and add measured.instancedDraws on the LOD0 tier when a draws cap is declared: the draws the three runtime target leaves after batching each repeatInstances group. It is informational and never changes the tier's status (#200).
  • The three runtime target takes maxLod (CLI --max-lod N): it keeps LOD0..LODN of each MSFT_lod chain and removes the lower levels with what only they used, trims their thresholds, leaves budget tiers above N out of the shipped declaration and records all of it in the sidecar's delivery.lod. The default keeps every level (#196).
  • The three runtime target takes positionBits (CLI --position-bits 8..16|float) for position quantization; other attribute classes are unchanged and the default stays 14 bits. The sidecar's delivery.quantization adds positionSteps (the grid step in metres per mesh node) and maxPositionStep, and bits.position is 'float32' for float positions. With float positions, KHR_mesh_quantization is still declared for the quantized normals and texture coordinates (#197).
  • Add the seededRandom(seed) sandbox global for reproducible random variation (#244). It takes a finite number or a non-empty string and returns next(), range(min, max), int(min, max) (both ends included, like THREE.MathUtils.randInt), pick(array) and fork(label), an independent stream derived from the seed and label rather than from how many draws were made, so a variant can replay a parent's draws. Seeds are hashed with FNV-1a and drawn with mulberry32, the generator scene layout and material presets already used. Builds that use it stay cacheable; Math.random still bypasses build reuse. Discovery finds it for "seeded random".
  • Add simplifyGeometry to derive a lower-detail copy of a part for an LOD tier (#243). await simplifyGeometry(geometry, { ratio }) (or { targetTriangles }, with optional maxError and lockBorder) uses the pinned meshoptimizer simplifier and returns new geometry without changing the input. Material groups are simplified separately with their boundaries locked, UV and normal seams and open borders hold, and surviving vertices keep their exact attributes. userData.kilnSimplify records the triangle counts, achieved ratio and the simplifier's error; a missed target is a SIMPLIFY_TARGET_NOT_REACHED build note. It never runs implicitly or to meet a budget. The defineLod contract no longer says Kiln simplifies no geometry and points to it.
  • Name profile solid failures across the sandbox (#178). An extrudeProfile or revolveProfile call whose outline, holes or bevel cannot become a solid now rejects with the closed cause PROFILE_SOLID_FAILED and engine-written repair advice, instead of the bare generic rejection; out-of-scale coordinates and holes that consume the outline are two reduced cases. No library message crosses the boundary, and PROFILE_BEVEL_COLLAPSE still names an over-large bevel. The generic rejection now says that kiln_validate checks syntax and static rules but cannot see execution-time failures, and points to reproducing them with kiln_render.
  • Map cylindrical projectUV poles and name profile solid failures (#178). A bevelled revolveProfile whose outline touches the axis ends in sloped triangles meeting on it; cylindrical projectUV gave that pole no defined angle, so the mesh smeared U or, at some segment counts, threw and rejected the whole program. A corner on the axis now takes the mean U of the other corners of its triangle; cone apexes are treated the same way. Separately, an extrudeProfile or revolveProfile outline that cannot become a solid (for example out-of-scale coordinates, or holes that consume it) now rejects with the closed cause PROFILE_SOLID_FAILED and engine-written repair advice instead of the bare generic rejection; no library message crosses the boundary, and PROFILE_BEVEL_COLLAPSE still names an over-large bevel. The generic rejection now says that kiln_validate checks syntax and static rules but cannot see execution-time failures, and points to reproducing them with kiln_render.
  • Export a saved material revision's maps as tiling textures with a planar preview (#246). material export <id> <revision> --maps <dir> --size <px> [--repeat <metres>] [--tiles <n>] writes one PNG per map at the stated size, a lit tiles × tiles preview and a kiln.material-maps.v1 sidecar naming each map's slot, colour space, size, repeat, source revision and sha256. A V2 layer recipe is recompiled at the new size; other maps resample with a wrapped Catmull-Rom filter. The preview uses the GPU render port when one is configured and records its renderer and viewFidelity, so a CPU preview is never read as material evidence. Existing files are never replaced. exportMaterialMaps and createMaterialMapExport from material-library/node do the same for hosts; --out and MCP are unchanged.
  • Material measurements no longer read as a budget nobody declared. Without a material limit, receipts list materialAdvice[] beside budget and QA reports observe findings MATERIAL_TEXTURE_RESOLUTION_ADVICE, MATERIAL_IMAGE_COUNT_ADVICE, MATERIAL_DECODED_MEMORY_ADVICE and MATERIAL_BLEND_AREA_ADVICE (formerly *_BUDGET warnings) against the web.portable.v1/standard reference tier, worded as optional advice. defineBudget gains images, decodedBytes and materialTier, measured in budget.materials and covered by --strict-budget; triangles is now optional when another limit is declared (#176).
  • Report geometry deltas against the parent revision on save (#245). A kiln_save (and kiln save --parent) with parentRevision now returns comparison: the drawn triangle, vertex, draw-call and material counts as parent, child and delta, the drawn bounds sizes and their delta, and geometryIdentical, a hash of the sorted drawn world-space triangles at float32 precision that ignores node, primitive and vertex order, with uvIdentical when the geometry matches. Merging four primitives into one without moving a vertex now reads as identical geometry with three fewer draws instead of only a changed part. A comparison that cannot be made reports unavailable and never fails the save. kiln_inspect compare (and kiln_edit preservation) gain the same counts, geometryIdentical, uvIdentical and boundsDelta. No input changed.

1.4.0 (2026-10-23)

  • Encode KTX2 through an optional ktx2-encoder peer (#201). export --target three --ktx2 (or ktx2Encoder: await createKtx2Encoder()) uses ETC1S for base colour and emissive and UASTC for normal and other linear maps, refuses an image shared by both kinds of slot, and records the encoder name, version, Basis WebAssembly hash and settings in delivery.ktx2.encoder and the --json receipt. Kiln does not install or bundle the peer: run npm install [email protected] (MIT; its bundled Basis Universal encoder is Apache-2.0 with its notice in the package). The KTX2 hook now receives the slot, requires the KTX2 identifier in its output, and rebinds atlas provenance to the encoded bytes, so an encoded atlas passes import validation.
  • Add an opt-in runtime texture manifest and content-addressed external textures (#213). export --profile runtime --textures manifest adds sidecar textures[] naming each image's exact sha256, size, colour space and, when its bytes equal a saved library map, that material pin. --target three --textures external --out x.gltf writes JSON glTF whose images are shared textures/<sha256>.<ext> files: an identical existing file is reused, a different one stops the export, and rollback never removes a texture. Without --textures, runtime GLB, sidecar and receipt bytes are unchanged; MCP does not offer the options.
  • Name the rule in material validation errors (#198). Sampler, procedural V3 and atlas checks now report the canonicalizer's reason (for example "stamps are supported only for color usages albedo and emissive") instead of a bare "Invalid input", and run only after the field checks pass. Tool input errors drop a bare parent "Invalid input" line when an issue inside that record already explains the failure.
  • Advertise renderer status separately from reprobe (#206). The new read-only kiln_renderer_status (readOnlyHint: true) lets hosts that auto-allow reads check status without a prompt; kiln_renderer stays stateful and still accepts action: "status". The packaged MCP server lists eighteen tools and the native registry eleven (sixteen with delivery). In the named-operation presentation kiln_renderer_status is now read-only and kiln_renderer_reprobe stays stateful. Status and reprobe results add ready, activeRoute (gpu or cpu) and fallback (active, with materialFaithful: false and a reason when views will be CPU geometry). kiln_discover({ capabilities: true }) is unchanged.
  • Add kiln-init --progress-file PATH for the compaction handoff (#212). The workspace-relative path is recorded in .kiln/workspace.json, named in AGENTS.md and START.md, and kept by --check, --upgrade and --repair, so a host with folder-scoped edit permissions no longer approves every root KILN_PROGRESS.md update. Absolute, traversal and managed paths are refused. The default guide is unchanged.
  • Add repeatAlongCurve for leaflets, cards and studs along a sampled curve (#211). By default it merges the copies into one geometry (one primitive per frond) with each copy's UVs kept, an optional _along attribute and an opposite row; merge: false returns shared-geometry nodes. Merges are bounded at 262,144 vertices. Discovery now answers foliage wording ("palm frond leaflets", "fern", "grass clump") with the repetition and card helpers, and the authoring skill describes the foliage workflow and when per-element naming applies.
  • Accept derive: normal-from-height on V3 normal-slot maps in schemaVersion:2 material drafts. Derivation reads compiled RGB luma as height, counts toward the V3 budgets, is recorded in the saved recipe and reapplied by verification. V3 stamps now accept data usages such as normal, so a height recipe can emboss the albedo's stamped pits; palettes stay colour-only. V2 derivation identities and existing V3 recipe hashes are unchanged (#205).
  • Export vertex colours (COLOR_0) and lowercase underscore author attributes such as
  • Export vertex colours (COLOR_0), a second UV set (uv1 as TEXCOORD_1) and lowercase underscore author attributes such as _wet (as float _WET, 1 to 4 components) through the default legacy converter as well as three; the runtime three target lists them in customAttributes in the same order as delivery inspection. A color attribute now tints the exported surface in glTF viewers instead of being dropped with a warning. docs/geometry.md lists the attributes each converter keeps. A texture with channel = 1 exports with texCoord: 1, and a mesh it samples must have uv1 (#195).
  • Add optional material merge advice to the instanceability report: drawn materials that share alpha, sidedness, texture bindings, extensions and extras but differ in factors are listed with their parts, the differing factors, what a merge needs and the projected material count and grade. The advice is labelled optional and never changes the grade or any QA disposition (#209).
  • Add natural material presets beach-sand, coral-limestone, coral-limestone-wet, palm-frond, driftwood and thatch, tagged by family (ground, rock, foliage, wood, fiber). palm-frond is an alpha-tested, double-sided cutout saved as a schemaVersion:2 record; createMaterialPresetDraftAny returns any preset's draft, and preset summaries report recordSchemaVersion. The docs list the presets as a table that a test keeps in step with the catalog (#210).
  • Add a second set of material presets (#221). lime-plaster, oak, linen, jute, basalt, terracotta, wicker and brushed-brass follow the #210 contract: base colour, normal derived from height and packed metallic/roughness, an explicit seed and licence, a stated repeat scale and a family tag. They are synthetic starting points, not scans; the docs table and its test list them.
  • Name procedural texture usage errors and add kiln validate (#215). An unknown proceduralTexture usage (such as data) or a usage that does not match its portable material slot, in V2 or V3, now crosses the evaluator boundary as the closed PROCEDURAL_TEXTURE_USAGE diagnostic; its advice lists the seven usages and the slots that take them, instead of the bare rejection sentence. Discovery's proceduralTexture contract lists them too. The new kiln validate <program.js|ref> [--json] serves the same kiln_validate check from the CLI, prints the programRef and exits 1 when the source is invalid; the generic rejection advice names both forms.
  • Add metric UV projection (#216). projectUV accepts metersPerUnit: one UV unit maps to that length, measured from the frame origin, so parts of different size tile at the same texel density and pieces that share a frame keep the same phase. A full cylindrical wrap rounds to whole tiles at the largest radius so the seam stays continuous. Calls without it are unchanged. The contract and geometry docs say to weld the non-indexed output with mergeVertices where the projection is continuous.
  • Normalise non-unit normals on export (#217). A raw THREE.LatheGeometry whose profile nears the axis left pole normals of length 0.02 to 0.13, and export stopped with repeated GLTF_ACCESSOR_VECTOR3_NON_UNIT lines naming an accessor. Export now writes those normals at unit length with one NORMALS_NORMALISED note naming the part and count, leaving the authored geometry and unit normals untouched. A zero-length normal fails naming the part and vertex, with lathe, revolveGeo or creaseNormals as the remedy.
  • Discovery: when some exact IDs are unknown, the known contracts are returned in request order beside the UNKNOWN_ID error, which names only the unknown IDs; no substitution is made and a request with no known ID still returns no entries. pbrMaterial now ranks first for roughness-map queries (#218).
  • Allow the three runtime target without Meshopt (#219). exportAssetGlb/deliverThreeRuntimeGlb accept compression: 'none' and the CLI accepts --compression none with --target three: buffers stay plain, so a loader without a Meshopt decoder reads the GLB, while KHR_mesh_quantization, instancing and every preserved feature stay. The sidecar delivery.compression records { extension: 'none' }. The default output is unchanged.
  • Declare parts that rest on an external support (#220). A requirements binding can list externalSupport.supports: named parts and the plane they rest on outside the asset. A named part whose bottom meets that plane moves from the floating-parts warning to an informational line, and its connectivity observation becomes GEO_PART_EXTERNAL_SUPPORT naming the declaration. Undeclared parts, parts at another height and every other disposition are unchanged. The declaration is covered by the policy hash.
  • Add an opt-in host validation profile to requirements (#208). A host binding can carry requirements.validation, a closed kiln.validation-profile.v1 statement that selects final GLB nodes by name and checks primitive counts, required attributes, an attribute range or gradient along a local axis, and material alpha mode and sidedness. The exact rule HOST_VALIDATION_PROFILE evaluates it on the final bytes; in enforce mode its findings block kiln_render and kiln_save. The profile is part of the policy hash, so changing it refuses earlier reviewed artifacts. Tool input and source cannot weaken it, and Discovery capabilities show it as host-declared. Bindings without the key are unchanged.
  • Write exported files from MCP into a host-configured folder (#207). When the MCP server's environment sets KILN_EXPORT_ROOT (an existing absolute directory outside every collection and .kiln/), it also advertises kiln_export_to, which writes one saved revision's GLB, and for the default runtime profile its metadata sidecar, at a root-relative path. profile: "editable" writes the exact saved GLB and target: "three" the three.js runtime GLB, byte-identical to CLI export. Paths are relative, forward-slash and portable; links in the path and existing files are refused, and the receipt is the CLI --json receipt with root-relative paths. Without the variable the tool list is unchanged (eighteen tools), and kiln_export stays read-only with the same schema. Native registries add it to the delivery tools when an exportRoot writer is injected.

1.3.1 (2026-10-17)

  • Document private security reporting, include the policy in distributed packages, complete Codex plugin website and repository metadata, and configure monthly dependency update proposals.
  • Correct installation instructions to reference the published 1.3.0 plugin.
  • Use single-view posters for Cabin gallery assets on the website.

1.3.0 (2026-10-16)

  • Add optional game delivery roles, colliders, anchors, kit ports, surface bakes, budgets, solid assertions, atlas packing and a compressed Three.js runtime target. These describe explicit delivery choices; they do not impose an asset style or require every mesh to be closed.
  • Adapt the non-rock organic helpers contributed by FaberVi (Vincenzo Fabiano) in #141: metaball surfaces, field composition, sampled paths, tapered tubes, curls and smoothing. Maintainer integration corrects sampling, recipes, input validation and unsafe count arithmetic while retaining the original blend default. See the provenance record.
  • Preserve vertex colors and additional UV channels in review reconstruction and custom capture derivatives; measure draw diagnostics on Meshopt runtime exports; retain bounded topology facts when an explicit solid assertion fails.
  • Document quantized skin transforms and consumer-owned LOD selection, and bring demonstrated authoring and harness lessons into maintained workspace guidance.
  • Retry transient Windows permission failures when publishing material revisions, using the existing bounded atomic-directory helper. Existing revisions remain immutable and are accepted only after full material verification.
  • Recheck renderer health after observing a child exit during concurrent startup, so an earlier refused connection cannot hide another client's verified service.

1.2.3 (2026-10-12)

  • Allow concurrent renderer clients to await verified health through the shared startup deadline when another client wins the socket during a cold start.

  • Publish Cabin in the Woods: PSX Horror with 53 exact editable asset revisions, runtime and Full Kiln downloads, a portable scene, and integrated gallery pages. The WebGPU walkthrough includes first-person tools, fuel-driven fire, woodland interactions and fullscreen controls. Performance evidence and limits are recorded in the scene's review report.

  • Add opt-in named texture atlases, clone-owned region UV mapping and portable V3 material sampling. V2 saved material records carry RGBA recipes, atlas source manifests and exact dependency pins; standalone creation and complete offline material/project delivery preserve existing V1 records and explicit opt-outs.

  • Inspect named atlas bindings against drawn UVs, material slots and samplers without reading pixels. Report bounded or unavailable inspection as partial; structural checks do not establish intended corner orientation or appearance.

  • Add exact saved-material map inspection to Materials, Library and Live Review, with pixel zoom, light/dark/checker backgrounds and optional atlas-region labels. Raw map inspection remains distinct from material-faithful rendered evidence.

  • Add opt-in bounded V3 RGBA procedural surfaces with rectangular images, explicit shape coverage, alpha masks, palette mapping, fixed dithering and seeded periodic stamps. V1/V2 recipes, pixels, hashes and material records retain their behavior.

  • Preserve encoded image bytes for direct unflipped PNG/JPEG bindings in the experimental converter, including transparent RGB padding. Prepare raw maps for channel conversion and explicit vertical flipping without changing caller data; report native canvas load failures with recovery steps. Converted transparent images retain a documented pixel-fidelity limitation.

  • Correct project documentation: explicit call-level material pins replace matching project pins for that invocation without rewriting the saved project revision.

  • Diagnose malformed source skin bindings before bounds, texture baking and conversion, with mesh/joint/vertex-range findings through SDK, CLI and MCP. Read-only integrity inspection includes current morphed/skinned bounds and preserves authored data. Invalid bindings cannot bypass input validation through QA warning mode or derivative export; final glTF validation remains independent.

  • Add opt-in semantic createBoneChain and bounded explicit createSkinnedPart helpers, retaining rigid createJointChain behavior and legacy exporter defaults. Skin binding owns cloned geometry, preserves rich unchanged topology, validates explicit four-lane influences and provides closed CLI/MCP repair advice.

  • Extend GLB geometry/animation review to position and normal morph targets, default weight precedence and STEP/LINEAR/CUBICSPLINE weight tracks. Preserve independent influences across primitives, instances and review copies, apply morphs before skinning, and reject invalid data before claiming pose evidence. Other morph semantics remain explicitly unsupported by this review path.

  • Remove CPU preview cracks and duplicate shared-edge coverage on continuous triangulated surfaces. Both camera paths use top-left sample ownership and unbiased edge interpolation; clipped shared edges retain matching endpoints.

  • Correct CPU face culling under mirrored transforms and honor back-only source materials in both camera paths. Visible reverse faces now use the corresponding flat lighting normal; ordinary positive-scale front faces retain their output.

  • Reject used BackSide materials in both GLB converters with an actionable diagnostic, instead of silently writing front-only surfaces. Author inward-facing geometry or deliberately choose DoubleSide; existing saved GLBs remain unchanged.

  • Preserve independent skeletons in isolated, two-sided and composed-scene review copies. Hidden joint ancestors retain their transforms without rendering their geometry; copied bones and bind data no longer reference the retained source.

  • Reconstruct four-influence glTF skins in geometry/animation review and measure the sampled surface for CPU views and part bounds. Preserve joint hierarchy, inverse bind matrices and normalized weights; reject unsupported extra influence sets instead of showing a false pose. Supported POSITION/NORMAL morph review is described above; other target semantics remain explicit limitations.

  • Preserve explicitly authored texture filtering and wrap modes in the default GLB exporter, including separate samplers sharing image bytes. Existing procedural and loaded-texture defaults stay unchanged. Regenerated GLBs now encode those settings explicitly; saved asset revisions are not rewritten.

  • Reject unsupported sampler values in the default exporter instead of silently replacing them with glTF defaults.

  • Preserve supported vertex attributes, morph targets, material groups and metadata through autoUnwrap seam duplication. Reject unsupported inputs, invalid correspondence and the xatlas adapter's 16-bit index overflow. Existing normal defaults remain unchanged; normal morphs require useNormals: true. New UV0 invalidates tangents, which must be recomputed.

1.2.2

  • Clarify radial and tangential orientation for circular walls and roof sections, including edge checks for accidental quarter-turn rotations.
  • Require checking export receipts and delivering files from the final reviewed revision in the authoring skill and CLI guidance.
  • Include these instructions in the package and local plugin. Geometry/runtime behavior and the seventeen-tool local MCP interface are unchanged.
  • Align the public hosted integration draft with the deployed 21-tool contract, and update README/site guidance for the invite-only service and Discord access.

1.2.1

  • Load embedded viewer textures through the browser image path, retaining pixels, sampler settings and UV transforms under restrictive MCP Apps CSP. This uses the shared viewer and existing presentation tool; local and hosted tool counts remain unchanged.
  • Reject failed texture decoding instead of silently showing white geometry. The chat component labels its saved-preview fallback and can recover when another asset is presented. Advance the widget resource URI to invalidate cached component bytes.
  • Generate the MCP manifest before building sibling runtimes so one complete build keeps their identities consistent after a package or widget update.

Actual ChatGPT-host acceptance and hosted production deployment remain separate from local browser regression evidence and package publication.

1.2.0

  • Add an opt-in named MCP operation presentation generated from the shared registry, including consolidated asset search, material browsing and typed material creation. Existing grouped local tools remain the default.
  • Share action requirements with schema generation and reject unclassified fields/actions instead of silently dropping required inputs.
  • Omit unsupported renderer controls from the named presentation and use its available tool names in capability guidance and resource-recovery messages.

This additive SDK contract does not establish production-hosting readiness.

1.1.0

Existing-project setup, public host interfaces and simpler onboarding. Hosted deployment and directory submissions remain deferred.

  • kiln-init --adopt configures an existing project or a new workspace through the same initializer. Preview with --adopt --check; existing instructions, unrelated configuration, saved assets and customized skills remain intact.
  • Multiple compatible client registrations share one program store. Managed upgrades retain narrow configuration ownership and recover interrupted setup writes without putting recovery snapshots inside the project.
  • Explicit migration of a copied legacy OpenCode workspace replaces its old owned skill path instead of loading both original and copied instructions.
  • The local plugin's setup helper uses the pinned engine's adapter list. Plugin installation remains specific to Claude Code and Codex; those clients can also configure another supported workspace adapter through the shared helper.
  • Public mcp, discovery/portable, tools/input and views/port SDK entries expose existing host contracts without requiring imports of internal package files. Portable Discovery accepts an engine-generated catalog without loading Node's catalog builder. The local stdio entry keeps lazy engine loading.
  • The release verifier accepts versioned 1.x follow-ups and release candidates, retaining exact-archive evidence and owner promotion approval. Development builds and unsupported prerelease tags remain ineligible for staging.
  • Concurrent captures rejoin a replacement local renderer when a delayed failure arrives from the old connection. Startup failures preserve their bounded child error output instead of reporting only the stack footer.
  • The README and maintained guides lead with npm installation and distinguish released local functionality from deferred hosting. Real Troy captures join the existing scene and vehicle previews. Global and project-local CLI instructions explain the workspace launcher and avoid PowerShell argument forwarding errors. Historical examples move out of the active source tree; pinned Git-history restoration preserves the website archive and regression corpus.
  • The optional Linux isolated evaluator no longer passes an unsupported --preserve-fds option to Bubblewrap. Its explicit fd3 protocol pipe uses inherited descriptors; namespace, capability, filesystem and resource limits remain required by readiness qualification.
  • Isolated readiness compares the child's namespace and non-root identity with the parent, accounting for Bubblewrap's nested mapping when further user namespaces are disabled. The final worker environment is cleared again to remove Bubblewrap's injected PWD while retaining the exact allowed variables.
  • The isolated worker removes Node's legacy __proto__ accessor instead of throwing on reads, allowing Khronos glTF validation to initialize. Readiness verifies that the accessor is absent; a regression also checks that assigning a JSON __proto__ key cannot change an object's prototype.

1.0.0

Published on npm as @instruktlabs/[email protected] under latest, following the public 1.0.0-rc.1 prerelease. These are the changes since the 0.10.0 tagged package. Future publication follows the separate release gates in the runbook. Hosted deployment and vendor directory acceptance remain separate milestones.

  • Breaking: the npm identity is now @instruktlabs/kiln, with compiled ESM and TypeScript declarations for its public subpaths. The root is a library entrypoint; use the kiln executable for the CLI. kiln-mcp starts the stdio MCP server.

  • Consumer archives contain the maintained installation/API/workflow documentation; historical plans, reviews and model traces remain in the repository. Current repository links and package publisher metadata point to Instrukt Labs.

  • Installed isolated evaluation resolves compiled workers and readiness probes without a TypeScript loader. Host isolation still requires its own readiness proof.

  • The stdio executable cancels pending engine warmup when its client disconnects; a tool-list-only session no longer starts unused engine work after closing stdin.

  • Isolated evaluation explicitly requires a user namespace before disabling nested namespaces, satisfying Bubblewrap's launch precondition. Unsupported hosts still fail closed before source execution.

  • Windows asset saves retry transient directory-rename denials within a bounded delay, preserving atomic publication and existing immutable revisions.

  • Source restoration, MCP source resources, reviewed saves and CLI rebuild observations preserve an authored UTF-8 BOM instead of silently changing the source and its program reference. Invalid source UTF-8 is rejected on those reads.

  • Custom asset-library hosts can reuse the canonical saved-material resolver through @instruktlabs/kiln/assets/node.

  • The kiln-engine local plugin uses the Instrukt Labs marketplace and installs a pinned engine outside its disposable cache. It registers setup only; managed workspaces own the authoring skills and one MCP server. Upgrades preserve stores and refuse conflicts. The npm archive includes the small bundle and both catalogs. Replacing an older kiln@kiln installation requires the explicit plugin migration; public directory submission and hosted access remain separate release work.

  • Blind-run receipts recognize OpenCode's recorded code-mode MCP calls and AGY's generic MCP dispatcher without inferring execution from source or output text. Setup and authoring guidance now covers waiting for independent authors, checking sloping panel fit, retaining repeated parts during edits and saving child revisions before exporting. The eight-asset campaign records its incomplete handoffs and visual defects separately from valid exports.

  • Breaking (v1 candidate): optimize: 'full' replaces flatten/join with rigid-group merging. Its rigid-merge pass preserves node names, hierarchy and transforms, including animated targets, named joint pivots, semantic nodes, composition placements and LOD levels. Ordinary named mesh nodes can become empty or hold merged geometry. When geometry must remain on every named part, use optimize: 'off' or 'palette' with instance: 'off'; the separate GPU-instancing pass can remove named instance nodes. Shared-buffer expansion is limited to 4 KiB per saved draw, and merged buckets split at 65,534 vertices. Results expose boundary, lock and rejection diagnostics. New builds record rigid-v1; exact rebuilds of older unversioned full-mode revisions require their original engine or an explicit new authoring revision. Original saved GLBs remain exportable.

  • ORM packing isolates shared images per metallic-roughness/occlusion pair. Materials with different AO maps and consumers in other texture slots retain their original pixels, UVs and samplers; identical packing pairs reuse the packed image.

  • Scene browser tools share portable executable discovery and clean up temporary profiles on launch failure and close. The normal portable scene gate includes script tests, and the static server identifies WebP images correctly.

  • Cloudflare Pages deployment has a portable Node preflight that verifies the exact launch-mode artifact inventory, sizes and hashes against a clean checkout before upload. The PowerShell entry delegates to the same implementation.

  • Inspection and export summaries add bounded per-anchor draw counts, a qualified rigid-merge estimate, and sampled mirrored-tangent/coplanar-part observations. Compact render output and tool input schemas stay unchanged; estimates and flags are advisory, not GPU timings or QA acceptance.

  • Compatible dependency updates include glTF Transform 4.5.1, manifold 3.5.4, MCP client/server 2.3.0, Strands 1.19.0 with the compatible AI SDK 6/provider 3 family, image libraries and tooling. Site/scenes use Vite 8.3.2. Maintainer pins move to Node 22.23.3/npm 12.2.0, retaining Bun 1.4.2 and consumer Node compatibility.

  • The exact-input scene release gate verifies public pack hashes and cannot pass through missing-fixture skips. Shadow caches observe morph weights, Farm's economy tier retains its trailer casters, and Golden Gate reflections exclude dynamic traffic/player/fog while preserving vegetation; diagnostic fog hiding persists.

  • The scenes' dependency pin check resolves the engine, site and render service from the integrated checkout instead of hard-coded Windows worktrees. It now runs on the Linux hub and relocated checkouts; a filesystem regression test verifies collection and detection of an engine pin mismatch. Contributor and Troy resume instructions name the current validation and workspace setup commands.

  • The kit pass (applyKitContract, packKitGlb) no longer folds an occlusion map into the metallic-roughness image when the two are read through different UV sets or KHR_texture_transform values. It used to point the occlusion slot at the metallic-roughness UV set as well, so a baked AO map on TEXCOORD_1 was sampled through TEXCOORD_0. Such a material keeps its separate occlusion image and UV set, and the summary's new ormSkipped names the material and the reason; a matching pair packs as before, and packing no longer rewrites the occlusion slot's UV set.

  • src/render.ts and src/__tests__/optimize.test.ts no longer cite docs/kiln-material-consolidation-cycle.md, which exists on no branch; the OptimizeMode comment states the rule in place.

  • docs/runtime.md documents KILN_BAKE_OPTIMIZE and KILN_BAKE_INSTANCE: their values, that they only set the default for a render that omits optimize or instance, that the MCP and CLI tools pin optimize: 'off' (so only KILN_BAKE_INSTANCE reaches their GLBs), which library renders take the variables, and that a saved revision rebuilds with the options its manifest recorded. No behaviour changes.

0.10.0

Protocol revision 2026-07-28, and a server that answers before it loads. The v1 readiness cycle (plan) measures Kiln under Claude Code, Codex, OpenCode and Antigravity and fixes what the sessions show. Entries marked Breaking change what a client or an embedder observes.

MCP transport

  • The stdio server serves protocol revision 2026-07-28 beside the 2025 handshake revisions. @modelcontextprotocol/server and client move to 2.2.0 and ext-apps to 2.0.3. A 2026-07-28 client sends server/discover or any request carrying the per-request _meta envelope and needs no handshake; a 2025-11-25 or 2025-06-18 client sends initialize as before. Every 2026-07-28 result carries resultType and the server identity; server/discover, tools/list, resources/list, resources/templates/list and the viewer page read are public with a one-day ttlMs, while asset and project reads stay private with ttlMs: 0.
  • Breaking: a request that carries neither a protocol version nor a preceding initialize is answered -32602 with both ways in, instead of being served as a 2025 session. listChanged is no longer advertised for tools or resources (the lists are fixed for a build) and subscriptions/listen acknowledges no list-changed notifications. Advertised schemas no longer carry $schema.
  • The entry is thin. dist/mcp-server.mjs bundles the protocol library and a generated manifest of the definitions (src/generated/mcp-manifest.json, regenerated by the build and by bun run mcp:manifest), answers initialize, server/discover and tools/list from it (229 ms after process start in the startup test on the maintainer's PC, against 1.1 to 1.7 s before), and loads dist/mcp-engine.mjs on the first call that needs the engine, warming it once the harness holds the tool list. Breaking for hand-wired installs that copied the one file: both bundles must stay together.
  • Breaking: a configuration problem no longer kills the server at startup. A stale workspace, an invalid KILN_RENDER or a missing engine bundle come back as the first tool result, naming the next step and no local path; the next call tries again, so a workspace repaired while the harness is open needs no restart. A wrong command-line option and an unreadable or legacy --requirements file still exit 1 before the protocol starts.
  • Breaking for embedders: createKilnMcpServer, kilnMcpToolDefs and runTool moved from src/mcp-server.ts to src/mcp-engine.ts, and createKilnMcpServer returns the low-level Server; MCP_SERVER_NAME, MCP_SERVER_VERSION and MCP_SERVER_INSTRUCTIONS live in src/mcp-core.ts. src/requirements-json.ts reads a host binding file without zod; readHostRequirementsFile validates on top of it as before.

Tool surface

One versioned batch: tool definitions are prompt-cached, so every schema and description change lands together. Measured on the packaged manifest: the seventeen advertised definitions 39,603 characters as JSON (74,649 before), every input schema within 5,000 bytes (four were over, the largest 18,788), input schemas 26,475 bytes in all (61,598), src/generated/mcp-manifest.json 72,659 characters (205,917).

  • Breaking: kiln_project, kiln_material and kiln_review are one flat object each with an action enum instead of a root oneOf (Claude Code dropped all three). Every other field is optional in the schema; the server checks what each action needs and names the missing fields. The nested draft, patch and payload records are opaque in the schema and validated when the action runs; kiln_discover({ ids: ['shape:project-draft'] }) (and shape:project-patch, shape:material-draft, shape:material-import) returns the full JSON Schema through the new Discovery kind shape. kiln_project offers export only when the host can read project bundles. The field names and defaults are unchanged.
  • Breaking: kiln_edit capture, kiln_view_interior capture, kiln_inspect shot and kiln_screenshot_animation shot are advertised as opaque records; kiln_render states the capture shape in full, shape:capture and shape:camera-shot describe it, and each tool validates the record as before when it runs. The capture schemas live in src/tools/capture-input.ts.
  • kiln_validate, kiln_render, kiln_edit, kiln_inspect, kiln_view_interior and kiln_screenshot_animation accept file, a program file inside the workspace named relative to its root, beside code and programRef; absolute paths and .. are refused with the rule. A code-mode harness can hand Kiln a path instead of quoting a program.
  • The configured project is visible: kiln_discover capabilities carry project.configured, the overview says to read it first, and a project-bound render, edit, inspection or save result carries project: { projectId, revisionId }.
  • Breaking: the server instructions are 692 characters (2,297 before), name no absolute path and point at skills/ beside the server; the list of skills and the offer to copy them into .claude/skills/ or .agents/skills/ moved out. Workspace selection and camera field text is shorter, and every description opens with its purpose.
  • docs/tools.md is the packaged manifest pretty-printed (seventeen tools, the advertised bytes), no longer the embedding registry's fourteen.
  • kiln_material accepts resourceId, the name a project's palette and materialDependencies give a material, as an alias of materialId (a Codex session passed it twice and was refused both times); the advertised schema and the docs keep materialId, and a call naming both with different values is refused with the fix.
  • Breaking for a call that pins another revision of a project's material: a project revision implies its material pins, and a pin the call names replaces the project's or the inherited one for the same resourceId instead of being refused as a conflict (a Codex session repeated the project's five pins on every render, edit, inspect and animation call, 1,300 to 3,400 characters of arguments each, because the field said project locks could not be replaced). The materialDependencies description of the six workspace-bound tools says so in the same number of bytes.

Program handles

  • A programRef the store does not know comes back as a tool result that names the next call (kiln_validate or kiln_render with code) and no local path. kiln_validate, kiln_render, kiln_edit, kiln_inspect, kiln_view_interior and kiln_screenshot_animation state the retention of the handle they return: the packaged file store keeps it across sessions and processes without eviction. ProgramStore gains an optional retention sentence for injected stores, and docs/tools.md states the packaged store's.

Results

The baseline sessions measured a detail: 'full' render of 79,078 characters (cut near 40,000 before Codex's model saw it; 24% of it line breaks and indentation), 41 copies of one finding with the same 300-character repair text, and Agy writing every result over about 4,000 characters to a file the model then read back. A default result is now at most 20,000 characters and no result is over 40,000; on a 97-part fixture whose every part floats, the compact render result is 9,103 characters, full 16,734 and lean 2,018. src/__tests__/result-contract.test.ts and mcp-errors.test.ts hold the rules.

  • Breaking: every tool result is JSON on one line. A render, edit, inspection, interior or animation result leads with ok, acceptance, disposition, up to eight blockers (grouped by code with the repair text once), the findings counts and next, the sentence naming the next call; the programRef follows, then the metrics.
  • Breaking: the compact report groups the findings of each dimension by code, most severe first: one record per code with count, the first affected entity and up to two alsoAffected, findingsTotal, and findingsOmitted/omittedByCode beyond twelve groups. The rule records collapse to ruleSummary (evaluated, notEvaluated; notRequested rules are not listed). viewEvidence carries current and the hash-only lastFaithful, not the faithful history. The part preview is 24 paths with partsNextOffset and the kiln_inspect listParts hint. Build warnings are at most twelve of 1,000 characters each with warningsOmitted.
  • detail on kiln_render, kiln_edit, kiln_inspect, kiln_view_interior and kiln_screenshot_animation takes lean, compact (default) or full. lean is the verdict, blockers, counts, next step, metrics, a short fidelity receipt and three warnings. full is every finding, rule and part that fits 40,000 characters, with retainedReport: { operationId, path } naming .kiln/review/<operation>/evaluation.json (now pretty-printed) when Live Review records the operation; when the complete report does not fit, the warnings are bounded first, then repeated findings group by code with every rule kept, then the part list shrinks and the groups halve, and qaReport.detail reads full-bounded. The packaged host reads KILN_RESULT_DETAIL (lean or compact) as its default.
  • Breaking: a kiln_edit result is ok, applied, changed (status, part and animation summaries, the first five changes), next, the diff (2,000 characters in lean, with diffOmitted), preservation (not in lean) and the compacted render. The compact preservation.comparison is the counts, the artifact before and after and up to twelve changes as path, name, status and changed fields; the bounds of each change and the scope sentences stay in full (a live compact edit of a 49-part asset measured 20,069 characters with them, 7,191 of it the comparison). When a compact edit would still pass 20,000 characters, its diff is shortened first, never below 2,000, with diffOmitted.
  • Breaking: a kiln_inspect compare page in compact or lean is the same shape: the counts, the artifact before and after, offset, nextOffset and each change of the page as path, name, status and changed fields. A live compact page of 50 changes measured 38,952 characters with their bounds and the scope sentences; detail: 'full' keeps them.
  • Breaking: in compact and lean detail a per-view receipt (derivativeReceipts, and viewFidelity.receipts of shot and animation results) is its derivativeLabel, cameraFidelity, captureCache and only the fidelity fields that differ from the result's viewFidelity; the camera is in cameraShots under the same name. A live six-shot compact edit measured 22,417 characters with 4,672 of receipts repeating the summary and the cameras; full keeps whole receipts.
  • Breaking: a compact or lean result rounds every number to six decimals (a micrometre on a metre-scale asset); full and the retained report keep every digit. The 17-digit doubles of bounds, cameras and origins were 4,346 of a live 24,223-character compact animation result and 1,514 of a 20,556-character compact six-shot edit.
  • Breaking: in compact and lean detail, frames of an animation that resolve to one shot are stated once in cameraShots with frames counting them and each frame's bounds in poseBounds (nine frames repeated a 631-character camera and subject, 5,666 characters); viewFidelity states once what every receipt shares (the renderer id, a degrade reason); and viewEvidence.lastFaithful is omitted when it is the current view. When nine phases and many measured parts would still pass 20,000 characters, the leading frames of poseBounds stay whole and poseBoundsOmitted counts the rest, with poseBoundsHint naming the way to them; full keeps every frame that fits 40,000.
  • Breaking: a detail: 'full' edit is bounded as a whole. A live full edit measured 40,533 characters: its render bounded at 40,000 on its own, the 8,177-character diff and the 10,973-character comparison on top. The diff shrinks first (to 2,000, with diffOmitted), then the bounds of each change leave the comparison (the retained report keeps them), then the render is bounded again with what is left.
  • Breaking: kiln_edit no longer echoes the patched source when the program was sent as code: a live edit of a 13,173-character program came back at 28,539 characters, the source beside the render. The retained programRef serves it through kiln_source; includeCode: true asks for it, bounded with the rest of the result (codeOmitted, codeHint).
  • An invalid-input error no longer ends an issue sentence twice (...or file.. Check), and one that names a key the tool does not take lists the keys it does (kiln_material takes action, materialId, ...): a live session passed a project palette's resourceId to kiln_material get twice and was told only to check the schema. The materialId description names the palette's resourceId. A nested record the image tools enforce when they run (shot, capture) that fails to parse is the same kind of sentence naming the record's Discovery shape, as a tool error: a live session put the camera fields at the root of a shot and received ok: false with zod's issue dump under "Fix the error in the source".
  • kiln_assets get and restore without revisionId read the asset's newest revision (the one no later revision names as its parent), and kiln_material get without revisionId reads the material's only revision, naming the revisions when there are several; both match kiln_project get. Three live sessions called get with the id alone and were refused.
  • Breaking: kiln_inspect listParts returns names and paths; placement: true adds the world transform, mirroring and bounds in pages of 50. The floating-parts warning names the first six parts with their fix and the next 24 by name, and a render result carries the export-time structural warnings once (a second pass over the re-imported scene repeated every floating part under its primitive name).
  • Breaking: kiln_review list pages (offset, limit up to 100, default 20) and returns short records (operationId, revision, tool, status, timestamps, programRef, pinned, the artifact hash, capture count and fidelity) with total and nextOffset; get and pin return an operation bounded to 20,000 characters, naming the retained file for what was left out. kiln_discover detail pages stop at 15,000 characters and name the ids not returned in omittedIds.
  • Breaking: a result with ok: false is an MCP error (isError: true). Every error names the next call and no absolute local path: an invalid input is a sentence naming the fields and the shape: id to read instead of a zod issue dump; an unknown project, material, asset or review id names the list action; a renderer that is required but unavailable names KILN_RENDER, KILN_RENDER_PORT_URL and kiln_renderer reprobe; kiln_review save names the revision or status to fix; a project import refusing its own id says to pass a different --id; a shot whose subject names no node, or more than one, is answered with the shot's fix (one exact part path from the list in the error), not the source's.
  • The CLI render --json and animation --json receipts carry the compact result by default (one receipt measured 51,312 characters at full); --detail lean|compact|full selects the detail. The CLI material list prints the summaries kiln_material list returns, not every manifest (34,116 characters for five pinned materials before).
  • scripts/tier2-dogfood.mjs counts the tool steps of an Agy stream (step_update with tool_name, one per step index), so a blind Agy run's receipt no longer says unknown.
  • A saved manifest read as a resource (kiln://assets/.../manifest.json) is one line, as every tool result is; the file on disk stays pretty-printed. CLI kiln asset <id> without a revision reads the asset's newest revision, as kiln_assets get does (it refused with "requires asset ID and revision ID"), while export still names one exact revision; kiln save --help prints the save usage alone (a blind OpenCode run read 2,275 characters of the assets-and-viewer block for it, and the whole block had been 16,077 before the records trim).

Generated code

The follow-ups the owner decided on 2 October 2026 after reading the cycle's report (decisions 23 to 28 in the plan) land here, on the same branch, before it merges.

  • Breaking: generated code runs in strict mode. The evaluator prepends 'use strict' to every program and kiln_validate parses with the same directive, so a construct only strict mode refuses (with, a legacy octal literal, a duplicate parameter name) is a SYNTAX_ERROR with its line before any evaluation; an assignment to an undeclared name throws (answered as an unbound variable) instead of creating a host global; and a function declared inside a block stays in that block. The source policy allows this inside object-literal methods, getters, setters and function properties, class methods, constructors, accessors, field initializers and static blocks, and in arrows nested inside those, where it is the receiver the program built (w29's mesh batcher was an object literal whose add method read this); this at the top level or in a plain function stays UNSAFE_GLOBAL_ACCESS, as does module.
  • The generic rejection carries the engine's own advice. A program that throws without a closed cause is still answered Generated asset execution was rejected. with no message, stack or identifier from it; that sentence now continues with a fixed engine-owned paragraph saying so and naming the way to read values (kiln_inspect on a rendered program, not a thrown Error) and the way to find the line (kiln_validate). The scene session that threw an Error to print bounding boxes got the bare sentence (H30). A rejection with a cause keeps that cause's advice alone; the wire message and the adversarial isolation test's exact first sentence are unchanged.

Knowledge and setup

Standing knowledge is read whole at the start of every session and again after each compaction, so it is a budget: the generated guide is at most 5,000 characters and a SKILL.md at most 16,000 characters and 500 lines, enforced by the workspace tests and check:skills.

  • Breaking for generated workspaces: AGENTS.md carries a 4,461-character guide (10,716 before) and CLAUDE.md is the one-line import @AGENTS.md. Claude Code 2.1.287 loads AGENTS.md by default only where no CLAUDE.md exists, so the import keeps one copy of the guide in context whichever file it reads. A workspace carries one skill registry, the directory its harness reads: .claude/skills/ for Claude Code (whose binary also names .agents/skills, so the two copies registered every skill twice), .agents/skills/ for codex, hermes, agy, copilot and cursor-agent, and none for OpenCode, whose opencode.json names skills/ in skills.paths. Existing workspaces are not rewritten: kiln-init --check reports the second registry a 0.9 workspace carried as retired, --upgrade removes it when unchanged and stops on an edited copy.
  • kiln-author-asset/SKILL.md is 15,969 characters (19,030 before). Its delivery paragraph offers node kiln.mjs view to a person who is present instead of telling the agent to launch it: a headless Codex session saved its asset and then sat behind the viewer until the 30-minute cap. The author, QA and camera guidance make the compact result the way to review and name detail: "full" only as a qualified second look: the first wave pair asked full on every render and edit in both the compact and the lean arm because the skills said to pass it "for every finding". check:skills now refuses a skill sentence that names full detail without "only". engine-handoff.md lives once in kiln-qa-asset and export-profiles.md once in kiln-author-asset, each named by skill and path from the other (a skill's markdown links stay inside the skill, so a workspace that installs one skill alone resolves every link); check:skills refuses two files under skills/ with the same bytes.
  • Codex: the generated .codex/config.toml is read once $CODEX_HOME/config.toml marks the project trusted (measured on 0.160.0; the generator and START.md said Codex read no project-local config), node codex.mjs applies the same values per run so no trust entry is needed, and its env_vars forward KILN_PROJECT, so a configured project reaches the server under Codex as it does elsewhere. kiln-init --help lists all seven harnesses.
  • Antigravity: the generated .agents/mcp_config.json sets KILN_RESULT_DETAIL=lean on the server entry. Antigravity writes a result over about 4,000 characters to a file the model then reads back, and the wave's paired sessions showed lean winning both measures only there (24% fewer result characters, 8% fewer output tokens); the other harnesses' entries set nothing and keep the compact default, and a call's own detail still wins. An existing Antigravity workspace shows the entry as changed managed configuration to kiln-init --check; --upgrade refreshes it when the file is unedited.
  • Records: the plugin manifests say 0.10.0 and kiln (the Codex plugin manifest said kiln-oss), the root plugin.json no longer names a schema URL that returns 404, docs/dogfooding.md and docs/clean-room.md name OpenCode's --standalone (there is no --pure in 2.0.14), docs/harnesses.md records the measured skill directories and the Codex trust rule, and the Tier 2 driver reads the packaged manifest for the tool names it counts as workspace MCP use (its hand-kept list lacked kiln_discover, kiln_renderer, kiln_project, kiln_material and kiln_review).

0.9.0

Source and site preview for dogfooding. The v0.9 work is integrated for the Cloudflare site rollout. Package publication remains deferred to v1.0 after feedback. Individual asset review status is recorded on its page; deployment does not change it.

Kiln 0.9.0 adds optional projects, a material library and Live Review to standalone authoring, makes the calibrated review-neutral-v1 rig the default for review views, exports declared levels of detail as MSFT_lod chains, and fixes the defects authors reported while using 0.8. Standalone assets need no project. The migration notes list every change an existing author will notice; the foundation checkpoint records how projects, materials and Live Review were qualified.

Projects, materials and Live Review

  • Optional projects. kiln_project and node kiln.mjs project create, read and update immutable, versioned project records: brief, inventory, design profile, references, delivery intent and an exact material dependency lock. Updates name the expected revision and report conflicts. Work stays standalone unless an operation selects a project (--project, MCP projectId) or the host configures KILN_PROJECT; --no-project and projectId: null override that default. The collection named project remains only a save destination.
  • Material library. kiln_material and node kiln.mjs material keep immutable material revisions with creator, license, recipe, seed and source provenance. Five offline procedural presets (warm-brick, wood-grain, brushed-metal, woven-fabric, coarse-soil) each produce base colour, normal and packed metallic/roughness maps. Custom procedural drafts, normal-from-height derivation and complete payload import and export are supported. Source compiles a returned portableSpec with compilePortableMaterialSpecV2; the exact pins travel as materialDependencies or --materials.
  • Live Review. node kiln.mjs view opens the local dashboard: Library, Materials, Projects and Live Review. Live Review shows the exact retained artifacts, captures and fidelity of CLI and MCP operations, with iterations, errors, pinning, comparison and reconnection. kiln_review lists, gets and pins observed operations and saves an exact reviewed operation. KILN_WORK_ITEM optionally groups one authoring item across sessions. The Measure control records a bounded browser load and frame sample.
  • Delivery. project export --profile editable|runtime packages a project's linked saved revisions; editable packages rebuild offline from source, settings and complete material resources, and asset ... --rebuild reports artifact hash equality. The Library aggregates configured collections with collection-qualified IDs.
  • Seventeen MCP tools. The packaged stdio server lists the fourteen program tools plus kiln_project, kiln_material and kiln_review. Embeddings advertise those three only when their host services are supplied.

Review lighting and provenance

  • review-neutral-v1 is the default review rig: a calibrated white rig with Review Neutral, a Khronos PBR Neutral variant. A key-facing matte #C0362C panel reads (193,51,40) instead of (255,177,147); mean CIEDE2000 over the ColorChecker chart falls from 28.09 to 0.51. neutral-studio-v1 and gallery-studio-v1 stay selectable by explicit lighting ID, captures without one re-render after the upgrade, and composer's unsupported neutral-studio-v2 default becomes review-neutral-v1. Do not darken albedo for review lighting.
  • The CLI honours KILN_RENDER on every renderer-selecting path: an explicit --render wins, then KILN_RENDER, then auto.
  • Saved builds record the installed engine under every build-cache policy, and an absent optional peer is fingerprinted as peer-absent instead of erasing the runtime identity.

Levels of detail

  • One tier unless the brief asks. The authoring skills say so. Tiers are sibling groups named with one stem and a level token (Body_LOD0, Body_LOD1), LOD0 the full-detail tier, and each set is declared once with defineLod(levels, { screenCoverage }): one screen fraction per level, 0 to 1, strictly decreasing, where a last value of 0 never culls. createPart is unchanged. Two or more sibling tiers without a declaration, a gap, a missing LOD0 or a set declared inside another tier fail the build with the closed diagnostic LOD_SET.
  • Exported as MSFT_lod. Every GLB Kiln writes from source (the saved asset.glb, kiln_export, kiln export, render --out, both export profiles, both converters) carries each set as one chain: LOD0 stays in the scene with extensions.MSFT_lod.ids and extras.MSFT_screencoverage, the lower levels leave the scene with their subtrees and transforms, and materials are untouched. A loader without the extension draws LOD0.
  • LOD0 is the headline. Triangles and bounds count LOD0 and the parts outside every set; levelsOfDetail in render results, the integration manifest and CLI receipts lists each level's path and triangles.
  • Review views. Default sheets in kiln_render, kiln_inspect and the kiln_save preview draw LOD0. A shot whose subject is a lower level's path draws that level in LOD0's place (visibility: "isolate" shows it alone), the CPU and GPU views agree, and each chain's drawn says which level every view drew. No tool input changed.
  • Viewer. Library and Live Review show a Level control (LOD0 to the last level, LOD0 by default) and every level's triangles for a GLB with chains, imported or authored. Expand Per-part levels to choose each independent chain, such as a medium tractor body with detailed wheels. Mixed selections report the triangles actually displayed. Current and pinned Live Review artifacts have their own part controls; the current artifact's global selector still sets both views. Selecting another observation of identical bytes retains geometry statistics and updates the observation identity.
  • Revision comparison reads chains: each lower level is compared at the path it takes beside LOD0. Switch thresholds are not compared.

Authoring and review contracts

  • Part listings include world position, quaternion, scale, mirrored orientation and world bounds, including compact results.
  • Node and material userData round-trips through glTF extras: plain JSON, at most 4 KiB per object and 64 KiB per asset. kiln* keys remain engine-owned. Validation reports literal problems; builds report omitted dynamic values. Optimization keeps metadata-bearing nodes and materials instead of merging away their identities.
  • visible = false survives export as KHR_node_visibility. Headline metrics and category QA exclude hidden subtrees; hiddenNodes reports their triangle counts. Instancing and flattening preserve the flag and its ancestor scope.
  • markOpenShell(part, reason) acknowledges an intentionally unmeasurable open shell without suppressing measured overlap or other failures. Overlapping closed components use union volume; unsupported inward shells and component budgets remain unmeasured.
  • CUBICSPLINE, EASE_IN, EASE_OUT and EASE_IN_OUT tracks export standard cubic samplers with computed tangents and play consistently in review. Quaternion loop closure treats q and -q as the same rotation.
  • Source exports index unindexed primitives by welding exact complete vertices. indexPolicy: 'asBuilt' (local host: KILN_INDEX_POLICY=asBuilt) retains helper buffers and requires optimization off. Render results and CLI receipts report the index pass's accessor payload bytes before/after, separately from GLB file size.
  • Sweep and loft helpers observe tight curvature and intersecting consecutive rings with station evidence. The bounded local check replaces unconditional unchecked warnings; budget-limited checks remain explicitly partial. Distant segments are outside this check.
  • kiln.capture.v2 adds shot-level hide with exact paths or unique names. Version 1 and legacy captures remain valid. CPU and GPU derivatives apply the same hide list; post-loop CPU captures resolve subjects from the exported hierarchy.
  • Instanced capture derivatives and canonical bounds retain every instance transform. Overlap QA excludes alternate levels only within the same LOD chain, and category diagnostic sheets show the default LOD0 scene. Render-service startup tolerates a concurrent winner's bounded warmup; completed captures verify the service instance.

Fixes from author reports

  • Smaller results. MCP kiln_render and kiln_screenshot_animation are compact by default; detail: "full" returns every finding and rule. On the carousel example a render result falls from 34,904 to 7,706 characters. kiln_view_interior, kiln_inspect and kiln_edit are compact too; the CLI, retained artifacts and Live Review keep complete reports.
  • Sizes and files. Animation composites take a frame size of 128 to 1024 px (default 256). Versioned capture shots go up to 2048 px. --capture with output: "separate" writes <stem>.shot-01.png and onward.
  • Animation. createClip(name, duration, tracks, { loop }) records loop intent, exported as the animation extra kilnLoopIntent and checked by review (LOOP_NOT_CLOSED). GLBs no longer duplicate every clip as the kilnReviewClipsV1 scene extra.
  • Views. Saved previews drawn from the persisted GLB record exactArtifact: true. Isolated capture shots send the GPU only the subject. CPU views draw translucent surfaces after opaque ones, farthest first, so glass shows what is behind it. An explicit perspective camera without near sets it from the nearest geometry.
  • Geometry and export. extrudeProfile adds no side rings unless divisions asks (16 by default when twisted). sweepProfile keeps hard corners (creaseAngle 60) and can cap one end. Emissive intensity survives export, above 1 through KHR_materials_emissive_strength. An imported GLB's MSFT_lod chains survive import, save, optimisation and export.
  • Diagnostics. A build that throws names a closed cause with advice and a Source check:; kiln_validate reports TEMPORAL_DEAD_ZONE, MATERIAL_RECIPE_OVERRIDE and MATERIAL_RECIPE_ID. Overlap QA skips LOD alternates, tests the likeliest pairs first and groups unmeasurable parts; connectivity leaves out LOD1+ parts. Repeated helper notes appear once with a mesh count. The instanceability grade says it is informational, the blend-area budget names its largest materials, and kiln_inspect evaluates without optimisation.
  • Errors that name candidates. Ambiguous and missing subjects, unknown camera keys (fovDeg for fov) and missing or shared surfacePairs names list what would have matched. surfacePairs take exact paths or unambiguous node names, as measure does. Animation measureParts entries carry each node's world origin.
  • Setup and CLI. A workspace's kiln.mjs re-executes under the Node recorded at setup, so CLI exports equal kiln_save bytes. .kiln/workspace.json names the bundle buildIdentity, apart from the installed runtimeIdentity. The viewer accepts localhost and [::1]; Git Bash collection roots are refused on Windows. kiln edit and kiln source accept --json, kiln service start joins or starts the shared renderer, and a render URL naming the shared local socket takes the local route.

Fixes from the 0.9 dogfood runs

Three blind setup-and-author runs on the packaged build, two in OpenCode and one in Agy, found these before release.

  • kiln_edit results lead with programRef and parentRef and carry a compact render; kiln_render({ programRef, detail: "full" }) returns the complete report.
  • Discovery. ids take a recipe's bare slug (material-wood-v1) as well as recipe:material-wood-v1, and a material recipe's summary names its materialRecipe("kiln.material.wood.v1") call. Reviewed aliases let bench, table and cast iron find the joined-frame recipe, arrayLinear and the painted-metal material.
  • One --json rule. render, source, export, discover, inspect, animation and service status/reprobe print a receipt; commands that print JSON already accept the flag; generate, view, collections add and service start/stop refuse it and name the commands that take it. export --json names each file with its bytes and sha256.
  • Exports never replace a file. export and source --out fail and name the existing file; render --out still replaces its own working output.
  • Setup. kiln discover --capabilities reports the collections and source storage the MCP server has, and kiln-init creates the .kiln/programs store it configures.
  • Guidance. The OpenCode configuration check, npm 11's install-scripts warning for webgpu, the part rotation convention and which way an object faces, searching with kiln_discover rather than a harness's own search, observe findings on intended joins, suffixed names for repeated sub-assemblies, a user-level kiln server beside kiln_workspace, and where agy's --print prompt goes.

Output that changes on upgrade

Review colours under the new rig (assets darkened for the old rig look too dark); untwisted extrudeProfile triangle counts; sweepProfile shading of triangular, square and pentagonal profiles (pass creaseAngle: 180 for the old smooth look); GLB bytes of emissive and animated assets; images from explicit perspective cameras without near; CPU images through glass; GPU isolated shots; MCP result size and shape (detail: "full" restores the complete report), including kiln_edit, which leads with its refs; the wording of refused exports; Discovery ranking for bench, table and cast iron. A program with two or more sibling LOD<n> tiers fails with LOD_SET until it declares them with defineLod or keeps one tier; once declared, its GLB bytes, headline triangles and bounds, and default sheets (LOD0 only) change.

0.8.0 (source update)

The 0.8.0 source update exposes Original GLB and Runtime GLB downloads in the local viewer and public gallery, with companion runtime metadata and unchanged canonical files. The public viewer adds native animation selection and pause/play controls. Gallery build scripts use the current evaluator API. Site setup text and historical-example labels match the upgraded CLI/MCP workflow.

External CLI/MCP authoring skills and native Strands workflow instructions are separate. Optional native references expose only explicitly selected technical files, with no workspace setup, CLI command or delivery instructions.

  • One asset workflow across CLI and MCP. Kiln Discovery replaces kiln_list_primitives; search ordinary modeling language, browse operations, assemblies and optional recipes, then fetch exact contracts. No search model, GPU, API key or category selection is required. Matching now normalizes Unicode identifiers, retains term/field evidence, labels related and partial results, and limits typo expansion to missing vocabulary.
  • Explicit migration instead of hidden legacy fallbacks. Retired Discovery selectors, ambiguous helper aliases, category-driven execution and the old evaluator/native interfaces fail with migration advice. See the migration guide before updating an integration.
  • Geometry and assembly contracts are sharper. The unification pass repairs scale-sensitive geometry diagnostics, sweeps, CSG precision/attributes, UV ownership and assembly reuse. Requirements and QA report unsupported obligations as incomplete; successful generation does not certify an asset's physical fit.
  • Better evidence during review. Animation review reports endpoint continuity separately from loop intent and velocity smoothness. Rendered edits automatically compare exported static data and animation channels; source-only edits explicitly leave preservation unassessed. Focused inspection provides paged differences, subtree summaries and surface measurements.
  • A shared renderer with explicit fidelity. Compatible clients share a managed service with an idle lifetime; the starting session's exit does not kill other clients' work. Incompatible listeners are reported without replacement. The optional renderer ships inside Kiln; local startup, remote routes, cancellation, admission limits and in-session reprobe share the documented contracts. Material fidelity is reported for each view and CPU views remain geometry-only evidence.
  • Strands is optional. Its native workflow uses the shared program-reference tools, unified rendering and an explicit kiln_finish terminal. Native context stays outside the shared CLI/MCP skills; SDK/provider dependencies are optional.
  • Consumer requirements are separate from maintainer pins. CLI/MCP accept Node 20.15.0+ on the 20.x line or 22.2.0+; native Strands requires 22.2.0+. Installed commands do not require Bun. Read-only workspace checks respect an existing installed interpreter; setup canonicalizes parent directory aliases so macOS temporary workspaces remain current after Node resolves their paths. Repair/upgrade remains explicit. OpenCode setup guidance reflects its current CLI, and Cline's affected image path has a documented workaround.

This source update does not publish a new installable package. Qualification and remaining limits are recorded in the progress checkpoint. The development entries below retain earlier changes and may describe intermediate interfaces superseded by this version; use the current tool and migration guides.

Test suite holds under a loaded runner

  • The test scripts and CI set a 20 s per-test budget instead of Bun's 5 s default. Tests that take under a second locally (a cold CLI spawn, the first sharp decode in a file) had timed out at 5 s on the Windows runner and passed on re-run; a real hang still fails, twenty seconds later.
  • The tier-2 driver's process-group test no longer races node start-up. It stopped the run 50 ms after spawn, so on a loaded runner the child died before it had spawned its descendant and the orphan spawned afterwards survived. The test now waits for the child to announce its descendant before interrupting the group, and a separate test proves the deadline reports itself. Temp directories that a just-killed process tree still holds are removed with retries instead of failing the run with EBUSY.

Neutral view backdrop, and a named backdrop per capture

  • Every contact sheet is now painted on the neutral studio grey #aab1bc instead of near-black #1a1a1a. The old value was pinned in PR #13 for CPU/GPU parity and never revisited; a dark asset on it lost the silhouette, tail and ground contact the render tool asks the model to check. The new default was chosen by measuring silhouette-edge contrast over the 86 examples plus a near-black test asset on the CPU rasterizer: near-black left 39.7% of edge pixels under a 1.5:1 contrast ratio, the studio grey 12.8%. It is also the GPU studio preset's background, so a CPU fallback sheet and a GPU sheet of the same request now share one colour on every path, including exact-camera captures, which used to come back grey from the GPU and near-black from the CPU fallback.
  • capture.backdrop accepts neutral, dark or light on kiln_render, kiln_edit and kiln_view_interior. Free colours are deliberately not accepted: comparability across runs assumes two sheets of one GLB differ only because the asset does. The chosen id is part of both capture-cache keys and is echoed as capture.backdrop in every render result. The render service accepts the same backdrop field in both modes from a mirrored table that the engine suite asserts against. The CLI takes it inside a --capture recipe or as --backdrop <id>, which merges into the same capture object and overrides the recipe's own value, so one shared recipe can be re-run on another backdrop without editing it.
  • The GPU backdrop is pixel-exact. The service clears the scene background into its HDR framebuffer and tone-maps it with the asset, so the neutral #aab1bc used to read back as (203, 207, 213) while the CPU rasterizer painted (170, 177, 188). The service now sets the backdrop as the linear colour that comes out of the output pass as exactly the table's bytes, through an analytic inverse of three's ACES filmic curve and sRGB transfer in render-service/src/display-transform.mjs, verified against pixels read back from a dawn-d3d12 device. A GPU sheet and a CPU sheet of the same request now agree on the backdrop pixel for pixel. Compositing after the pass was rejected because multisampled edges would have kept a one-pixel fringe.
  • The render service's free-hex background field is gone, in both modes, along with the presets' own background colour: the named backdrop table is the only source, so nothing can paint a colour the engine would not. background in a request is a 400 naming backdrop.
  • kiln render --render gpu no longer hangs after starting the renderer itself. The host kills a service it started from an exit hook, which suits the long-lived MCP server, but a one-shot command never reached exit: the child's piped stderr kept the loop alive, so the CLI finished its render and then sat forever with a GPU process orphaned behind it. The CLI now stops a service it started when the command settles and leaves one it merely found alone. For a batch of CLI renders, start the service once by hand so each command joins it.
  • Occupancy coverage takes the backdrop it should measure against. Sheets cached from earlier versions are keyed by the old request shape and are simply re-rendered once.
  • kiln_view_interior echoes capture too, so every image result now says which backdrop its silhouettes sat on. The guidance in the schema and skills states one rule for every asset colour: switch only after a sheet shows a part merging with the grey, to light when that part is darker than the grey and to dark when it is lighter.
  • kiln_save takes the same backdrop for the preview it stores, as does the CLI's kiln save --backdrop <id>, and the manifest records the one used as preview.backdrop. A preview used to be painted on the default whatever sheet had been accepted, so a grey asset reviewed on dark was stored merging with the grey it had just been moved off.

Experimental community exporter and engine handoff

  • The established GLB exporter remains the default. Builds containing this integration also provide an experimental Three.js exporter for explicit comparison; no separate repository is needed. See the Blender/Unity handoff guide for scoped CLI/MCP activation, restoration of the default, tested import routes and known limitations.
  • Authoring and QA skills include the handoff guide so agents can discover the option when destination requirements call for it. Blender/Unity does not automatically select it.
  • Expanded export, GPU, deformation and clean-package checks are documented in the qualification report. The candidate is not yet qualified to replace the default for all supported workflows.

Saved-asset export profiles

  • Keep byte-preserving editable exports as the default. Opt-in runtime exports move Kiln's duplicated scene review clips to a versioned, hash-linked sidecar, preserving standalone native glTF playback and the canonical saved revision. Available through the CLI, MCP and @kiln/engine/asset-export library entry. Usage, provenance contract and limits.

0.7.1: Preserve CLI outputs on failed writes

  • GLB, preview PNG, and generated source replacements are written to unique sibling temporary files and renamed only after the write closes successfully. A failed write or rename leaves the previous output intact. Source and asset exports continue to refuse overwrites. Concurrent replacements can fail with a sharing violation on Windows; the CLI reports the error without deleting the destination.

The setup defects, and a bind that was never ours to choose — 2026-09-13

  • The render service binds loopback now, and widening it costs a token. HOST unset used to bind every interface, and the documented manual start -- npm start, "nothing else to configure" -- did exactly that with RENDER_SERVICE_TOKEN unset and only a warning. What sat behind it is a POST /render that accepts a 48 MB GLB, parses it with three.js and hands the buffers to Dawn and a native Vulkan driver, on a queue that renders one frame at a time -- so a single caller can hold the GPU indefinitely, and an untrusted binary-asset parser sits in front of a kernel driver. That is the shape of CVE-2026-7482, where a crafted model file drove a heap overread in a local inference server that operators had put on the public internet by the hundred thousand. Their default was loopback; ours was not.

    The fix is a rule rather than a flag: the bind address decides whether auth is required. Loopback is free, because the operating system is the boundary. Anything wider requires a token and otherwise refuses to boot -- the same choice this file already makes for a software adapter, where a driver regression yields a service that will not start rather than one that silently does the wrong thing. RENDER_SERVICE_ALLOW_UNAUTHENTICATED=1 is the explicit waiver, spelled so an operator has to type the word. The container image sets HOST=0.0.0.0 itself, because a container binding loopback is unreachable through -p. Verified on hardware: a LAN address is refused by default, an exposed bind with no token exits 1 before the GPU is even acquired, and an exposed bind with one serves while returning 401 without the header.

  • Two generated workspaces could not work, and both for the same reason. A codex workspace wrote .codex/config.toml that codex never reads -- every source it consults is $CODEX_HOME-rooted -- so a harness the README lists reached no Kiln tools at all. A hermes workspace redirected HERMES_HOME to get its MCP servers and skills read, and that one variable resolves the config path and the credential path, so the run died before its first model call. Both now configure per invocation through generated launchers: codex via -c overrides, hermes via --in plus the program store riding the environment into the MCP child. Neither writes outside the workspace and neither touches authentication. The rule they establish: a workspace may add configuration to an invocation, but it must not replace the home that holds credentials.

    The hermes diagnosis was wrong before it was right. There is no provider key to inherit -- ~/.hermes/.env holds tool toggles and every API key reads "not set", because the provider is a subscription OAuth. What the redirect actually lost was model.default and model.provider. Two more things fell out of measuring rather than assuming: --skills takes skill names, not a path, and the documented --ignore-rules was suppressing the workspace's own AGENTS.md.

  • A launcher test, because that is why nobody saw either one. harness-smoke.mjs invokes each CLI directly and never touches the generated launcher, so both defects passed every check. The new test asserts the launcher's shape -- that it registers per invocation, parses under the interpreter that will run it, and never names the home that holds credentials.

  • arrayLinear was making copies that were not copies. It read only source.position, so every instance stood up straight however the source was laid down -- while arrayRadial next door set a rotation on every copy. Two dispatched models hit this independently. Copies now carry the source's rotation and scale. Separately, arrayRadial could only ever orbit the parent's origin, which is what its docstring says and not something a caller could work around; it takes an optional center now. These helpers had no unit tests at all, which is how a disagreement between two neighbours survived. This changes exported geometry for a program that arrays a rotated or scaled source.

  • The helper overview stopped making models guess. A bare kiln_list_primitives returned names grouped by category and nothing else, and models reliably guessed the JS-conventional createPart(parent, {...}). The overview now carries the exact signatures of the two helpers every program calls, read from the catalog so it cannot drift from what a detail request returns.

  • --render gpu starts the renderer it needs. It used to throw when nothing was listening even though the installation ships a service that could start, because only the MCP server ever asked for that. gpu means "I asked for a guarantee and would rather know than be quietly downgraded"; answering it with a technicality was the defect. auto deliberately still does not spawn -- a one-shot sheet should not pay a GPU boot. Fixing it also removed a dead throw and a real crash: the spawn branch read options.serviceDir on a path that can now be reached with no options at all.

  • Which Kiln answered is now a question a tool can settle. A server named kiln may be a different installation, and two live examples on one development machine proved it -- an extracted 0.6.0 package registered in ~/.cursor/mcp.json beside a 0.7.0 checkout, and a stale cached tool namespace. Both were local leftovers rather than repo defects, but the workspace guide has always said "do not substitute it silently" with nothing behind it. kiln_list_primitives {capabilities:true} now reports engine.version and engine.installUrl, and the guide says to compare them against the workspace manifest.

  • zod 4.6.4 and webgpu 0.6.1. The latter was gated on a GPU smoke that has now passed twice: dawn-vulkan on a GTX 1660 Ti boots and renders through the engine on 0.6.1.

Seven harnesses, one version, and the defects only a plain prompt could find — 2026-09-13

  • Two new harness adapters: copilot and cursor-agent, bringing the dispatch table to seven. Both were verified end to end rather than written from documentation, and both needed a flag that is not obvious: Copilot's --allow-all-tools is required for non-interactive mode by its own help, and Cursor needs three separate grants -- --force for tool calls, --approve-mcps for the server, --trust for the workspace -- because an unapproved MCP server is gated independently of tool permission.
  • create-workspace.mjs learned both harnesses. Copilot reads a workspace .mcp.json, the same filename Claude Code reads, and not the same contents: its own copilot mcp add writes type: "local" plus a tool filter where Claude writes type: "stdio" and none. The generated config is the spelling Copilot produced for itself. Cursor gets .cursor/mcp.json.
  • Tool names are not portable, and a prompt that names one is a harness dependency. Copilot namespaces every MCP tool as <server>-<tool>, so an agent asked for kiln_list_primitives found nothing by that literal name and correctly reported the tools missing -- while copilot -p listing its own tools showed all thirteen as kiln_workspace-kiln_*. harness-smoke.mjs now says the prefix may exist.
  • The smoke brief was measuring the wrong thing. It told the agent to call kiln_list_primitives and then "nothing else". A bare call returns a compact overview where createPart is one name among eighteen, and the overview's own first line says to ask again with {names:[...]} for signatures. Two of five harnesses guessed the JS-conventional createPart(parent, {name, geo, material}) and were rejected at build time; three wrote the real positional form. Asking for the signatures made both failures pass with the same models. The engine's opaque rejection is not at fault: nothing from a sandboxed exception may cross that boundary, by design.
  • One version, everywhere a client can read it. package.json moved to 0.7.0 and four other declarations did not: plugin.json, .claude-plugin/plugin.json, .codex-plugin/plugin.json and MCP_SERVER_VERSION. Every MCP client reported kiln v0.6.0 against a 0.7.0 engine, which is worth nothing to a bug reporter citing a version. A test now asserts all five agree, so the next bump cannot miss them.
  • Gemini CLI is excluded, not missing. Google switched it off for individual tiers on 18 June 2026 in favour of Antigravity CLI; it now fails at startup with IneligibleTierError. agy is the replacement and already had an adapter.
  • agy print mode does not run unattended by itself. Its log says what happens instead: Print mode: soft-denying tool confirmation "CallMcpTool" at step 10, then exit 0 with no program. It needs --dangerously-skip-permissions.
  • Claude Code's allow-list needed the third server spelling. mcp__kiln_workspace is what a generated workspace and a user-level registration both use; with only mcp__kiln and mcp__plugin_kiln_kiln listed, a run stopped and asked for kiln_list_primitives by name.
  • New: docs/harnesses.md, the per-harness install, upgrade, headless-flag and MCP-config reference. docs/dogfooding.md now opens with the method -- three tiers, and why a scripted brief is a wiring probe rather than a dogfood.
  • ROADMAP.md carries a stabilisation queue for the first time. The two items at the top are setup defects rather than engine defects, and both sit on a path the README documents: a generated codex workspace cannot see Kiln at all (codex has no project-local config mechanism -- every source is $CODEX_HOME-rooted), and a generated hermes workspace cannot reach a model (its launcher redirects HERMES_HOME, and the provider lives in the real home). The codex fix is verified but not applied. The rule it establishes: a workspace may add configuration to an invocation, and must not replace the home holding credentials.

Five tools were unusable in VS Code, and had been since 0.7.0's camera work — 2026-09-12

  • kiln_render, kiln_edit, kiln_inspect, kiln_view_interior and kiln_screenshot_animation all carried a z.tuple camera vector. Zod renders that as JSON Schema 2020-12: prefixItems plus items: false, meaning "nothing beyond the listed positions". VS Code's tool validator tests items for truthiness, so false reads to it as an array with no items and it refuses to register the tool: "Failed to validate tool mcp_kiln_kiln_edit: tool parameters array type must have items." That is the whole authoring loop — no render, no edit.
  • Not a regression, and not broken anywhere else. The tuple arrived with the camera capture work in b2eff76 (2026-09-05) and never changed. Claude Code, opencode 1.18.30 and the Copilot CLI 1.0.83 all register 13 of 13; only VS Code Copilot Chat rejects any. The two Copilot surfaces disagree with each other.
  • Kiln was the conformant party. SEP-1613 is Final: 2020-12 is the default dialect and "Clients MUST support at least JSON Schema 2020-12". The fix is still worth taking, because tuples are the one construct the two dialects spell irreconcilably — draft-07 uses items: [...], 2020-12 uses prefixItems + items: false — while a bounded uniform array (items: {type: number} with minItems/maxItems) is valid and identical in both. Choosing it removes a class of client incompatibility rather than patching one client.
  • It also made the surface smaller: the tools/list frame went 33,937 B to 32,081 B, about 464 tokens saved once per session for every harness, and docs/tools.md lost 288 lines of tuple boilerplate.
  • The tuple TypeScript type is preserved by a static assertion, so nothing downstream needed a cast. It is deliberately not a zod .transform: that reads as equivalent and breaks every non-MCP harness, because the Strands skin converts with io: 'output' where zod refuses — "Transforms cannot be represented in JSON Schema" — while the MCP SDK converts with io: 'input' and never sees it. Only the in-process parity test caught that.
  • Confirmed in the client that rejected them: before the fix VS Code logged the error 26 seconds after our server connected; after it, all 13 mcp_kiln_* tools list, kiln_edit included. Copilot Chat logs only validation failures and never successes, so this rests on the before/after, not on a passing log line.
  • Gated two ways: no array in any advertised schema may have a falsy items, and a camera vector must still reject two, four, and non-numeric members at runtime. The second gate exists because the first one alone would pass on a schema that had quietly become an unbounded number list.

Asset links now say how big they are and who they are for — 2026-09-12

  • A user reported "massive token usage" from VS Code Copilot, attributing it to resource_link mishandling. Measuring first: kiln_save/kiln_export put 941 B of URIs on the wire and no file bytes, and a JSON-RPC tap showed the Copilot CLI never calls resources/read at all. So the stated mechanism does not exist in our responses — but the report was standing next to something real.
  • Kiln emitted only four of ResourceLink's fields. The spec also carries size and annotations.audience, which are exactly how a server tells a client "this artifact is for the human to download, not for the model to read". Emitting neither left every client guessing from a MIME type, including the ones that guess "inline everything". Both are now set, with priority: asset.glb and preview.png are ['user'] because the model already receives rendered views as image blocks and geometry as metrics; source.kiln.js is addressed to both.
  • editable.zip is no longer advertised. It is a bundle of the files listed beside it, so a client resolving every link paid for the same bytes twice — and it was the largest entry while being the only derived one. It stays readable at its URI (which is what the widget's download button uses) and stays in downloadUrls.
  • Net wire cost went 941 B → 1,017 B. This is not a size win and is not claimed as one: it trades 76 bytes for every client being able to decide correctly. The size is compared in the test against the bytes resources/read actually returns for that URI, because a declared size a client cannot trust is worse than no size at all.

Post-release polish: the install guide had gone stale — 2026-09-12

  • docs/install.md told readers to use a checkout "until an updated package is released", naming kiln-engine-0.6.0.tgz, an eight-tool surface, and five tools the package lacked. All three were true when written and none survived v0.7.0. Verified by driving the published tarball's MCP server over stdio: it advertises 13 tools, including all five that section said were missing.
  • Rewritten to link the latest release and the generated tool reference instead of restating either. The section was fragile because it duplicated facts that live in gated files — docs/tools.md is already checked against the registry, so it does not need repeating in prose that nothing checks.
  • A test now enforces the rule that follows: install guidance may not hard-code a release tarball version, and must point at releases/latest and tools.md. Scoped to the docs that tell a reader how to obtain the package; CONTRIBUTING.md keeps its kiln-engine-0.6.0.tgz because there the filename is the evidence for why the version policy exists. Both failure modes verified — a pinned version, and a link that stops pointing at the latest release.
  • docs/migration.md said "keeps the package version at 0.6.0 until release review", which stopped being true at the tag.
  • AGENTS.md now explains the two tool surfaces, which was a real comprehension trap: registry.ts holds the in-process loop's four tools and the MCP surface's thirteen, and "both skins consume it" read as one shared list. The one differing name, kiln_screenshot, is merged rather than missing — in-process, kiln_render returns metrics only and kiln_screenshot carries the six-view grid, so a cheap structural check need not pay for an image; on MCP, kiln_render is unified and returns metrics, part paths and images together, so a separate screenshot tool would be a second way to ask for the same grid.
  • Also measured while checking the new-developer path, in a fresh clone: ~31 seconds from nothing to a rendered GLB (4s clone, 26s install, 1s render), and the documented render-service step works verbatim — npm --prefix render-service ci --ignore-scripts in 2s, then 37 tests pass.

The Windows failure was a real bug in the alias lock — 2026-09-12

  • rejects lost updates from eight independent processes went red once on a Windows runner. The first read of it here was wrong, and the number that refutes it was in the log all along: the test failed in 123 ms, while both hang guards are 10 and 15 seconds away. Nothing was slow. A worker died, fast.
  • The only way compareAndSet does that is the throw error beside its lock, reached whenever mkdir reports contention with a code other than EEXIST. Windows has exactly that case: directory deletion is not synchronous, so a directory whose last handle has not closed sits in pending-delete, where mkdir on that name answers EPERM or EACCES. Every release runs rmdir in a finally, so with eight processes contending, one landing in that window is ordinary contention — and it was rethrown.
  • isLockContention now recognises those two codes on Windows only. Widening it to every platform would be the over-fix: on POSIX, EPERM/EACCES from mkdir means the parent directory is not writable, and swallowing that would report a permission fault as "busy". Both mistakes are pinned by tests — reverting to EEXIST-only fails the Windows case, over-widening fails the POSIX guard.
  • Lock release stopped being able to decide the call's outcome. rmdir has no force, and on Windows it can fail while a scanner holds the directory — which inside a finally would replace a precise Alias conflict with an unrelated errno, or turn a successful write into a failure. Cleanup failures are now swallowed, and a lingering lock degrades to "busy" rather than corrupting anything.
  • Asserted on the decision rather than through a real Windows filesystem, so a Linux host checks every branch and the platform is a parameter. The worker timings added alongside are what made the failure legible in the first place, and they stay: one FAILED beside seven fast children points at the code, where all eight slow points at the host.

--receipt was relative to the wrong directory — 2026-09-12

  • scripts/verify-package-receipt.mjs resolved --receipt against --root rather than the working directory. Those are the same directory in the CI step, which is why the original passed its own tests and every CI run — and different everywhere else.
  • Found by using it. Assembling the release from downloaded artifacts puts the receipts in a staging directory while root is the repository, so every path silently became <repo>/linux-package.json and all four verifications failed with ENOENT. The assembly refused to publish, which is what it is for.
  • A path a person types on a command line belongs to where they typed it. root now locates package.json and nothing else.
  • The test that passed while the bug existed is the finding worth keeping: its fixture had root and the receipt in the same temp directory, mirroring the CI step, so it could not tell the two rules apart. It now addresses the receipt explicitly and a second case pins the resolution rule with root and the receipt in different directories. Both fail if the old behaviour is reintroduced — the doubled path in the error is its signature.

webgpu 0.6.1 is held out of 0.7.0 — 2026-09-12

  • The bump was slated for this release and then held, because reading what is in it changed the decision. [email protected] was published the same day, and v0.6.0...v0.6.1 bumps the third_party/dawn submodule to "latest" alongside a real fix — unmapping a device's buffers when the device is destroyed, with 114 lines of new tests upstream.
  • The fix is worth having: render-service creates and destroys a device per capture, and buffer unmapping on destroy is the readback path. That is not what holds it.
  • What holds it is that nothing here can exercise it. CI installs render-service with --ignore-scripts so the 37 pure tests run without a device — which means they prove the package resolves and nothing more. render-service/src/, package.json and package-lock.json all ship inside the engine tarball, so an untested native bump would be in the release artifact, attested by four receipts that never touched a GPU.
  • So 0.7.0 ships from what CI has fully proven, and this is the first change after it, gated on the GPU smoke that already holds Phase 4 §7 and the two conformance runs.
  • Noted while looking, not changed: render-service/package.json has an allowScripts field keyed {"[email protected]": true} that nothing reads — not Bun's trustedDependencies, no @lavamoat/allow-scripts in the tree, and the README says plain npm install, which runs scripts anyway. It looks like a control over native build execution and is not one. Left for a deliberate decision rather than deleted.

All four platform receipts come from CI now — 2026-09-12

  • The 2026-09-05 release attached linux-package.json and windows-package.json, but test:package ran only in the macOS job — so two of the four platforms a release attests to had no reproducible source and were produced by hand. linux-package and windows-package jobs close that; CI now emits the tarball and all four receipts from one run.
  • The receipt check left the workflow. It was a ~400-character node -e one-liner inside the macOS job, which is tolerable at one platform and not at four: the expected platform differs per job, so copying it is three chances to assert darwin on a Linux runner and have the receipt pass anyway. A receipt that cannot fail is not evidence. It is now scripts/verify-package-receipt.mjs, one line in each of the four jobs.
  • Extracting it bought two things beyond deduplication. Expected Node and npm versions come from engines rather than being written a second time, so check-toolchain.mjs stays the single source; and because the receipt records engineVersion, each platform receipt is now checked against package.json — so a release's receipts are tied to its version rather than merely sitting beside it.
  • --tarball overrides the path the receipt recorded, which is what makes one verifier serve both uses. In the job the receipt names a tarball sitting right there. At release-assembly time the receipts are downloaded artifacts whose absolute paths belong to a runner that no longer exists — but their tarballSha256 is exactly what must be checked against the file about to be published.
  • Verified against a real receipt rather than only fixtures: the Linux smoke was run on a Linux host first (16 checks, engineVersion 0.7.0), then that receipt was accepted, rejected when asked to assert darwin — the precise bug copying the one-liner would have caused — and rejected again after one byte was appended to the tarball, naming both hashes.
  • REQUIRED_CHECKS goes to eight, and the gate added two changes ago is what forced that edit: adding a job without deciding whether it gates a merge fails the suite. First time one of this phase's gates caught the next change instead of a past one.

0.7.0 — the version moves with what ships — 2026-09-12

  • version sat at 0.6.0 from the OSS release through 21 shipped changes, while CI named every tarball from it. Two people could hold kiln-engine-0.6.0.tgz and have materially different software — across a three.js major, a history rewrite and a dist/ re-add. It moves per shipped change now: patch for a fix, minor for changed or added capability, which is the normal case pre-1.0.
  • 0.7.0 rather than a patch. What accumulated is behaviour: three.js r186, the CommonJS removal it exposed, 128 lines of previously understated tool schema in docs/tools.md, and a shadows.type contract that now selects a filter from basic/pcf/vsm instead of naming one that no longer exists.
  • A bump has to be rebuilt, because runtimeBuildIdentity hashes the version into each entry's identity in dist/build.json — the value a build receipt cites. A test now asserts package.json and every dist/build.json entry agree.
  • Nothing caught that drift before, and this was verified rather than assumed. With the version at 0.7.0 and dist/ still recording 0.6.0, the full suite passed — 1860 tests, zero failures. mcp-bundle.test.ts rebuilds dist/mcp-server.mjs and compares bytes, but the version is read from package.json at runtime rather than inlined, so the bytes are identical and the stale record is invisible to it. Confirmed by the rebuild: dist/build.json was the only file that changed.

The documented offline gate did not run two of the repository's checks — 2026-09-12

  • bun run test is bun test src scripts, so it never reached render-service/. Its 37 tests ran only in CI, in the job 13.7 added — so a contributor editing that subsystem got no local signal at all and found out from a red pull request. check:skills was the same shape in the other direction: a step in CI's checks job that the documented gate never named.
  • The subsystem cannot fold into bun test src scripts: it is a separate npm project with its own lockfile and a native dependency. It gets bun run test:render-service instead, which needs npm --prefix render-service ci --ignore-scripts once. All 37 tests are pure — framing arithmetic, PNG readback packing, cache identity, contract and preset validation — so none needs a GPU or the Dawn build, which is the CI job's own recorded reason --ignore-scripts suffices.
  • Both are now in the gate in AGENTS.md and CONTRIBUTING.md, and a test asserts the general defect rather than the instance: every bun run command the agent guide names must exist as a script, and the two that were missing must appear in the gate block itself.
  • Reading the fenced block rather than the whole file is what makes that discriminate. The first version checked "named anywhere in AGENTS.md" and stayed green when the line was deleted from the gate — because the prose underneath mentions the same command. Verified three ways after narrowing: a guide naming a script that does not exist, the line dropped from the block, and the script removed from package.json all fail.

Three CI jobs reported and blocked nothing — 2026-09-12

  • build portable Node package and both Node package · macOS jobs run on every push and every pull request, and were required by nothing. Measured before changing anything: 24 of 24 green across the last 8 runs on main, and a pull request that broke macOS packaging would still have merged.
  • The test named every CI job blocks; none of them merely reports was green throughout, because it checked only continue-on-error — the narrower of the two ways a job can fail to block. Its own comment already described the gap it did not cover: "the other half is a GitHub setting." For three jobs that setting had simply never been made.
  • 13.4 set the precedent that a context is required only once it has reported, since a required context that never reports blocks every merge instead of guarding it. It promoted the Windows job on nine runs with seven green; these three clear that bar.
  • The test now derives every context ci.yml can produce — expanding the macOS matrix into its two legs, because GitHub requires the expanded name — and compares it against the list that has to be required. Adding a job without deciding whether it gates a merge now fails the suite. Verified three ways: a new job, a renamed job, and a dropped matrix leg each fail, naming the exact context gained or lost.
  • build the gallery is deliberately not required. pages.yml is path-filtered, so it stays silent on any pull request touching none of examples/, site/, src/, scripts/authorship.ts or README.md. Requiring it would block every such merge — the exact trap 13.4 named. The rule is now written down: unconditional workflow, required; conditional workflow, unrequired.

The documented way to convert an old clone did not work — 2026-09-12

  • The 2026-09-10 rewrite moved refs/tags/oss-2026-09-05 as well as main, and a tag is the one ref git fetch will not update on its own. So the README's remedy — git fetch origin && git reset --hard origin/main — left the old tag in place, holding every removed file reachable. Measured on the clone this was found in: .git at 228 MB where a fresh clone is 26 MB, with identical content.
  • Reproduced by running the documented commands verbatim in a throwaway copy. The two obvious next guesses are not merely ineffective, they are refused: plain git fetch --tags and even --prune-tags both report would clobber existing tag, so a reader has no route to the answer without already knowing --force.
  • The instructions now force the tag and then reclaim. Verified end to end on the real stale clone: 228 MB to 23 MB, fsck clean, HEAD and the working tree hash byte-identical before and after. The plan document already recorded that "the tag was the whole rewrite" for the push side; this is the same fact on the clone side, which is the side a reader is on.
  • scripts/reliability.test.mjs pins it, and asserts the absence of the broken form as well as the presence of the working one — the short version is what a later simplification reaches for.
  • Clone figures re-measured: 60 MB full and 49 MB with --filter=blob:none, where the README said 52 MB and 48 MB. .git grew from 18 MB to 26 MB when the runtime bundles were re-added after the rewrite; the checkout is unchanged at 34 MB. The timing claims are removed rather than restated — they are network-bound and cannot be honestly re-verified from a different link.

Skill bytes are canonical, and the SEP-2640 record is corrected — 2026-09-12

  • Re-read SEP-2640 from the spec text on its PR branch and the working group's own repository, rather than from a page about it. Three things this project had recorded were wrong.
  • The design changed, and not cosmetically. The extension defines skills/list, skills/get, and an optional resources/directory/read. skills/activate is gone, and with it the bundle, the scoped tools revealed on activation, and progressive disclosure inside the protocol. The SEP now "defines only the transport binding" and delegates the format and disclosure model to the Agent Skills specification.
  • The status heuristic was backwards. The note here said "read the labels, not the prose", after a summary twice reported the SEP as Final. The SEP document's own Status: field does read Final; the pull request's label still reads draft, and under the SEP process the document is the status of record. The note pointed at the weaker signal.
  • "Nothing to build against" is no longer true. The spec depends on nothing beyond base Resources, capability declaration rides SEP-2133, and the pinned @modelcontextprotocol/[email protected] already carries extensions in ServerCapabilitiesSchema while setRequestHandler takes any schema. Conformance tests merged 2026-09-11.
  • 7.12 still waits, for a different and checkable reason: nothing public consumes it. The TypeScript SDK's convenience wrappers PR is closed unmerged, every public host is a prototype in one contributor's forks, Claude Code's is internal and not public, and the GitHub MCP server prototype is closed. Shipping it now adds a third transport no host can call. Re-check the TypeScript SDK, not the SEP's status.
  • The re-read found one real gap. skills/list publishes a per-file digest and size over raw bytes, and this project already publishes sha256 digests of skill artifacts at /.well-known/agent-skills/index.json — but skills/** was -text in .gitattributes and carried the same accidental line-ending mix found in render-service/src: five files fully CRLF, two mixed, seven LF. It went unnoticed because the frontmatter parser is tolerant of both. Tolerant parsing is right; publishing a digest over whichever ending an editor happened to write is not.
  • Normalized to LF across skills/ and both registry copies, and check:skills now rejects CRLF in any skill file. Verified by reintroducing one — and then by git checkout restoring the pre-normalization bytes and the gate firing on that too, which is the regression path that actually happens.
  • Two pieces of the eventual work are already in place: the digest derivation extends 7.13's rather than being invented, and check:skills has enforced the SEP's name-equals-directory rule since Phase 7.

The published tool reference is correct again — 2026-09-12

  • docs/tools.md is generated from the tool registry, and docs/ is in the package's files list — so a stale reference is not an internal note being wrong, it is shipped to every install. It was stale: regenerating moved 128 lines.
  • The cause was an in-range dependency bump. zod 4.4.3 → 4.6.2 changed z.toJSONSchema to emit items: false, minItems and maxItems for fixed-length tuples, so every tuple input in the published reference understated its own schema.
  • Nothing caught it because the generator's --check mode appeared in no workflow and no test — the same shape as the render service's 37 tests running nowhere. An offline gate that runs nowhere is worth exactly as much as no gate.
  • It is a test now rather than a workflow step: the generator exports toolReferenceMarkdown() with its CLI behaviour behind a direct-entry guard, and scripts/tool-reference.test.mjs compares the published file to the registry. bun test already runs on Linux, Windows and both macOS architectures, so this needs no new job — and cannot become a job somebody forgets to add, which is the failure mode being fixed.
  • Compared whole rather than section by section: the drift that shipped was four added lines inside one nested schema, which any summary comparison would have missed. Verified by dropping a single minItems line and watching the test name the file and the command that fixes it.

Every directory that holds code is linted now — 2026-09-12

  • 14.4 left the one-off tools in scripts/ out and priced the alternative at 26 lint findings, a 1,530-line reflow, and 162 lines of coverage slack. After the ratchet got a scope the third term is zero — scripts/** is not instrumented at all — so what was left was a diff, and it is taken. 480 files where 442 were.
  • Thirty-four format findings and thirty-two real ones, over .mjs and .ts alike; the .ts files under scripts/ had never been linted either, since the pattern was src/**/*.ts.
  • Twenty-five useTemplate, seventeen of them one idiom: JSON.stringify(…) + '\n', the receipt-file shape, across eleven files. A shared helper is the obvious DRY move and is deliberately not taken — package-plugin.mjs ships in the package files list, so importing one means shipping another file for a cosmetic win.
  • Three findings were not cosmetic. Two any in the pilot evaluation host: one read as previous.config / previous?.deadline, now typed; one feeding a budget estimator through optional chains, now a declared PilotToolInput that names exactly the fields the image-cell budget depends on — documentation the estimator did not have. A loop's update step hiding in its condition in smoke-package.mjs. And a literal ESC byte in harness.mjs's ANSI stripper, invisible in every diff and editor, now \u001B.
  • Also surfaced, and deliberately left for its own change: docs/tools.md is stale and its docs:tools --check drift checker runs in no workflow and no test. The cause is the zod 4.4.3 → 4.6.2 bump — z.toJSONSchema now emits items: false, minItems and maxItems for fixed-length tuples — so the published tool reference has understated every tuple schema since. Ledger 14.8.

render-service joins the lint surface — 2026-09-12

  • It was left out because render-service/src/** is -text in .gitattributes and the formatter would rewrite the line endings. Looking at what the attribute protected turned that reason into the finding.
  • It was sweeping, not deliberate. The line arrived in the OSS release commit alongside the other -text entries, and what it froze is inconsistent: four files fully CRLF, renderer.mjs at 395 of 399 lines, three carrying a single stray CRLF line, four fully LF. One stray CRLF line in an otherwise-LF file is an editor's signature, not a decision.
  • Those bytes are genuinely hashed, so the replacement matters: fingerprintRendererInputs walks that directory into the renderer's capture identity. But -text only guarantees "whatever was committed", while the * text=auto eol=lf rule guarantees what the fingerprint needs — one line ending on every platform. The normalization is a stricter guarantee than the attribute it replaces.
  • Nothing re-validates the old digest. capture-producer.v1 fingerprints in checked-in provenance receipts record the renderer build a poster was made under; no test recomputes one. 13.6 already edited two of these files and every gate stayed green — a later build hashing differently is the point of recording it.
  • Eight files to LF, the attribute removed with the reasoning left where the next reader will ask, and the directory linted: 442 files where 416 were. Twenty-two format findings, then five real ones. One of them, useIterableCallbackReturn in presentation-presets.mjs, is the same defect 13.5 fixed in the Bradley-Terry fit — a one-expression arrow in a forEach returning a value the contract discards — sitting in production render-service code that was outside every lint gate this repo has.
  • reliability.test.mjs pins both include patterns and asserts the -text line stays gone. render-service's own 37 tests pass on the normalized sources.

The coverage ratchet has a scope now — 2026-09-12

  • The previous entry blamed 162 lines of lost coverage slack on helper scripts being measured and never executed. The number was right; the mechanism was wrong. Bun instruments only files it loads, and coveragePathIgnorePatterns already dropped **/*.test.mjs, so those tools were never in the report — there is no SF: record for dispatch-asset, upload-posters, geometry-experiments or harness.
  • Exactly four files under scripts/ were instrumented, because tests import them: evaluation/observe-shipping.mjs, build-runtime.mjs, evaluation/conditions.ts and authorship.ts. 229 lines against the engine's 45,726 — 0.5% of the denominator, and worth 0.10 points. Two of the four are dense single-expression files, so reflowing them inflated their line counts while their covered lines stayed put. That is where the 162 lines went.
  • So the finding is narrower and worse than "helper scripts dilute the ratchet": the engine's coverage contract had a repo-only formatting input. A number this repository enforces as policy could be moved by reformatting code that does not ship.
  • bunfig.toml now ignores scripts/** for coverage. Those tests still run — they are the gates — but their sources leave the denominator, so the ratchet is a statement about the shipped engine and nothing else. Re-measured on the narrowed scope: 95.39% functions, 92.59% lines.
  • Narrowing hands back 44 lines of slack no new test earned, so lines goes 92 → 92.1 to hold the 224-line margin 13.3 chose rather than pocket it. functions stays at 94, where the margin is unchanged in practice. Tightening further is a separate decision.
  • And the record carries its own scope now. measuredBaseline requires measuredOver, the gate refuses a baseline without it, and it prints it: Recorded baseline: functions 95.39%, lines 92.59% (over src/, [email protected], 2026-09-12). A percentage without its scope is as ambiguous as a threshold without a baseline — which is what made the wrong explanation above plausible enough to write down.

The repository's own gates are linted now — 2026-09-12

  • Adding a file to scripts/ and running biome check on its path printed "No files were processed." Biome's files.includes was src/, site/src/ and site/*.ts, so the directory holding this repository's gates — and which test:coverage already measures — sat outside the lint surface. The zero-warning baseline 13.5 established was zero across a subset.
  • Taken: scripts/check-*.mjs and scripts/**/*.test.mjs — the checks are now checked. 416 files where 405 were. Ten findings were behind the hole: seven format, and three real ones. A dead const in check-vision.mjs, easy to miss because the identical line two loops down is load-bearing. Two useTemplate on the JSON.stringify(…) + '\n' idiom. reliability.test.mjs asserts both include patterns, verified by dropping one and watching it fail.
  • Left, with the cost measured rather than guessed. The rest of scripts/ is one-off tools, several authored as dense single-expression lines. Taking the whole directory is 26 lint findings, a 1,530-line reflow (3,078 lines to 4,608, pure formatting), and 162 lines of coverage slack — lines fall 92.49% to 92.14% against a threshold of
    1. Measured by taking the full pass and running the gate.
  • Corrected below: the mechanism first given for that third cost was wrong, and it pointed at the wrong fix.
  • render-service/ stays out for an unrelated reason: its sources are CRLF by .gitattributes, and the formatter would rewrite the line endings.
  • One incidental finding: Biome prints at most 20 diagnostics by default, so a count read off bun run lint is a floor, not a total. The gate still fails either way.

The prompt-cache breakpoint is asserted on the wire — 2026-09-12

  • The two deferred rows in the queue were both deferred with a reason. Checking the reasons rather than inheriting them changed both answers.
  • The ai 7 family is blocked upstream, and money was never the constraint. The recorded reason was that only test:live exercises those paths and it spends money. What actually blocks it: @strands-agents/[email protected] is the latest release, declares peer @ai-sdk/provider: ^3.0.0, and types its VercelModel on LanguageModelV3, while @openrouter/ai-sdk-provider@3 requires ai@^7, which depends on @ai-sdk/provider@4. No budget moves that.
  • And typecheck would not have caught it. @ai-sdk/provider@4 still exports LanguageModelV3 beside V4, so the import keeps compiling; the break is a v4 model handed to a v3 wrapper, at runtime, on the one path no offline suite drives. There is a gate for it now: scripts/peer-ranges.test.mjs walks the installed tree and fails on a peer range the version beside it does not meet.
  • It found a mismatch that already exists. @strands-agents/sdk declares peer @anthropic-ai/sdk: ^0.109.1 — on a 0.x version that means >=0.109.1 <0.110.0 — and the last dependency refresh took 0.125.0. Fifteen minors past the declared range, moved by a routine in-range update, noticed by nothing. Kept, and listed with its reasoning in the gate's ACCEPTED table, so the next one fails while this one is a decision on the record rather than a silence.
  • The native cache breakpoint is now asserted against the bytes. The OpenRouter half already was: it drives doStream with fetch replaced and reads the outgoing JSON. The native half asserted that toCachedSystemPrompt returns [TextBlock, CachePointBlock] — the input to the transport, never its output. So the claim the design rests on, that a cache point becomes cache_control on the wire, was carried by a comment, on two dependencies that move inside their caret ranges on every refresh. Losing it bills full price for every prefix that should have been a cache read, with every offline gate green.
  • Both native transports are captured now, offline: the Anthropic client takes a fetch that records and throws, Bedrock a requestHandler that does the same. Both tests are differential — a plain string goes out with no breakpoint — so the breakpoint has one possible origin. Establishing that took an injected defect, which disproved the first draft's premise: Bedrock does not auto-inject a system cache point here, because that needs a cacheConfig and Kiln passes none. Patching the installed adapters to drop cache_control and the converse cachePoint fails exactly the new tests while every pre-existing test stays green — including the one named "the adapter emits cache_control", which never checked that it did.
  • 7.12 / SEP-2640 stays deferred, for a better reason. PR 2640 is open and still labelled draft; a page summary reported it Final for the second time and was wrong again. But the row turns on something downstream: @modelcontextprotocol/sdk publishes 1.30.0 as latest, the version already installed, so there is no TypeScript surface for skill:// resources to build against whatever the SEP does next. Check the SDK's version, not the pull request.

A preset's shadow filter now selects a filter — 2026-09-12

  • Going to compare shadow filters by eye turned up the reason there was nothing to compare: no shipped presentation preset enables shadows. neutral-studio-v1 sets shadows.enabled: false to preserve the pre-registry visual, gallery-studio-v1 is a spread of it, and every light has castsShadow: false. So r186 deleting the PCFSoft implementation is not a visible regression here, and yesterday's switch to PCFShadowMap corrected a line that never runs. Its claim to keep the log clean was overstated: the assignment sits inside if (preset.shadows.enabled), so three's deprecation warning never fired from this service either.
  • What was actually wrong is that shadows.type described a filter and selected nothing. The validator demanded the exact string pcf-soft while the renderer ignored the field and hardcoded a constant — and after r186, the one name the schema accepted was the one name that no longer exists.
  • It selects a filter now. SHADOW_FILTERS is basic, pcf, vsm — what r186 left — and the renderer maps each to its three constant. vsm is the soft option that survives, with one catch recorded where someone choosing it will read it: under VSM every shadow receiver also casts, so a ground plane starts casting too.
  • The names live in the schema that validates them and the constants live in the module that imports three, so the renderer checks at load that the map covers the list. A name the validator accepts and the map lacks would set shadowMap.type to undefined mid render — not a crash, just a quietly different image. Verified by adding pcf-soft back to the list and watching the service refuse to start.
  • The gallery is not affected either, for a different reason: neither <Canvas> in the site sets r3f's shadows prop, so renderer.shadowMap.enabled stays false there too, and the only shadowing on that surface is drei's ContactShadows — its own depth pass to a texture, which never consults shadowMap.type. Between the two paths, r186's PCFSoft removal changes nothing anyone can see in this repository.
  • render-service is in CI now, which it never was. Thirty-seven tests guarding a shipped subsystem ran on nobody's machine but a maintainer's — including, until this commit, the change above it. It is a separate npm project with a native dependency, which is presumably the reason; but the tests do not need it. All 37 are pure: framing arithmetic, PNG readback packing, cache identity, contract and preset validation, and not one acquires a device. So the job installs with --ignore-scripts, skipping the webgpu package's Dawn build. Verified against exactly that install with no binding built: 37 pass, 0 fail. The GPU smoke and the two conformance runs stay manual, because those genuinely need a device.

The lint baseline is zero, and stays zero — 2026-09-12

  • bun run lint reported 14 warnings and 11 infos and exited 0. All 25 are fixed; the tree now reports nothing. The point is not tidiness: a baseline everyone agrees to ignore is a baseline the twenty-sixth finding arrives invisible against.
  • Two of them were not style. isFinite in the render inspector is the coercing global, where Number.isFinite is not — identical on a Box3 component, taken because the next caller to pass something looser is the one the coercion silently accepts. And ids.forEach((id, i) => index.set(id, i)) in the Bradley-Terry fit returned the map from a callback whose contract discards it; the index is built from its pairs instead.
  • Three any bounds in buildSandboxGlobals carried // eslint-disable-next-line @typescript-eslint/no-explicit-any. This repository lints with Biome and has no ESLint config, so those suppressed nothing while reading as reviewed-and-accepted. Rather than translate them, the any is gone: never[] is the correct bound for "any parameter list" and unknown for "any return", with one narrow assertion where tsc resolves a call through the constraint and can only see unknown.
  • The quaternion fixture's 0.7071 is now Math.SQRT1_2 — exact, and it says which angle a quarter turn about Y actually is.
  • Warnings now fail. lint runs with --error-on-warnings, and because that flag does not reach Biome's info severity — where useTemplate and several others sit by default — the seven rules this cleanup touched carry an explicit error in biome.json. Each of the seven was verified by reintroducing its defect and confirming the gate fails and names the rule.
  • The useIterableCallbackReturn: "warn" downgrade is gone with the finding it was written around. A test asserts the seven severities and the lint script itself: a rule lowered to keep a build green is indistinguishable from a rule nobody wanted, and that has happened here before.
  • CONTRIBUTING.md says the contract plainly — the tree reports nothing, so any diagnostic a change produces belongs to that change, to fix or to suppress with a biome-ignore comment that says why.

The gates stop reporting and start blocking — 2026-09-12

  • The Windows job blocks. It landed reporting-only on purpose, because the fault it was added to rule out — a native GLib g_system_thread_free / invalid CloseHandle inside libvips/sharp under Bun's threading — was intermittent, and a required check that fails at random is worse than no check. Its whole history is now nine runs: seven green, two red, and not one recurrence. Both reds were new code from the session that added the job — a require('sharp/package.json') that sharp's exports map blocks, and a new URL('..', import.meta.url).pathname that yields /D:/a/kiln/src/ — and neither is reachable from a POSIX host. The failures were true, which is the argument for blocking rather than against it.
  • Blocking means a hang is a blocked merge rather than a slow report, so the job now has a 30-minute bound. The suite runs there in about two minutes.
  • A test asserts no CI job carries continue-on-error at job level, so this cannot be demoted by one line slipping back in. The single step-level exception is the native dependency inventory, which exists to attach libvips and GLib versions to a run if the fault ever returns and must never be why Windows reports red. Indentation is the distinction and the test reads it as such.
  • The coverage ratchet moves to 94% functions / 92% lines, from 92/91. Measured 95.27% and 92.49% on this tree, which leaves 42 functions and 224 lines of room.
  • That "42 functions" is the other half of the change: the gate now reports its margin in the unit a person can act on. A percentage says whether the gate passed; turning it into work needs LCOV totals that are not in front of whoever tripped it. Slack rounds down and a shortfall rounds up, so neither reads as more comfortable than it is.
  • The gate also refuses a threshold set above the baseline it records. That is the one mistake the coverage comparison cannot catch by itself: a threshold above anything ever measured fails in whatever change happens to run next, and reads there as that change's regression. A thresholds file with no recorded baseline is refused for the same reason — a ratchet is raised to a number somebody measured.

Dependencies current in range, and the toolchain gate gets its own test — 2026-09-12

  • In-range refresh, deliberately kept apart from the deferred majors: ai 6.0.222 → 6.0.282, openai 6.46.0 → 6.49.0, @ai-sdk/provider 3.0.14 → 3.0.16, @aws-sdk/client-bedrock-runtime 3.1083.0 → 3.1131.0, and in site/ react and react-dom 19.2.8 → 19.3.0 with their types, plus vite 8.2.2 → 8.3.0.
  • The ai 7 / @ai-sdk/provider 4 / @openrouter/ai-sdk-provider 3 family stays where it was. Only test:live exercises those paths and it spends money, and the deliberate prompt-cache transport asymmetry is exactly what a provider major breaks without a test noticing. Nothing enforces that decision in prose and nothing needs to: the caret ranges cannot resolve to a new major, so the boundary is structural.
  • The @types/three parity rule added yesterday now reads as what it always was — a rule about types, not about three. Every @types/* whose runtime package the same manifest pins must sit on that runtime's release line. That is what brought @types/react and @types/react-dom along with react 19.3: the site compiles its @react-three/fiber JSX against those types, and types a release line behind make new API invisible to tsc while removed API still typechecks.
  • check-toolchain.mjs now has a test. It had grown three times, each extension verified by injecting the defect by hand, once, at the time — the right check made in the wrong place, because nothing stopped a later edit from leaving a rule that could no longer fail. A vacuous gate is worse than no gate, since it is believed. The gate takes an optional --root, and each case stages a real copy of the repository's own files, mutates exactly one value, and asserts the gate names it: stale engine pin, prose that installs the wrong Bun, three drifting in either the site or the render service, types off their runtime's line, an Action pinned to a mutable tag, and a Pages workflow left behind. Staging the real files rather than a synthetic fixture is the point: a rule whose phrasing drifts out of step with the document it reads fails the baseline case immediately.
  • A mutation that changes nothing fails the test. A search string that no longer appears injects no defect, the gate correctly reports a clean tree, and the case goes green having checked nothing — the exact rot the file exists to prevent, so it is caught rather than trusted.

The r186 bump missed the site, and now a gate catches that — 2026-09-12

  • site/ was still on three 0.185.1 while the engine and render-service moved to 0.186.0. Substantive rather than untidy: kiln emits EXT_mesh_gpu_instancing, and r186 fixed that extension's custom instance attribute sharing in GLTFLoader, so the site was rendering the gallery with an unfixed loader for an extension the engine writes.
  • check:toolchain now asserts three is byte-identical in every manifest that pins it, and that @types/three tracks its minor. Verified by injecting three defects — the exact drift that shipped, a render-service drift, and a stale @types/three — and confirming each is caught and names the offending manifest.
  • The reason this is a gate and not a note: the same class of defect, a value that must agree across files with nothing enforcing it, had been caught in the prose that same morning by a person. Twice in one day is an argument for a check.

Finishing the CommonJS removal the r186 bump started — 2026-09-12

  • The previous entry's fix was incomplete, and looked complete. src/ops.ts moved to the ESM build, but src/__tests__/subdivide-normals.test.ts still imported the bare specifier — so the CommonJS build kept loading and kept emitting THREE_CJS_DEPRECATED, while the production import read as corrected. The whole suite now reports zero occurrences of that warning.
  • three-subdivide is pinned exactly rather than by caret. The deep path three-subdivide/build/index.module.js is legal precisely because the package declares no exports map; a minor release that added one would make the path unresolvable, and a caret range would have taken that release silently.
  • src/__tests__/three-subdivide-esm.test.ts guards the whole tree rather than one file, which is the lesson from the partial fix: it walks every .ts under src/, asserts the ESM build has no require( call, and asserts the pin is exact. Verified by injecting the bare specifier into src/ops.ts and confirming the guard fails and names the offending file, rather than by observing a pass.
  • Timing, since it reads as urgent and is not: three deprecated the CommonJS build in r186 and has not announced a removal release. Its own precedent — build/three.js deprecated at r150, removed at r160 — suggests roughly ten releases of runway. The reason to fix it now is the warning users see today, not the removal.

three.js r186, and the CommonJS load it exposed — 2026-09-11

  • three and @types/three to 0.186.0 in both the engine and render-service. The types were the blocker and they shipped; r186's three named breaking changes — Source → TextureSource, toTrianglesDrawMode() mutating in place, Object3D.dispose() needing super.dispose() — touch nothing here, checked before the bump rather than discovered by it.
  • three-subdivide was pulling three in through the deprecated CommonJS build. It has no exports map, so a bare specifier resolves to main, which is a UMD bundle doing require("three"). r186 did not create this; it made it audible, by emitting THREE_CJS_DEPRECATED on stderr — which every kiln CLI invocation would then have printed. Fixed by importing the ESM build the package already ships, three-subdivide/build/index.module.js, which has zero require( calls. [email protected] is the latest release, so there is no upstream fix to wait for, and three has announced the CJS build's removal.
  • Worth recording because it is tempting and wrong: this does not fix a dual-THREE instance hazard. src/primitives.ts documents one, and it was measured here rather than assumed — geometry from both the CJS and the ESM build satisfies instanceof THREE.BufferGeometry. The isBufferGeometry flag tests stay, because they are correct defensively regardless.
  • The GPU service was requesting a shadow filter that no longer exists. r186 removed the PCFSoftShadowMap implementation while keeping the constant; three warns and substitutes PCFShadowMap. render-service now names the filter it actually gets. Material conformance returns numbers identical in every region before and after, which is the proof the substitution was already happening.
  • Verified on hardware, not only offline: 1,831 pass / 0 fail, typecheck clean, lint at the unchanged 14/11 baseline, and material-conformance PASS on dawn-vulkan across all six channels. One number to watch — normalHalfLumaDelta moved 1.51 → 1.2 against a threshold of 1, consistent with r186's diffuse energy-conservation change. It passes with less margin than 11.5 measured, which is an argument for that row's follow-up rather than for a new threshold.

The guide was pinning a toolchain the gate rejects — 2026-09-11

  • AGENTS.md, CONTRIBUTING.md, README.md, docs/google.md and docs/install.md still named Bun 1.3.14, Node 22.23.1 and npm 12.0.1 after the bump to 1.4.2/22.23.2/12.0.2. AGENTS.md is the guide every harness reads, so the first command a new contributor ran installed a Bun that bun run check:toolchain — the next command in the same list — then rejected.
  • scripts/check-toolchain.mjs now asserts those five documents state the supported triple, and that pages.yml pins the same Bun as ci.yml. The gate had enforced package.json and ci.yml and nothing else, so both the prose and the second workflow could drift silently; pages.yml was correct today only because it was set by hand in the same change. Verified by injecting each of the three defects and confirming a non-zero exit, rather than by observing a pass.
  • Dated receipts under docs/evaluation/ are deliberately excluded from the check. They record the toolchain a run actually used, and rewriting one to match a new pin would falsify it.

Skills are fetchable by URL — 2026-09-11

  • The six skills are published at https://kilnstudio.tools/.well-known/agent-skills/index.json, per Cloudflare's Agent Skills Discovery RFC v0.2.0 — which is what OpenCode's skills.urls consumes. One skill-md entry and five archives for the skills carrying references/, each with a sha256 of the artifact's raw bytes so a client can verify what it fetched.
  • The archives are built by hand as POSIX ustar with every non-content field pinned — mode 0644, uid/gid 0, mtime 0, sorted entries — because the digest is published. Neither the system tar nor a convenience library gives that by default, and an archive whose bytes move on every build publishes a digest that is wrong the moment it is written. The test asserts those header fields directly rather than only comparing two builds, since two builds agreeing is also what a tar with a coarse clock does inside one second.
  • Verified end to end: real tar extracts the archives with SKILL.md at the root and contents byte-identical to skills/, and Vite copies the dot-directory into the published output.
  • This path carries skills and no MCP server, so a client that loads them has the workflows and none of the tools they describe. docs/install.md says so where it offers the URL.
  • Follow-up: the first deployment served a 404, and neither the build nor Pages was at fault. actions/upload-pages-artifact v5 archives with --exclude=.[^/]* unless include-hidden-files is set, so it strips every hidden path — and a well-known URI is under a dotted directory by definition. The artifact had 465 entries and not one dot-entry, while the same build locally produced all seven files. Fixed by setting the flag, verified to add exactly .well-known and nothing else.

Bun-only APIs cannot reach a Node bundle unnoticed — 2026-09-11

  • Audited the shipped bundles for the defect class behind the MCP server's import.meta.main bug. The bundles were clean of all nine patterns checked — but the audit found the identifier still live in src/experiments/geometry-acceptance.ts, which ships (files carries src/**/*.ts). Unbundled under plain node, import.meta.main is undefined, so that guard was always false and running the script with node did nothing at all, silently. The same defect as the MCP one with its sign flipped: there, bundling made the guard always true and started a server nobody asked for. Both now use isDirectEntry, which decides from process.argv[1].
  • A new guard asserts both halves — no Bun-only API in any committed bundle, and no import.meta.main deciding an entry point in shipped source. It was verified by injecting a defect into each and watching it fail, rather than trusted for passing green: the whole reason this class survived is that nothing was looking.

The GPU material check runs for the first time — 2026-09-11

  • render-service/test/material-conformance.mjs is the only automated evidence that the GPU path applies textures at all, and it had never passed. It replaces globalThis.fetch with a thrower to prove an embedded fixture never crosses a network boundary — but blob: is an in-memory object URL, and three's GLTFLoader mints one per embedded image that ImageBitmapLoader reads back through fetch. The guard blocked the only path a texture has into the renderer, so the file measured an untextured render and asserted against it: lumaSpread: 0 on the albedo checker, with the real cause printed as a loader warning nobody read. blob: is now exempt, and the guard self-checks that an https: fetch still throws.
  • Its normal-map threshold was >= 3 and had never been evaluated, because the albedo assertion above it always failed first. Recalibrated to >= 1 from measurement. The small number is the tone curve rather than a weak response: that panel sits at mean luma ~242 of 255 under the fixture's own exposure of 1.38, past the ACES shoulder. Measured 1.51 at exposure 1.38 and 2.61 at 0.9 with nothing else changed — which is also the proof that the map applies. An absent normal map reads near zero, the way the albedo checker read exactly 0.
  • All six channels now verify: albedo, normal, shared ORM, AO, emissive, alpha.

Artifact identity stops tracking the serializer's version — 2026-09-11

  • asset.generator is now a stable "Kiln". It defaulted to the serializer's own version string, so glTF-Transform v4.4.1 sat inside every artifact's bytes and therefore inside artifactHash. Taking 4.5.0 moved all 83 recorded hashes and failed the gallery build — and the entire difference between the two GLBs was that one string. Identical BIN chunk, identical accessor min/max, identical semantic digest. With the generator pinned, all 86 examples are byte-identical across 4.4.1 and 4.5.0, including the ones using palette(), which 4.5.0 changed. A dependency's version number is provenance about the tool, not identity of the asset.
  • @gltf-transform/* moves to an exact 4.5.0. Still exact, deliberately — the version-string cause is gone but other serialization changes are not impossible, and a serializer bump should stay a measured decision.
  • A poster receipt no longer asserts artifactHash. It asserts sourceHash and imageHash — this image was rendered from this source — which is what it could always honestly claim. Asserting the container's bytes claimed something glTF never promised: that rebuilding a source on another platform reproduces it byte for byte. The hash stays in the record as provenance, naming the bytes the poster was rendered from on the machine that recorded it, and the prose in all 83 records no longer calls the poster a render of "the exact downloadable GLB".
  • Within-run integrity checks are untouched and still hash bytes: the gallery index against the files built beside it, the build receipt against the index, and both demo receipts against their own run's GLBs.
  • The gallery now builds on Linux. bun run site:assets followed by site/scripts/verify-assets.mjs completes — 80 source/GLB pairs, posters, both edit-demo revisions and the geometry example. Before this it failed on the first example.
  • pages.yml now runs site/scripts's tests explicitly. Correction: this entry first said those tests had never run in any workflow. They had. bun run test is bun test src scripts, bun treats those as substring filters on paths, and site/scripts matches scripts — so both files were already in the suite CI runs. The step stays for a smaller reason: that coverage is incidental, and spelling the script bun test ./src ./scripts would drop it silently.
  • The gallery no longer builds on Windows. pages.yml is ubuntu-latest, which closes Phase 6.
  • New scripts/glb-chunk-hashes.mjs splits a GLB by chunk, and it answered the question Phase 6 opened with. Measured on 8 examples across both platforms at one commit: the JSON chunk diverges in all 8, the BIN chunk in 2 of 8, and totals move by 4, 8 and 264 bytes — digit counts changing, which a formatting difference cannot do, because ECMAScript specifies number-to-string exactly. So the divergence is the float values themselves, most likely the transcendentals, which IEEE-754 does not bit-specify. That means no canonical serialization could ever have fixed it, and narrowing the receipt was the only option that works.

The renderer starts itself, and now ships — 2026-09-11

  • The MCP server starts the GPU render service on demand. Installing it (cd render-service && npm install) is the whole setup: there is no longer a second process to start first, and nothing to restart to pick one up. The first view that needs PBR shading starts the renderer, the rest of the session reuses it, and it stops when the server does. Measured end to end on the shipped bundle with nothing listening: the first kiln_render came back material-faithful from the GPU in 5.4 s, the second in 1.7 s.
    • A service already listening is joined, not replaced, and a session that merely found one does not stop it on the way out -- so one GPU shared by a batch of dispatched agents keeps working, and the agent that finishes first cannot pull the renderer out from under the others.
    • A machine that did not install the renderer is unchanged, deliberately and at the level of the attached port rather than the rendered result: the absence of a render port is what makes an ordinary CPU view read as ordinary instead of as a degrade.
    • KILN_RENDER_PORT_URL and --render-port short-circuit all of it, so a hosted or remote GPU is still exactly one flag. KILN_RENDER_SERVICE_PORT moves the local one off 8000.
    • The CLI is deliberately not on this path: a one-shot kiln render should not pay a GPU process's startup to draw one sheet.
  • render-service/ now ships in the package. The MCP server told every model that a GPU renderer "ships as render-service/ in this installation"; that was false for anyone installing from npm, because the directory was in no files entry. Its source travels with the package now (104 KB) while its ~94 MB of native dependencies stay an explicit opt-in install.
  • webgpu 0.4.0 -> 0.6.0, smoked on hardware: 36/36 service unit tests, display conformance passed, end-to-end smoke all pass.
  • A service started for you binds loopback; one you start yourself still binds every interface, which is what a container deployment needs. HOST is now honoured either way.

Review surfaces say what they mean — 2026-09-11

  • viewFidelity.exactArtifact was a hard-coded false literal at every kiln_render site, never computed. A flag that is always false carries no information, and this one invited the opposite of the truth: a model could read it as "these bytes differ from what I would export" when the bytes are frequently identical. The value is still false -- this surface only ever renders an in-loop build -- but it now carries the reason code IN_LOOP_BUILD_NOT_PERSISTED, so the false value is readable rather than ominous.
  • kiln_screenshot_animation was reported to rotate a whole asset where the clip drives one joint. It does not. Measured on world matrices rather than pixels: a one-channel clip moves the joint's subtree through a clean 180-degree yaw while the un-animated sibling holds the origin at every phase. An image cannot tell a turret sweeping from a scene spinning, which is why the report was plausible; a regression test now stands where the doubt was.
  • arrayLinear and arrayRadial say outright that count is the total including the source, which survives as copy 0 -- so count: 8 gives eight bolts, not nine. The program contract states that kiln_screenshot_animation requires clip by name, that frameTimes is phases in 0..1 rather than seconds, and that a clip that renders frozen means a joint-name mismatch surfaced in unresolvedTracks.

Dependency refresh — 2026-09-11

  • Patch and minor bumps with no API surface change: @types/three 0.185.4, acorn 8.18.0, manifold-3d 3.5.3, sharp 0.35.4, zod 4.6.2, @anthropic-ai/sdk 0.125.0, @biomejs/biome 2.5.13, @google/genai 2.22.0, @strands-agents/sdk 1.17.0. biome.json follows Biome's own version, which the linter checks and which is what actually failed the gate; one test file picks up the new formatter's line fitting.
  • @gltf-transform/* is now pinned to exactly 4.4.1, joining three and gltf-validator. 4.5.0 changes the bytes of every exported GLB: all 83 recorded artifactHash values move, and the gallery build fails on a stale poster. A caret range on the library that serializes the artifact means the artifact's identity can change on an unrelated install, which is not a property this project can have. Taking 4.5.0 is a deliberate act with receipts re-recorded in the same pass, not a refresh.
  • three stays at 0.185.1. @types/three has no 0.186.x published, and r186 renames Source to TextureSource and makes BufferGeometryUtils.toTrianglesDrawMode() mutate in place rather than clone. Taking the runtime without the types would be a net loss.

Toolchain moved to Bun 1.4.2, and the MCP bundle stopped starting itself — 2026-09-11

  • Development toolchain pins move to Bun 1.4.2, Node 22.23.2 and npm 12.0.2. Bun 1.4 also fixes the early-exit behaviour above at its source: the pre-fix CLI, which produced empty output in 6 of 8 concurrent runs on 1.3.14, produced full output in 16 of 16 on 1.4.2. The withProcessAlive guard stays -- it holds for anyone still on 1.3.x, and nothing in the runtime contract promises otherwise. The offline suite runs about 18% faster.
  • dist/mcp-server.mjs started a stdio server when merely imported, and had done so for as long as the bundle has existed. The source guarded its entry block with import.meta.main, a Bun property that no Bun release lowers correctly for a --target=node bundle. Every lowering emits __require.main == __require.module; under Node ESM both sides are undefined, so the guard was always true. Bun 1.4 then stopped emitting the __require helper that line still references, which turned the same expression into a ReferenceError before the server could speak -- loud where it had been silent, and how this was finally caught. Both entries now decide from process.argv[1] through a shared isDirectEntry, which needs no lowering and means the same thing on both runtimes.

kiln commands no longer exit 0 in silence under Bun — 2026-09-11

  • Under Bun, a CLI command could exit 0 having written nothing at all: no output, no error, no rejection. kiln save did it reproducibly under load. The command was not failing, it was still running -- Bun does not register the in-flight work as an active resource, so the event loop went idle and the process exited before main() settled. Every entry point was exposed, the generated workspace kiln.mjs launcher included, because all of them await main() and then set process.exitCode. main now holds the process open for its own duration. Node was unaffected in practice, but the guard is runtime-agnostic.
  • Every CLI destination now creates the directories leading to it. --out and --views failed with a bare ENOENT on a missing parent, and failed after the build had run and printed a programRef -- a successful render followed by an error naming a path but not the directory as the thing to fix. Covers render --out, render --views, generate, source <ref> --out and export --out.

Usable from a bare clone by any harness; isolate honored on GPU — 2026-09-10

  • A bare clone is now usable by claude, codex, opencode, hermes and agy. The root .mcp.json pointed at ${PLUGIN_ROOT}, which only Antigravity defines, so the server failed to start with MODULE_NOT_FOUND in every other host; it now uses ${CLAUDE_PROJECT_DIR:-.}, which resolves whether or not the variable is set. CLAUDE.md imports AGENTS.md rather than duplicating it, and the kiln-setup-workspace skill is registered at .claude/skills/ and .agents/skills/ so a clone opened for an asset task is told to build a workspace instead of authoring in the engine checkout.
  • visibility: 'isolate' and the legacy isolate: true were silently ignored whenever a GPU service was attached. Both hide geometry by clearing mesh.visible; the CPU rasterizer culls on that flag, but glTF carries no per-mesh visibility, so the derivative GLB shipped the hidden meshes and the service drew them. kiln_inspect was reporting "nothing in this image occludes it" about images where everything still did. The derivative serialization now prunes hidden meshes from a copy, leaving the caller's scene untouched. The only previous test framed a single-mesh scene, where isolation cannot change the image.
  • The generated workspace guide is organised around the authoring loop rather than a flat tool list, and presents the MCP server and node kiln.mjs as equal surfaces that may be mixed, naming the two things that actually differ: where the rendered image lands, and that a CPU view is not material evidence. It also names the GPU render service, resolving the engine path through .kiln/workspace.json so --repair keeps it accurate, and asks the session to report skills and MCP servers it inherited from user-level configuration.
  • START.md printed a literal /current/kiln/ in its repair command; it now prints the recorded installation path plus how to recover if that moved.

Smaller clone; gallery images served from R2 — 2026-09-10

  • Gallery renders and launch video are no longer carried in git history. A clone costs 52 MB and 8 seconds rather than 440 MB and 79 seconds, 48 MB with --filter=blob:none, and a plugin install no longer pays for 539 MB of repository content twice. Packed history went from 226.06 MiB to 17.41 MiB.
  • The 88 gallery images moved to Cloudflare R2 byte for byte and are served from assets.kilnstudio.tools. Nothing was re-encoded: all 83 poster receipts still verify against the stored objects, and scripts/verify-posters.mjs checks that on every gallery build.
  • This rewrote history. All 177 commits survived and the tree is unchanged apart from the removed images and video, but every commit hash changed. Clones predating this cannot fast-forward; see the note in README.md. Links pinned to an old commit SHA will stop resolving; links through main are unaffected.
  • The launch video was never what the README served -- that comes from GitHub's asset CDN -- so the README is unaffected. assets/gallery/ deliberately stays in the repository, so the README grid needs no network.
  • Re-encoding the posters to shrink them was considered and rejected: image tokens scale with pixel dimensions, not file size, so it would have saved no agent context while voiding all 83 receipts.

Full record, including everything rejected and why, in docs/plans/repo-size-and-r2-migration-2026-09-10.md.

Collections and chat viewing — 2026-09-06

  • Save assets into project or personal collections with immutable revisions, hashed provenance, original source, and portable editable ZIP bundles.
  • Browse collections and imported GLBs in a local viewer with animation controls, revision inspection, and GLB/source/bundle downloads.
  • Present saved assets in supporting MCP App clients with kiln_present. ChatGPT viewing was verified; native GLB/ZIP attachment delivery remains unverified. Host-provided download links are supported.
  • Package complete skills independently or bind them to a ChatGPT connector.
  • Add a canonical-only sitemap and crawler discovery file to the project site.

See dogfood results and remaining work and indexing diagnostics. Package version remains 0.6.0; this change does not publish a new npm package or promote dogfood assets.

Public OSS snapshot — 2026-09-05

  • Short, immutable source references work across rendering, source reads, edits, CLI exports, and MCP restarts. Full hashes remain compatible.
  • Project-local setup and skills support authoring, inspection, and refinement through the CLI, MCP server, and TypeScript tools.
  • Geometry modifiers and configurable asset/part cameras extend the authoring and review workflow.
  • The redesigned site includes 62 selected assets with source downloads, GLB viewers, attribution, and recorded revision histories where available.
  • Mechanical Peacock and Deco Radio include documented maintainer repairs. Brass Tellurion and Victorian Greenhouse remain archived outside the gallery.
  • Package checks cover Windows, Linux, and hosted Apple Silicon/Intel Macs.

The snapshot retains package version 0.6.0. Earlier development notes follow; their asset counts and workflow descriptions describe those earlier revisions.

[Unreleased]

Changed

  • site/ is a project site now, not a gallery. The front page was a wall of specimens with a tally of triangles above it, which answered a question nobody arriving from a link was asking. It now opens on what Kiln is, the offline command that proves the engine works with no model and no key, the exact configuration for each of the five harnesses with the gotcha that cost time in each one, and a map of where to look in the repository; the specimens moved behind #/gallery and are reached from a strip of eight. The aggregate counts are gone -- a number is a claim about the library, and the library is the thing on the other page. Per-card model attribution stays, because that is not a statistic. REPO and asset() moved out of App.tsx into a leaf module: once App imported a page that read one at module scope the cycle turned into a blank screen at first paint, and a module that imports nothing cannot be in a cycle.

Fixed

  • The carousel and orrery GIFs no longer show something the programs beside them stopped producing. Both were flagged in review as showing an earlier revision, and both were regenerated on the GPU port from the current source. Nothing in the repo ties a GIF to the revision it was rendered from, so the staleness was caught by somebody remembering rather than by a gate -- the stills have the same exposure. A frame overlay confirms the camera is fixed across both loops and only the authored motion moves.

Added

  • A specimen gallery in site/, built by running the programs rather than by committing meshes. The README's stills are a weak claim about geometry -- a lit render hides topology, and a reader has no way to tell a dense mesh from a clean one. The gallery loads all fifty as real GLBs with orbit controls, a wireframe toggle and the triangle count, draw calls, material count and bounds off the engine's own integration manifest. Nothing in it is checked in: site/scripts/build-assets.mjs runs each examples/*.kiln.js through the same evaluator the test suite uses and keeps what comes back, so a program and the mesh on the page cannot drift, and a program that stops building fails the deploy. Attribution on each card comes from the program's own header through scripts/authorship.ts -- extracted from the authorship test so that the README and the gallery read the headers with one parser instead of two that will eventually disagree. React and three live in site/ and nowhere else; the engine still has no browser dependency. .github/workflows/pages.yml deploys it.
  • A fifth skill, kiln-batch-dispatch, for the person pointing agents at the problem rather than the agent building the asset. The other four are read by whoever is holding the geometry; this one covers wiring a harness up, proving the tools are actually reachable before trusting a single result, and running the clean-room dispatcher across models and subjects until you have a library. It exists because the two halves fail as one: a batch launched on unproven wiring produces a pile of empty sandboxes, and no way to tell whether the models were weak or the tools were never there. It also writes down the two limits that cost the most time here -- a harness's default output cap silently truncating a model mid-file, and a run cut off at its deadline still being a success if a usable program is on disk.
  • --category on the dispatcher, with six experimental values and one honest default. Every asset ever dispatched from this repository came back category: 'prop', because the brief said so in a string literal. The problem was never that they were props -- most of them are, correctly, and almost anything can be built as one -- but that the field carried no information, so a library could not be sorted by it and the engine's per-category guidance was unreachable. The flag takes any of the seven contract values and rejects anything else in the first second rather than filing an asset under nothing. prop stays the default and its brief is deliberately empty, which makes it the least constrained thing the dispatcher can send. The other six append a short note on what tends to go wrong for that kind of subject, and they are a bet rather than a taxonomy: worth reaching for when the subject really is a building or a plant, worth dropping first when a run comes back worse than the same brief as a prop. src/__tests__/dispatch-categories.test.ts fails if the list the script carries ever drifts from ASSET_CATEGORIES.
  • Hermes as a fifth harness, which is the first real evidence that any of this is portable. The other four are JavaScript CLIs that broadly agree on what a plugin is; Hermes is a Python agent with its own YAML config, its own skill store and its own provider routing, sharing no code and no convention with them. It takes the same dist/mcp-server.mjs and the same skills/ directory unchanged: hermes mcp add connects on the spot and enumerates all seven tools, and hermes config set skills.external_dirs registers every shipped skill as local. It does not read .claude/skills out of the working directory the way the others do, and that config key is the whole difference. Smoke-tested green at 97s on a free model. -z is the headless mode the dispatcher drives, and since it has no working-directory flag the sandbox is simply the CWD it is spawned in -- which is also where it reads AGENTS.md, so the clean room holds without extra work.
  • bun run smoke:harness, which proves a harness can reach the tools. Every wiring failure in this project has been silent: agy plugin validate reports the MCP server as processed while agy mcp list shows none, and a harness that can see the tools but will not grant them answers exactly like one that never had them -- which is also what a model too weak for the job looks like. Three indistinguishable failures with one symptom is a thing worth being able to test, so this sends a short brief into a throwaway directory -- call kiln_list_primitives, write a four-line program, validate it -- and then builds what came back with the engine, because the child's own report of success is the only evidence that proves nothing. Measured on one machine: Claude Code 13s, OpenCode 37s, Antigravity 105s, each green. Codex reached the model and stopped at its account's own usage limit, which is the diagnosis the script exists to make -- the wiring is fine and the provider is out. Codex has since been smoked green as well, at 37s, once the flag below let it call a tool at all.
  • A fourth vendor in the gallery, and a wider spread of subject. This step took the heroes to twenty-seven, and the additions were chosen for the range they prove rather than for how they look: a supercarrier, a phased-array air-defence radar, a fighter with a lofted aerofoil and a geostationary comms satellite, which are the subjects where a program has to compute its shape rather than place it, and a Dutch tower windmill written by DeepSeek V4 Flash -- the first asset here from a fourth vendor's model, dispatched clean-room through OpenCode like the Muse Spark ones. The anglerfish was rebuilt: the first was a smooth dark cone with a jaw drawn on it, and organic form is the case this tool is worst at, so it is the one worth showing honestly. Eleven of those twenty-seven were not written by Claude.
  • Tangents for non-indexed geometry. computeTangentBasis required an index buffer and warned, per mesh, when there was not one -- so a normal map on any flat-shaded part, anything merged from several geometries, and anything through .toNonIndexed() shipped with no TANGENT attribute and a note saying each runtime would guess its own. That is most of what a hand-built asset is made of. A triangle soup is an index buffer that reads 0, 1, 2, ..., so the same accumulation is exactly right for it and every vertex comes out holding its own face's tangent; a test unwelds a box and checks the soup and the indexed copy agree per vertex. examples/anglerfish.kiln.js had twelve of those warnings and now has none.
  • A measured ceiling on the always-on context cost. src/__tests__/mcp-payload.test.ts now derives the JSON Schema for all seven tools and sums the front matter of every shipped skill, holds each under a budget, and requires the README to quote the real figures. The README argued the surface was small with numbers nothing was checking.
  • kiln_edit, the refine verb, and the kiln-refine-asset skill that drives it. Every MCP tool took a whole program and rendered it, so changing one line of a finished asset meant re-emitting the entire file and trusting that the other two hundred lines came back unchanged. kiln_edit takes exact-string replacements instead: they apply in order, a match that is not unique is refused rather than guessed at, and if any edit fails nothing is applied -- so a bad edit costs a retry rather than a program in a state the model never asked for. It returns the patched source, a unified diff, and the six-view sheet together, because the loop is edit-then-look. It is deliberately stateless: the in-process agent keeps a working buffer across turns, but over MCP the host holds the program text, and a second copy inside the server would have been a desync the model cannot see. The buffer itself moved to src/edit-buffer.ts so both transports share one implementation -- importing it from agent/tools.ts would have pulled @strands-agents/sdk into kiln/tools and into the MCP bundle, which is the one edge that subpath is documented not to have. Like the unified kiln_render, the def sits outside createKilnToolRegistry, whose four tools are a frozen bench baseline.
  • The scanned texture library doubled, from eight CC0 families to sixteen. The first eight were all rough exterior surfaces, which left three material recipes -- skin, leaf, and rubber -- with nothing photographic to bind at all, and made rust the only metal in the package. Added: brown leather, forest leaf litter, rubber tiles, riveted steel plate, clay roof tiles, cobblestone paving, finished oak veneer, and polished marble. 48 maps, 747,977 embedded bytes, still inside the 1 MiB package budget the test enforces.
  • OpenCode support, and clean-room dispatch. scripts/dispatch-asset.mjs gained an opencode harness, reaching a dozen vendors' models behind provider/model ids. More importantly, every dispatch now runs in its own directory containing only the brief and the Kiln skills. Dispatches previously ran with the harness pointed at this repository, where a child agent could read thirteen finished example programs -- which quietly invalidated the claim those runs were evidence for. The write grant is scoped to the sandbox, and the authoring model is stamped into the program it wrote. examples/gramophone.kiln.js is the first asset in the gallery actually built that way -- authored through OpenCode by muse-spark-1.3-contributor, a third vendor's model, in a directory holding nothing but the brief and the skills. Every other example predates the sandbox and is attributed without the clean-room claim.
  • Animated GIFs of the animated examples, via scripts/anim-gifs.ts. The render port fits its camera to the bounding box it is handed, which is right for a still and wrong for a sequence -- a robot arm's posed extent varies 63% across its cycle, so the asset would appear to breathe as the camera refit itself each frame. Because the projection is orthographic and the port's fit is exact, each frame is put back onto one shared camera afterwards by a scale and a translation that are both computable, so the result is a fixed camera rather than an approximation of one.
  • scripts/check-vision.mjs, a preflight that refuses to dispatch a blind model. Kiln's loop is the model looking at its own render, so image input is the one capability that is not optional -- and a text-only model does not fail, it just builds worse assets from the documentation alone. A nine-model batch here was found to contain four text-only models, picked by name on the assumption that a current flagship accepts images. Vision also varies between a vendor's own variants: glm-5.3-flash sees images and glm-5.3 does not. The check reads OpenCode's cached model metadata, costs about two seconds for any number of models, and exits non-zero naming the offenders.
  • Browser-safe GLB integration manifest. Every renderGLB / renderSceneToGLB result now carries kiln.integration-manifest.v1: artifact SHA-256, metre/+Y-up coordinate semantics, world bounds, ground offset, role, render metrics, and structural-validator counts. inspectGlbIntegration(bytes) derives the same contract from finished bytes without executing model-authored source.
  • Four assets from a sixth model, through a sixth harness. GPT-6 Astra wrote an orbital station, a rigid airship at its mooring mast, a blast furnace and a Gothic clock tower, dispatched through Codex into the usual clean room. They are the first batch in this repository where every program cleared the zero-structural-warning bar the shipped examples are held to on the first pass, with no hand repair and no promotion-time fix, at 10,212 / 11,764 / 11,964 / 11,664 triangles. The gallery is now fifty programs, thirty-five of them written by something other than Claude.

Fixed

  • The Codex harness could not call a single tool, and said so only in the child's transcript. codex exec pins its approval policy to never, and a never policy does not queue an MCP call for later approval, it refuses it outright -- so four dispatches came back inside a minute each having written nothing but a note that kiln_list_primitives was blocked. The dispatcher passed --sandbox workspace-write, which grants the filesystem and says nothing about tools; --approve-for-me is the flag that does both, selecting the same sandbox and moving approval to automatic review, and the two are mutually exclusive on the command line for exactly that reason. Worth noting alongside it: codex plugin add installs this repository's manifest happily and registers neither its MCP servers nor its skills, so the TOML server block is still required -- the same trap agy sets, failing the same silent way. Both are now documented per-harness in docs/install.md.
  • cylinderUnwrap now unwraps cylindrically, which it has always claimed to do. It and boxUnwrap were the same function: both preserved existing UVs and both fell back to the same flat projection, so on the one case the file's own header describes -- a curved surface carrying a directional texture -- brick came out as horizontal smears. Built-in cylinderGeo never hit it because Three.js ships UVs with it; anything swept or extruded did, and a texture-backed material on unwrapped geometry is a QA blocker rather than a silent miss. It now runs u around the Y axis and v up the height, normalized across the geometry's own angular span so a 22 degree curb stone gets the whole texture rather than six percent of its width, with caps projected flat so they do not sample a single row of texels.
  • The well, which was a ring of boxes pretending to be masonry. A box has parallel sides, so on a circle its neighbours meet it at an angle and the joint opens into a V that widens toward the outside face -- 40 mm of it at the outer radius, sixteen times around, which read as a cog wheel with a dark slot at every tooth. The curb is now cut the way a mason would cut it: wedge stones whose side faces lie on radial planes, inner and outer faces following the curve, in two courses offset by half a step so no joint runs the full height. The shaft is lined with an extruded ring rather than a solid cylinder, since the hole is the point of a well, and there is water at the bottom of it. The roof posts are bedded rather than balanced: a square post stopped on a round wall always reads as overhanging it, because from any angle where the wall curves away it does, so each post now runs past both courses to the plinth and the three stones on its line are cut around it with boolDiff. Only those stones lose their instancing -- an angular overlap test picks them out, one per post in the un-skewed course and two in the skewed one where the post straddles a joint.
  • The pinball machine's backbox, which stood on nothing. It was built entirely behind the cabinet's rear face, cantilevered off a 30 mm wall. Sliding it forward onto the cabinet only traded one fault for another: the playfield runs the cabinet's full length, so everything the head gained in support it took out of the glass, and at 380 mm deep it buried the bumpers. The fix was the one a real machine already uses -- the cabinet grew the rear bay the head bolts to. It is 1.34 m long instead of 1.14, its rear face and back legs moved with it, the backbox is 200 mm deep rather than 380, and the head now sits on that bay entirely behind the glass. The file's header records the repair, because the gallery makes a claim about who wrote each program and a claim quietly edited afterwards is worse than no claim.
  • The vending machine's sold-out column, which read as a hole in the model. One unlit column was meant to be the asymmetry that stops a 4 x 3 grid looking like a texture. It is, but everything in that column -- the dimmed panel, the bezel shelves, the rails -- is near-black, so instead of an empty rack behind a switched-off light it came out as a solid black rectangle with no shape in it, next to three lit columns. All four columns are stocked now, with an amber PET added as the fourth product, and the asymmetry that survives is the one that was always doing the work: cans in one column, bottles in the other three.
  • The vending machine's bin label, which was a flat plate on a round drum. A 240 mm slab across a 390 mm bin touches it along one line: the middle sinks in and both ends stand 40 mm proud, which from the front reads as a white wing growing out of the side. It is now an annular sector swept up through the label's height -- the same wedge the well's curb stones are cut from -- sitting 6 mm proud all the way round.
  • createPart now rejects a wrong call instead of dying in the exporter. The harness smoke run found this the way it was always going to be found: a free model on Hermes wrote createPart(root, { name, geo, material }) -- the shape most other scene APIs take -- and the run failed 185 seconds later with undefined is not an object (evaluating 'Object.keys(morphAttributes)'). Nothing in that sentence names anything the model wrote, so it had no way back and spent its remaining turns guessing. new THREE.Mesh() accepts any two arguments at all, which is what let a function reference and a plain object travel that far. The three positional arguments are now checked at the door, and each message says which argument, what arrived, and what the call looks like when it is right: a parent passed first is told the parent belongs in the options object, boxGeo without parentheses is told geometry helpers have to be called, an un-awaited roundedBoxGeo is told the helper is async and build() has to be too, and a hex number where a material belongs is told to wrap it. The same program now fails in under a second with a sentence a model can act on.
  • Three hero assets whose geometry was wrong in ways a contact sheet hides. The ferris wheel braced its two A-frames together at mid-height, and the upper tie sat 1.93 m from the hub inside a 3.60 m rim -- a girder straight through the spokes and the cars. It is now a clearance rule rather than a pair of chosen heights: candidate bracing levels are filtered against the wheel's swept envelope, rim radius plus how far a car hangs below its pin, and only the low portal survives, which is exactly where a real double-A-frame wheel is braced. The vending machine's cans were albedo 0x4a2f0c at metalness 0.78; a metal has no diffuse term, so its whole appearance is a specular reflection tinted by its albedo, and a near-black albedo under a neutral studio dome returns almost nothing -- the cans rendered as black rectangles and their column read as empty stock. A printed can is a coating over the metal, so it is dielectric like the bottles, and only the bare lid is aluminium. And the lighthouse's keeper's cottage stood a plain rectangular slab on each end wall as a gable, leaving 0.91 m of stone above the slate at both eaves; the gables are now pentagons derived from the roof pitch through extrudeProfile, tucked 20 mm under the roof underside so the two cannot fight for the same pixel.
  • An external 32,000-token ceiling was ending dispatched runs mid-thought. OpenCode caps one assistant step at 32,000 output tokens by default, whatever the model publishes. It is not a number this project set, and it took reading its session store to see: across every step ever recorded there, nothing had exceeded 32,000 -- not once, not by a token -- while the models involved declare between 80,000 and 943,718. Runs stopped there mid-sentence, with no file and no error, looking exactly like a model that was not up to the work. Dispatch now sets OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX per run from the model's own declared limit, read out of OpenCode's model catalog, so the ceiling is the provider's and never one invented here. docs/install.md says how to do the same by hand.
  • Removed every default cap on how much work an agent may do. The generation budget defaulted to 40 model calls, --max-steps to 24, and whole-program rewrites after a first successful render to 2. All three were cost guards from a hosted product where the operator paid for the calls. Out here the person running the tool is the person paying for it, and a ceiling they did not choose stops an asset halfway for reasons that have nothing to do with the asset. All three now default to no limit -- zero was already this codebase's "unlimited" value, honoured by the call budget, the step hook and the grade-refine headroom check, so this is a default change rather than new machinery. --max-steps also accepts 0 now instead of rejecting the value its own help text recommends, and the rewrite bound became a per-host option so a caller who wants it can still ask. The sandbox byte limits, the procedural texture bounds and the render deadlines stay: those are safety and correctness, not cost.
  • Nothing told a model to write the file before it had solved the asset. The skill's loop said "write the program" at step two and "write the final program to a file" at step six, which invites a model to keep the whole thing in its head until it is finished. Some do, and never arrive: measured through OpenCode's session store, four separate runs spent their entire output allowance -- to the token -- on one unbroken reasoning block, hand-solving pin positions and cylinder attachment points in prose until they were cut off mid-number, having written nothing at all. Three different vendors' models failed this way. The loop now says to save a rough version early, says plainly not to solve the geometry analytically first, and names the failure so a model can recognise it. The dispatch brief says the same.
  • Attribution rested on the request rather than on what ran. The dispatcher stamped the model it had asked for, which is the one claim the gallery exists to make and the one thing it was not checking. It now reads the model back out of the harness's own output and records that, reporting the difference if the two ever disagree. No harness has been caught substituting a model -- every one of the six OpenCode runs already promoted agrees with its log -- so this closes a gap rather than a leak, and makes "nothing in the gallery is misattributed" a statement backed by a check instead of an assumption.
  • Codex could never have authored an asset. Three faults in its entry in the dispatch table, each of which fired before the model saw the brief, which is why nothing in the gallery came from it and why nothing said so. --full-auto is deprecated in favour of an explicit --sandbox. A clean room is a bare temp directory, and Codex refuses to start in one as "not inside a trusted directory" unless the git check is waived. And the sandbox was never passed at all: with no --cd the child ran in this repository, with every finished example in reach -- the exact contamination the sandbox exists to prevent, in the one harness whose results would have been quietly worthless rather than merely absent. Its default model is now unset rather than gpt-5.1-codex, which that account is not entitled to and which no repository can guess; dispatch demands --model instead of stamping an author it cannot name.
  • The dispatcher's usage line omitted OpenCode, which had written six of the twenty-seven programs in the gallery at the time. It is generated from the harness table now, so it cannot drift from the list it describes again.
  • A busy GPU renderer was read as an absent one. --render auto probed /health with a 1.5 second budget and treated anything that was not a clean answer as "no service here". The render service is single-threaded, so while it is drawing somebody else's frame it accepts the socket and answers late, and a batch of agents pointed at one GPU had runs silently drop to the CPU rasterizer and judge their materials off a sheet where every textured surface is flat white. Nothing logged a fault, because from the caller's side nothing had failed. The probe now distinguishes the two: a refused connection still falls through at once, which is the point of the short budget on machines with no renderer at all, but a timeout is retried against an 8 second one. src/__tests__/cli-render-mode.test.ts holds a stand-in service to both cases and to the closed port.
  • Material constructors accepted an options object as their colour. gameMaterial(color, options?) takes the colour first, and a program that wrote gameMaterial({ color, roughness, metalness }) got a white material at default roughness rather than an error: THREE.Color.set ignores an object it does not recognise, so the mistake survives all the way to the render, where it looks like a lighting problem. It cost a real asset an afternoon. All four constructors now refuse a non-colour first argument and say where the settings go.
  • A dispatched program that outlived its own run lost its author. scripts/dispatch-asset.mjs recorded the authoring model only on a clean exit, so a run that wrote a finished program and then hit a wall was scored as having produced nothing: the file was still promoted, and stamped Authored by: null. Which is worse than an honest partial claim, because it is not a claim at all. Three assets in this gallery were written that way. The check is now "is there a program on disk", asked before the failure is classified rather than inside one branch of it, so it covers every way a run can be cut short instead of the one that was noticed first -- a provider limit, and the dispatcher's own 25 minute deadline, both of which fire long after the program is written. The interruption is carried into the manifest and stated plainly in the file header, because a run that was cut off cannot claim it looked at its own render and revised. Separately, the rate-limit matcher knew RESOURCE_EXHAUSTED, 429 and quota but not "session limit", which is Claude Code's wording, so a batch that hit one reported three flat failures and gave up instead of falling back or waiting the window out.
  • examples/aircraft-carrier.kiln.js wore a comb of teeth around its counter. The hull, the flight deck and the deck-edge netting were runs of axis-aligned slabs, each held at the half-beam or the deck width of its own centre. Wherever the ship is not parallel to its own keel -- the fine entry, the whole counter, the stern round-in where the starboard edge sweeps 21 m outboard in 23 -- every join left an end cap facing aft, and an end cap is lit as a different surface from the plating either side of it. Halving the station spacing only doubled the number of teeth, because the discontinuity was in the normals and not in the size of the step. All three are now lofted along their own planform curves, which share their vertices: no cap to catch the light, no step to refine, and 7,000 fewer triangles than the slabs cost.
  • Dispatched Claude runs stopped for permission with nobody to ask. --permission-mode acceptEdits grants writes and nothing else, so a child that reached for kiln_render blocked on a prompt no terminal was attached to. Three of four runs in one batch returned after a minute having written no program, no error and exit 0 -- just a courteous note about which permissions they would need, which is the worst shape a failure can take on an unattended path. The sandbox now ships a .claude/settings.json allowing the Kiln MCP tools under either install name plus the file tools, scoped to the one throwaway directory rather than reaching for --dangerously-skip-permissions.
  • A dispatch deadline that could not actually end a run. --timeout fired on schedule, wrote "timed out; killed" into the log, and then called child.kill(), which signals the direct child and nothing beneath it. On the path that matters that child is a shell: an npm-installed CLI on Windows is a .cmd shim, so the agent itself is a grandchild and survived. It went on holding the stdout pipe open, close never fired, and the job hung after having already been declared dead -- three jobs in one batch sat between 14 and 38 minutes past a 24-minute deadline, with a concurrency slot held by each. The deadline now kills the process tree (taskkill /T on Windows; elsewhere the child is spawned as its own process-group leader so the group takes the signal), and the promise settles on a 15-second grace timer whether or not close ever arrives, so a descendant that refuses to die costs one job rather than the batch.
  • Orthographic views now fit what they are looking at. The GPU render service framed every view with max(sizeX, sizeY, sizeZ) * 0.72 -- the longest axis whichever way the camera was pointed, padded by a constant -- so anything that was not a cube rendered small in a large frame, and a long object viewed down its own axis was framed for a length nobody could see. Views are now fitted per direction by projecting the bounding box's eight corners onto the camera basis, which is exact for an orthographic projection. This also makes --render cpu and --render gpu frame identically: the CPU rasterizer has always fitted this way, and the two disagreeing meant the documented side-by-side of the two modes was not comparing the same crop. render-service/src/framing.mjs is the whole of it, and it is GPU-free so it is covered by unit tests.
  • Unit-length normals out of lathe() and revolveGeo(). THREE.LatheGeometry copies its running meridian normal into the previous-normal slot before normalising it, so the final ring of a revolve carried normals scaled by the length of the last profile segment -- enough to fail GLTF_ACCESSOR_VECTOR3_NON_UNIT on export. Both entry points now normalise before returning.
  • kiln_list_primitives no longer sends its catalog twice. The result carried all 92 entries as a structured array and as the text rendered from that array, and the default MCP serialization pretty-printed both: 90,497 bytes for one call. Harnesses disagree about results that size. OpenCode truncates them, spills the full copy to a file, and hands the model a cut-off catalog -- a dispatched glm-5.3 run spent twenty-two minutes grepping that spill file at increasing offsets and never wrote a program. KilnToolDef gained an optional text() extractor (the text analogue of the existing media()), so a def whose output already contains a rendered form of itself can send that instead of a JSON dump. In-process callers still get primitives from run(). Measured after: 36,647 bytes, received in full, with the same model correctly enumerating all 92 primitives. src/__tests__/mcp-payload.test.ts holds the ceiling.
  • Unit-length normals out of subdivide(). three-subdivide builds each new vertex normal by summing the normals of the faces meeting there and never divides through, so a normal comes back at the length of however many faces touched it -- 2/3 after one iteration on a box, 0.35 after two. No raster shows it, because a shader normalises before it lights, but the glTF validator rejects every one of them. Found by a dispatched agent whose printing-press bed was subdivide(boxGeo(1.5, 0.6, 0.8), 2): 1,104 bad normals out of 1,152, and the build stopped at final-glb. Same repair as lathe(). src/__tests__/subdivide-normals.test.ts also asserts the raw upstream call is still broken, so the workaround can be removed the day that changes.
  • Explicit default scenes on exported GLBs. Generated and composed artifacts now set the glTF default scene, and optimize/palette rewrites repair legacy files whose first scene existed without being selected. Consumers no longer have to guess which scene to mount.
  • kiln_screenshot_animation no longer rejects every textured asset. The tool poses the scene and exports it again to render one camera cell, and that export was being submitted to asset QA as though it were a new asset. It is not: those bytes came out of this engine and had already passed. But a texture that has been through a GLB round trip returns as a decoded image without the payload provenance MAT_TEXTURE_DECODE_FAILED looks for, so QA blocked the preview -- meaning no textured asset could look at its own animation, including examples/robot-arm.kiln.js, which is the repository's designated animation example. renderSceneToGLB gained a derivative option that makes QA observe rather than block for exactly this re-serialization; reports still record their real disposition, and the option is far narrower than the process-wide KILN_QA_MODE escape hatch.
  • Dispatched agents no longer hang after finishing their work. scripts/dispatch-asset.mjs spawned children with stdin as an open pipe. OpenCode keeps its process alive while stdin is open, so a run would author the asset, write the file, and then sit there until the dispatch timeout killed it and reported a failure. Children are now spawned with stdin closed; the same command that ran to a 75-second kill exits in six.
  • The dispatch sandbox is a real one. It was created under .dogfood/, inside this repository, so a child agent's CLI resolved the project root by walking up to .git and found the whole repo, examples/ included. It now lives in the OS temp directory.
  • The MCP server no longer needs Bun on the consumer's PATH. Every published config said "command": "bun", which asks the harness to resolve a name against its own environment. Bun's Windows installer appends to the User PATH, and a process only ever sees the environment it was born with, so any harness started before that install died with exec: "bun": executable file not found in %PATH%. There is no Bun-specific API on the server's runtime path, so it now ships as dist/mcp-server.mjs, a committed Node bundle -- committed because a plugin install is a git clone with no build step. Bun remains the development toolchain and is no longer something a user of the plugin needs.

[0.6.0] -- 2026-07-12

Added

  • measureGlbBounds(bytes) (H-41). World-space AABB straight from stored GLB bytes (WebIO + getBounds, EXT_mesh_gpu_instancing registered) so consumers that only hold the artifact never need executeKilnCode to recover a footprint -- Kiln Studio's compose catalog drops its execute-model-code bbox fallback on this.
  • Six-grid rear-quarter variant (H-33 arm). SIX_VIEWS_REAR_QUARTER swaps the 3/4 cell to the opposite-rear azimuth ([-0.7, 0.5, -0.7], labeled 3/4 Rear); resolveGridViews(variant) + the KILN_GRID_VARIANT=rear-quarter env select it as the renderViewGrid default per-process -- no wire or tool-schema change. Explicit opts.views always wins; unknown env values fall back to SIX_VIEWS.
  • Gemini thinking + budget knob (H-43/B1). The google provider now forwards KilnModelDescriptor.maxTokens → generationConfig.maxOutputTokens and effort keywords → thinkingConfig.thinkingLevel ('xhigh'/'max' collapse to 'high'; numbers ignored; the KILN_THINKING env stays Anthropic-only). A bare descriptor still sends nothing -- Gemini API defaults (65,536 output, dynamic thinking) are preserved unless a consumer opts in. NOTE for consumers: registry rows that carried a decorative Google maxTokens now BIND -- set them to the intended ceiling before upgrading.

Changed

  • The texture library's signal floor is now two floors instead of one. The package-weight test asserted every map's peak channel deviation cleared 2, which worked while all eight families were rough: it was really asking "is this real photography rather than a proof swatch". Extending the library to smooth materials broke it for the right reason -- a polished marble normal map and an oak veneer normal map are supposed to be near-flat, and one high floor would have quietly restricted the library to rough surfaces forever. Per map the assertion is now only that the image is not constant; the photography claim is enforced per family, where it belongs.
  • OpenRouter reasoning clamp (A7). resolveOpenRouterReasoning(thinking, maxTokens?) now bounds reasoning by the completion budget: numeric budgets cap at 50% of maxTokens (dropped entirely when even the 1024 floor exceeds that half), and 'high'/'xhigh' downgrade to 'medium' when OpenRouter's ~80% translation would leave < 8,192 visible tokens (the cycle-2 step-1 MaxTokens deaths: a 32K model at 'high' kept only ~6.4K for visible output). 64K/48K configurations are untouched.
  • QA-blocked render errors are actionable (H-40(3)). AssetQaBlockedError's message now spells out each blocker's human message + authored repairText (first 6, then a count) instead of bare rule codes -- this string is exactly what the agent reads when a mid-loop kiln_render is QA-blocked, and what the salvage path records for QA-blocked step-cap programs.

Measured

  • Per-render QA cost (H-40(4), scripts/qa-cost-bench.ts): registry rules add 1–10 ms p95 per render across all five category fixtures; Khronos validation (unconditional, both modes) adds 1–4 ms p95. Two orders of magnitude under the 1.5 s follow-up threshold -- mid-loop QA stays on unconditionally.

[0.4.0] -- 2026-07-02

Added

  • M1c GPU-instancing pass (plan/05 §3.3). renderSceneToGLB/renderGLB gain an instance: 'off' | 'auto' | 'on' option (default auto = only role: 'fill' assets) and optimizeGlbBytes gains { instance, role } -- the web-tier re-bake seam, so the pass reaches prod with no wire change. Repeated geometry (>= 5 nodes sharing one mesh after dedup) is rewritten to EXT_mesh_gpu_instancing batches in the upstream-canonical dedup → instance → palette order, cutting draw calls + bytes for fence runs / colonnades / container stacks. Perf/filesize only -- the A–F grade keys on material count and does not move (tests assert grade + triangle parity). Skipped for animated/skinned docs and any asset carrying Joint* pivot names (Kiln City targets those by name). Results are recorded as InstancingSummary (meta.instancing, RenderSceneResult.instancing, OptimizeGlbResult.instancing -- and OptimizeGlbResult.summary is now optional: an instancing-only pass has no consolidation summary). All engine glTF IO now registers EXTMeshGPUInstancing (new dep @gltf-transform/extensions) so re-reads (grade-from-bytes, optimize-from-bytes, palette snap, scene export merge) preserve the batches, and collectGlbMetrics is instance-aware (an instanced node counts one draw but N× its triangles -- exactly what a supporting GPU renders).
  • M3 composer role/tier awareness (plan/05 §4.1). CatalogEntry gains optional role (CatalogAssetRole -- the M1d asset taxonomy) + tier (A–F); catalogList() (and therefore scene_list_assets) surfaces them. Placement roles now DEFAULT from the catalog asset's role via placementRoleForAsset (wonder/poi → hero, fill → fill, else support) in place/placeExact/cluster/ring/layout -- an explicit agent role still wins. The composer system prompt teaches the mapping, wonder scale-up, and D/F-tier density budgeting.

[0.3.0] -- 2026-07-02

Added

  • Generation-loop transcript compaction (default on). Before every model call, runKilnAgent now strips the image out of each SUPERSEDED render tool result (kiln_render / kiln_screenshot / kiln_view_interior / animation strips), swapping it for a short text placeholder -- only the newest render image rides each request. The prune is surgical, unlike the composer's whole-transcript collapse: no messages are added or removed, toolUseIds are untouched (tool-use/tool-result pairing stays valid on every provider), and the JSON metrics half of each result survives. This was the biggest input-token/cost lever in a multi-render run -- previously every render image rode ALL later model calls. Opt out per run with imageCompaction: 'off'. New helpers exported from agent: pruneStaleRenderImages, installRenderImageCompaction, STALE_RENDER_PLACEHOLDER.
  • M1b grade-aware refine loop (plan/05 §3.2, default on). After the model finalizes, the run bakes + grades the program exactly as the shipped artifact will be graded (grade-aware auto consolidation, matching generateKilnAsset and the Studio web-tier re-bake). If it still grades below B for a consolidation-fixable reason -- material sprawl (>3 distinct) or texture sprawl (>4), never a transparency-only demotion (glass caps at C by design) -- and the step budget leaves headroom, ONE bounded feedback turn (grade, material count, offending material list, consolidation directive) is fed back; the refined program is kept only if its grade actually improves. Opt out with gradeRefine: 'off'. Emits a grade_refine progress event; token usage now accumulates across the extra invoke. New helpers exported from agent: assessProgramGrade, shouldGradeRefine, buildGradeRefineMessage, gradeRank.

Fixed

  • Step-cap abort no longer discards a rendered program. A run halted by the model-call cap used to return only an error, throwing away the working-buffer program the sink already held. If the captured program renders, the run now returns it with the new RunKilnAgentResult.capped: true flag (mirrors the composer's capped semantics); a cap with nothing renderable is still an error.

[0.2.0] -- 2026-07-02

The release cut the 0.1.1 composer note promised: formally versions the scene composer surface (@kiln/engine/composer, /composer/agent -- shipped in 0.1.x without a bump) plus the fixes below.

Fixed

  • auto consolidation now fires on 4-material assets. PALETTE_MIN dropped 5 → 4, aligning the trigger with the instanceability rubric (grade B tops out at 3 materials, so 4 is the first grade-C count). Previously a 4-material asset graded C and auto never consolidated it.
  • Uint32 indices for >65,535-vertex geometry. bridgeGeometry always wrote Uint16Array indices, silently wrapping values past 65,535 (corrupt GLB). It now selects Uint32Array when the vertex count exceeds the Uint16 ceiling; the GLB writer emits the matching componentType (5125).
  • BYOK apiKey reaches Anthropic/OpenAI. makeKilnModel dropped opts.apiKey on the anthropic and openai branches (only google/openrouter passed it through), so BYOK silently fell back to the provider env vars.

Changed

  • Comments in agent/tools.ts / agent/run.ts updated: the unified tool surface is the production surface (Kiln Studio runs KILN_TOOL_SURFACE=unified), no longer "flag-gated until a bench A/B clears it"; current remains the library default.

Housekeeping

  • Added the missing LICENSE file (MIT, already declared in package.json).
  • Rewrote the stale @pixel-forge/core module headers (metrics.ts, agent/index.ts, agent/run.ts, palette.ts) to the @kiln/engine reality and removed dangling references to files that do not exist in this repo.

[0.1.1] -- 2026-06-30

Documentation

  • Clarified that @kiln/engine remains private execution infrastructure. External developer access is mediated by Studio /v1, private SDK/skills, and future AgentCore Gateway product tools rather than direct engine, raw Forge, or composer harness exposure.

Changed

  • Treat native claude-sonnet-5 as adaptive-only for Anthropic thinking controls: numeric KILN_THINKING budgets are ignored for this model so the agent harness does not send manual extended-thinking params that Sonnet 5 rejects.

Added -- scene composer (@kiln/engine/composer, /composer/agent)

A THREE-free scene-composition surface: a PlacementModel single-source-of-truth with a small scene DSL (scene()/asset()), terrain-agnostic hierarchy-aware layout, an overlap validator (MTV resolution), a ground sampler, and a SceneRenderPort; plus the Strands agent loop (runKilnComposer, 14 scene_* tools) isolated under /composer/agent so the SDK never leaks into the pure core. Transcript compaction collapses to serialize(model) past a threshold (the externalized model IS the state), with a soft step-cap backstop and a scene_layout-first prompt so large many-asset scenes converge. ~990 lines of new tests.

The surface landed without a version bump (Studio consumed it via the committed @kiln/engine 0.1.0 tarball); formally versioned by the 0.2.0 release above.

[0.1.0] -- 2026-06-23

Initial extraction of the Kiln 3D engine from pixel-forge/packages/core/src/kiln (source d396c10), file history preserved via git subtree split.

Included (the reachable runtime closure of agent/render/palette/views/arena)

  • agent/ Strands agent loop · arena/ ranking math · render.ts GLB bake/grade/optimize/snap/composeScene
  • primitives.ts · solids.ts (CSG) · ops.ts · gears.ts · uv.ts/uv-shapes.ts · textures.ts
  • validation.ts (AST) · inspect.ts · metrics.ts · palette.ts/palette-snap.ts
  • list-primitives.ts · prompt.ts/prompt-api.ts · tools/registry.ts · views/ (CPU rasterizer + PNG)

Removed vs pixel-forge core/kiln (what makes it lean)

  • TIJ pipeline modules imposter/, fbx-ingest/, sprite-atlas/, retex/, photogrammetry/, lod/ -- the only modules pulling in Playwright + the heavier image path.
  • Legacy single-shot generate.ts (Studio uses the agent path) and the entangled root index.ts barrel (Studio consumes subpaths, not the barrel).
  • Dropped deps: @anthropic-ai/*, @ai-sdk/{anthropic,google,openai}, @google/genai, openai, @fal-ai/client, Vercel ai, playwright, meshoptimizer, xatlas-three, @pixel-forge/shared.

Retained runtime deps (lazy-loaded)

  • sharp -- texture decode in loadTexture (await import('sharp')).
  • xatlasjs -- UV atlas in autoUnwrap (await import('xatlasjs/dist/node/...')).

Tests

  • 36 source test files ported (382 pass / 2 skip / 0 fail offline). Live agent tests gated behind KILN_SPIKE_LIVE=1 (off in CI). Dropped: the 6 OUT-module test suites, deps-smoke (old dep set), spike/top-level-generate (tested the deleted barrel generate() wrapper), and companions/refactor-validation (tested the legacy generate.ts companion aliases kiln.editCode/kiln.refactor, also pruned).
  • Provider SDKs (@anthropic-ai/sdk, @google/genai, openai, ai, @aws-sdk/client-bedrock-runtime) are devDependencies only -- needed to exercise the multi-provider makeKilnModel factory in providers.test.ts; they never enter runtime dependencies. The kiln-glb skill-drift gate is skipIf-guarded (the skill lives outside the engine repo).

Tooling

  • Biome 2.5.1 adopted (lint + format). Source formatted to Biome style (single quotes, 2-space, 100-col); bun run lint is green. A baseline of 19 stylistic warnings (noExplicitAny/useTemplate/useOptionalChain/noGlobalIsFinite/…) is left visible for a hardening pass; noNonNullAssertion/useLiteralKeys are off and useIterableCallbackReturn is warn (all idiomatic in the extracted code).

Follow-ups (deliberately deferred from WS0 -- see ../plan/03-standards-harness.md)

  • Burn down the 19 Biome warnings + re-promote useIterableCallbackReturn to error.
  • Tighten tsconfig (exactOptionalPropertyTypes); currently mirrors pixel-forge core for a zero-drift green typecheck.
  • Consider tsup dist build + Vitest golden-image render harness (engine ships TS source today for drop-in parity with how Studio consumes core).
  • Rename the live-test gate KILN_SPIKE_LIVE → KILN_LIVE.