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.

docs: rewrite the README around the fifty, and say how to install the plugin

Matt Kissinger81de3f7e6c56
diff --git a/AGENTS.md b/AGENTS.md
index cb236ccd..fc59a555 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,7 +15,7 @@ Read [README.md](./README.md) before changing exports or package contents. Runti
`src/tools/registry.ts` owns tool names, descriptions, and schemas. Two skins consume it: the
in-process Strands tools (`src/agent/tools.ts`) and the stdio MCP server. **Both must iterate the
-registry** — never hand-write a tool definition in a skin, or the transports drift apart and the
+registry** -- never hand-write a tool definition in a skin, or the transports drift apart and the
repo's central claim stops being true. There is a test that asserts name parity; keep it passing.
Prefer an explicit terminal submit tool over `structuredOutputSchema` in the in-process loop: the
@@ -32,7 +32,7 @@ deterministic engine paths.
The port is injected twice, for different jobs, and their deadlines must stay separate. A host calls
it once after the loop for the artifact sheet, where nothing is blocked and a long deadline is
correct. `KilnToolContext.viewRenderPort` injects it into `kiln_render` for the IN-LOOP grid, where a
-slow render blocks the agent mid-thought — that deadline is its own per-call argument and belongs far
+slow render blocks the agent mid-thought -- that deadline is its own per-call argument and belongs far
lower. Never collapse the two onto one value.
Routing is conditional on `sceneNeedsPbrShading(root)`: bound texture or `metalness > 0`, never
@@ -40,7 +40,7 @@ material type, because `gameMaterial` and `pbrMaterial` both construct a `MeshSt
are indistinguishable after construction. Host telemetry rides `onViewsRendered`, while every unified
`kiln_render` result also carries model-visible `ViewFidelityV1`; a geometry-flat CPU image must never
be treated as material evidence. Keep the input schema stable unless the active change explicitly
-versions it — the tool definition is cached, and changing it invalidates that cache.
+versions it -- the tool definition is cached, and changing it invalidates that cache.
**The GPU is a view producer only, never gate evidence.** `QaContext` is deliberately image-free so a
QA rule structurally cannot read a render buffer. Do not add pixels to it.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8406622b..220f0351 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,40 +6,475 @@ for the consuming app's lockfile + tarball provenance, not public npm releases.
## [Unreleased]
### 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
+## [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 —
+ 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.
+ 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
+ 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
+ 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
@@ -49,7 +484,7 @@ for the consuming app's lockfile + tarball provenance, not public npm releases.
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
+ (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.
@@ -57,56 +492,56 @@ for the consuming app's lockfile + tarball provenance, not public npm releases.
- **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.
+ 1.5 s follow-up threshold -- mid-loop QA stays on unconditionally.
-## [0.4.0] — 2026-07-02
+## [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
+ 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
+ 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
+ `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).
+ 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()`
+ `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
+ 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
+## [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
+ 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
+ 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
+ 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
+ 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
@@ -120,10 +555,10 @@ for the consuming app's lockfile + tarball provenance, not public npm releases.
`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
+## [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)
+surface (`@kiln/engine/composer`, `/composer/agent` -- shipped in 0.1.x without a bump)
plus the fixes below.
### Fixed
@@ -150,7 +585,7 @@ plus the fixes below.
`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
+## [0.1.1] -- 2026-06-30
### Documentation
- Clarified that `@kiln/engine` remains private execution infrastructure. External developer access
@@ -162,7 +597,7 @@ plus the fixes below.
`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`)
+### 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
@@ -174,7 +609,7 @@ past a threshold (the externalized model IS the state), with a soft step-cap bac
> 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
+## [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`.
@@ -187,7 +622,7 @@ Initial extraction of the Kiln 3D engine from `pixel-forge/packages/core/src/kil
### 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
+ `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).
@@ -196,8 +631,8 @@ Initial extraction of the Kiln 3D engine from `pixel-forge/packages/core/src/kil
`@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/...')`).
+- `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
@@ -206,7 +641,7 @@ Initial extraction of the Kiln 3D engine from `pixel-forge/packages/core/src/kil
`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
+ `@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).
@@ -218,7 +653,7 @@ Initial extraction of the Kiln 3D engine from `pixel-forge/packages/core/src/kil
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)
+### 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.
diff --git a/README.md b/README.md
index c9a42f74..763640a8 100644
--- a/README.md
+++ b/README.md
@@ -1,89 +1,275 @@
# Kiln
-**A vision-in-the-loop code-generation agent that builds 3D assets as source code.**
+[![CI](https://github.com/matthew-kissinger/kiln/actions/workflows/ci.yml/badge.svg)](https://github.com/matthew-kissinger/kiln/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-Kiln turns a sentence into a game-ready GLB by having a model *write a program*, look at what it
-rendered, and fix it — not by sampling a mesh. The output is a small program with named parts, not
-an opaque blob: editable, diffable, parametric, and readable by the next agent that touches it.
+**Game-ready 3D models, built by an agent that writes them as code, renders them, and looks at what
+came out.**
-Ten hero assets, each one a checked-in program in [`examples/`](examples/). Click any image for
-the full-size render. No mesh was sampled, no geometry was hand-authored, and none of it was
-touched in a DCC tool. A model wrote each program, rendered it, looked at the result, and revised
-— which is also why each file's header comment reads like a post-mortem.
+Kiln does not sample a mesh. A model writes a small JavaScript program that constructs the geometry;
+Kiln runs it, exports a glTF binary, rasterizes six orthographic views, and hands the images back so
+the model can fix what it sees. What you keep at the end is the GLB *and* the program that made it:
+named parts, real metres, a diff you can read, and a file the next agent can edit instead of
+regenerating from scratch.
+
+Fifty assets below, each one a checked-in program in [`examples/`](examples/). Click any image
+for the full-size render. No mesh was sampled, no geometry was hand-authored, and nothing was
+touched in a DCC tool. A model wrote each program, looked at the render, and revised, which is why
+every file's header comment reads like a post-mortem.
<table>
<tr>
<td width="33%" valign="top"><a href="examples/renders/field-gun.png"><img src="examples/renders/field-gun.png" alt="a Napoleonic field gun on a wooden carriage, generated by Kiln"></a><br><b><a href="examples/field-gun.kiln.js">field-gun</a></b><br>15,544 tris &middot; Claude Opus 5<br><sub>booleans and arrays</sub></td>
- <td width="33%" valign="top"><a href="examples/renders/street-lamp.png"><img src="examples/renders/street-lamp.png" alt="a cast-iron gas street lamp, generated by Kiln"></a><br><b><a href="examples/street-lamp.kiln.js">street-lamp</a></b><br>13,036 tris &middot; Claude Opus 5<br><sub>revolved profiles, emissive + glass</sub></td>
- <td width="33%" valign="top"><a href="examples/renders/diving-helmet.png"><img src="examples/renders/diving-helmet.png" alt="a brass standard diving helmet, generated by Kiln"></a><br><b><a href="examples/diving-helmet.kiln.js">diving-helmet</a></b><br>16,416 tris &middot; Claude Opus 5<br><sub>material contrast</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/cathedral.png"><img src="examples/renders/cathedral.png" alt="a Gothic cathedral with flying buttresses and lit stained glass, generated by Kiln"></a><br><b><a href="examples/cathedral.kiln.js">cathedral</a></b><br>19,842 tris &middot; Claude Opus 5<br><sub>repetition, and windows cut rather than placed</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/mech.png"><img src="examples/renders/mech.png" alt="a walking mech with plated limbs, generated by Kiln"></a><br><b><a href="examples/mech.kiln.js">mech</a></b><br>18,398 tris &middot; Claude Opus 5<br><sub>armour oriented along a bone</sub></td>
</tr>
<tr>
+ <td width="33%" valign="top"><a href="examples/renders/diving-helmet.png"><img src="examples/renders/diving-helmet.png" alt="a brass standard diving helmet, generated by Kiln"></a><br><b><a href="examples/diving-helmet.kiln.js">diving-helmet</a></b><br>16,416 tris &middot; Claude Opus 5<br><sub>material contrast</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/cafe-racer.png"><img src="examples/renders/cafe-racer.png" alt="a cafe racer motorcycle, generated by Kiln"></a><br><b><a href="examples/cafe-racer.kiln.js">cafe-racer</a></b><br>16,962 tris &middot; Claude Opus 5<br><sub>a tapered sweep along a curve</sub></td>
<td width="33%" valign="top"><a href="examples/renders/penny-farthing.png"><img src="examples/renders/penny-farthing.png" alt="a penny-farthing bicycle, generated by Kiln"></a><br><b><a href="examples/penny-farthing.kiln.js">penny-farthing</a></b><br>12,450 tris &middot; Claude Opus 5<br><sub>curves and radial arrays</sub></td>
- <td width="33%" valign="top"><a href="examples/renders/mech.png"><img src="examples/renders/mech.png" alt="a walking mech with plated limbs, generated by Kiln"></a><br><b><a href="examples/mech.kiln.js">mech</a></b><br>18,398 tris &middot; Claude Opus 5<br><sub>armour oriented along a bone</sub></td>
- <td width="33%" valign="top"><a href="examples/renders/arcade-cabinet.png"><img src="examples/renders/arcade-cabinet.png" alt="an upright arcade cabinet, generated by Kiln"></a><br><b><a href="examples/arcade-cabinet.kiln.js">arcade-cabinet</a></b><br>19,916 tris &middot; <b>Gemini 3.8 Flash</b><br><sub>silhouette from a swept profile</sub></td>
</tr>
<tr>
<td width="33%" valign="top"><a href="examples/renders/sushi-store.png"><img src="examples/renders/sushi-store.png" alt="a two-storey Japanese sushi shopfront with a tiled roof, generated by Kiln"></a><br><b><a href="examples/sushi-store.kiln.js">sushi-store</a></b><br>24,082 tris &middot; Claude Opus 5<br><sub>a facade as layered depth</sub></td>
- <td width="33%" valign="top"><a href="examples/renders/cafe-racer.png"><img src="examples/renders/cafe-racer.png" alt="a cafe racer motorcycle, generated by Kiln"></a><br><b><a href="examples/cafe-racer.kiln.js">cafe-racer</a></b><br>16,410 tris &middot; Claude Opus 5<br><sub>a tapered sweep along a curve</sub></td>
- <td width="33%" valign="top"><a href="examples/renders/beam-engine.png"><img src="examples/renders/beam-engine.png" alt="a rotative beam engine, generated by Kiln"></a><br><b><a href="examples/beam-engine.kiln.js">beam-engine</a></b><br>15,396 tris &middot; Claude Opus 5<br><sub>an animated four-bar linkage</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/street-lamp.png"><img src="examples/renders/street-lamp.png" alt="a cast-iron gas street lamp, generated by Kiln"></a><br><b><a href="examples/street-lamp.kiln.js">street-lamp</a></b><br>13,036 tris &middot; Claude Opus 5<br><sub>revolved profiles, emissive + glass</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/arcade-cabinet.png"><img src="examples/renders/arcade-cabinet.png" alt="an upright arcade cabinet, generated by Kiln"></a><br><b><a href="examples/arcade-cabinet.kiln.js">arcade-cabinet</a></b><br>19,916 tris &middot; Gemini 3.8 Flash<br><sub>silhouette from a swept profile</sub></td>
+</tr>
+<tr>
+ <td width="33%" valign="top"><a href="examples/renders/robot-arm.png"><img src="examples/renders/robot-arm.png" alt="a six-axis industrial robot arm with a parallel gripper, generated by Kiln"></a><br><b><a href="examples/robot-arm.kiln.js">robot-arm</a></b><br>15,324 tris &middot; Claude Opus 5<br><sub>a kinematic chain that animates</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/carousel.png"><img src="examples/renders/carousel.png" alt="a fairground carousel with a striped canopy and horses, generated by Kiln"></a><br><b><a href="examples/carousel.kiln.js">carousel</a></b><br>16,356 tris &middot; Gemini 3.8 Flash<br><sub>a radial array that turns</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/ferris-wheel.png"><img src="examples/renders/ferris-wheel.png" alt="a ferris wheel with lit gondolas on a braced frame, generated by Kiln"></a><br><b><a href="examples/ferris-wheel.kiln.js">ferris-wheel</a></b><br>10,452 tris &middot; Gemini 3.8 Flash<br><sub>a lattice that still reads at distance</sub></td>
+</tr>
+<tr>
+ <td width="33%" valign="top"><a href="examples/renders/orrery.png"><img src="examples/renders/orrery.png" alt="a brass orrery with an emissive sun and planets on arms, generated by Kiln"></a><br><b><a href="examples/orrery.kiln.js">orrery</a></b><br>15,720 tris &middot; Gemini 3.8 Flash<br><sub>arrayed gear teeth on one drive</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/longcase-clock.png"><img src="examples/renders/longcase-clock.png" alt="a mahogany longcase clock with a painted dial, generated by Kiln"></a><br><b><a href="examples/longcase-clock.kiln.js">longcase-clock</a></b><br>12,600 tris &middot; Gemini 3.8 Flash<br><sub>case joinery at furniture scale</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/radio-telescope.png"><img src="examples/renders/radio-telescope.png" alt="a steerable parabolic radio telescope on a pedestal, generated by Kiln"></a><br><b><a href="examples/radio-telescope.kiln.js">radio-telescope</a></b><br>16,532 tris &middot; Gemini 3.8 Flash<br><sub>a dish that tracks</sub></td>
+</tr>
+<tr>
+ <td width="33%" valign="top"><a href="examples/renders/anglerfish.png"><img src="examples/renders/anglerfish.png" alt="a deep-sea anglerfish with warty skin, a gaping jaw of needle teeth and a glowing lure on an arched illicium, generated by Kiln"></a><br><b><a href="examples/anglerfish.kiln.js">anglerfish</a></b><br>19,108 tris &middot; Claude Opus 5<br><sub>organic form, and an emissive lure</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/hot-air-balloon.png"><img src="examples/renders/hot-air-balloon.png" alt="a hot-air balloon with a striped envelope and a wicker basket, generated by Kiln"></a><br><b><a href="examples/hot-air-balloon.kiln.js">hot-air-balloon</a></b><br>9,816 tris &middot; Gemini 3.8 Flash<br><sub>a lathed envelope in twenty-four gores</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/vending-machine.png"><img src="examples/renders/vending-machine.png" alt="a lit drinks vending machine behind glass, generated by Kiln"></a><br><b><a href="examples/vending-machine.kiln.js">vending-machine</a></b><br>12,468 tris &middot; Claude Opus 5<br><sub>emissive area as the enemy of shape</sub></td>
+</tr>
+<tr>
+ <td width="33%" valign="top"><a href="examples/renders/gramophone.png"><img src="examples/renders/gramophone.png" alt="an acoustic gramophone with a faceted brass horn on a hinged mahogany case, generated by Kiln"></a><br><b><a href="examples/gramophone.kiln.js">gramophone</a></b><br>10,724 tris &middot; Gemini 3.8 Flash<br><sub>brass against mahogany, and a horn that folds out of a lid</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/typewriter.png"><img src="examples/renders/typewriter.png" alt="a cast-iron typewriter with a fan of type bars, brass trim and a sheet in the platen, generated by Kiln"></a><br><b><a href="examples/typewriter.kiln.js">typewriter</a></b><br>14,128 tris &middot; Muse Spark 1.3<br><sub>a mechanism arrayed on an arc</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/lighthouse.png"><img src="examples/renders/lighthouse.png" alt="a stone lighthouse with a copper-domed lantern, a gallery rail and a keeper&#39;s cottage on a rocky islet, generated by Kiln"></a><br><b><a href="examples/lighthouse.kiln.js">lighthouse</a></b><br>16,492 tris &middot; Muse Spark 1.3<br><sub>a whole small site, not just the tower</sub></td>
+</tr>
+<tr>
+ <td width="33%" valign="top"><a href="examples/renders/steam-locomotive.png"><img src="examples/renders/steam-locomotive.png" alt="a green 4-4-0 steam locomotive with a cowcatcher, brass domes and side rods, generated by Kiln"></a><br><b><a href="examples/steam-locomotive.kiln.js">steam-locomotive</a></b><br>19,256 tris &middot; Muse Spark 1.3<br><sub>coupled wheels, and rods that have to reach them</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/windmill.png"><img src="examples/renders/windmill.png" alt="a Dutch tower windmill in brick with a shingled cap, a stage gallery and four lattice sails, generated by Kiln"></a><br><b><a href="examples/windmill.kiln.js">windmill</a></b><br>9,872 tris &middot; DeepSeek V4 Flash<br><sub>coursing that is a texture, not a stack of rings</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/aircraft-carrier.png"><img src="examples/renders/aircraft-carrier.png" alt="an aircraft carrier with an angled flight deck, deck markings and an island superstructure, generated by Kiln"></a><br><b><a href="examples/aircraft-carrier.kiln.js">aircraft-carrier</a></b><br>17,904 tris &middot; Claude Opus 5<br><sub>a third of a kilometre, laid out by arithmetic</sub></td>
+</tr>
+<tr>
+ <td width="33%" valign="top"><a href="examples/renders/air-defense-radar.png"><img src="examples/renders/air-defense-radar.png" alt="a truck-mounted air-defence phased-array radar with the panel raised, generated by Kiln"></a><br><b><a href="examples/air-defense-radar.kiln.js">air-defense-radar</a></b><br>16,094 tris &middot; Claude Opus 5<br><sub>an array face that is a grid, not a texture</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/fighter-jet.png"><img src="examples/renders/fighter-jet.png" alt="a single-seat multirole fighter on its landing gear with canted tails and open nozzles, generated by Kiln"></a><br><b><a href="examples/fighter-jet.kiln.js">fighter-jet</a></b><br>18,172 tris &middot; Claude Opus 5<br><sub>an aerofoil lofted station by station</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/comms-satellite.png"><img src="examples/renders/comms-satellite.png" alt="a geostationary communications satellite with gold thermal blankets, two solar wings and three dish antennas, generated by Kiln"></a><br><b><a href="examples/comms-satellite.kiln.js">comms-satellite</a></b><br>18,824 tris &middot; Claude Opus 5<br><sub>a 21 m span that still has a 2.6 m bus in it</sub></td>
+</tr>
+<tr>
+ <td width="33%" valign="top"><a href="examples/renders/victorian-greenhouse.png"><img src="examples/renders/victorian-greenhouse.png" alt="a Victorian glasshouse with a curved barrel roof, cast-iron ribs and a brick stylobate, generated by Kiln"></a><br><b><a href="examples/victorian-greenhouse.kiln.js">victorian-greenhouse</a></b><br>10,462 tris &middot; Gemini 3.8 Flash<br><sub>glazing bars as structure, not as a texture</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/gothic-gatehouse.png"><img src="examples/renders/gothic-gatehouse.png" alt="a Gothic castle gatehouse with two drum towers, machicolations and a lowered drawbridge, generated by Kiln"></a><br><b><a href="examples/gothic-gatehouse.kiln.js">gothic-gatehouse</a></b><br>10,428 tris &middot; Gemini 3.8 Flash<br><sub>two drums, one arch, and a bridge that lands</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/cable-stayed-bridge.png"><img src="examples/renders/cable-stayed-bridge.png" alt="a cable-stayed road bridge with a portal pylon and fanned stay cables, generated by Kiln"></a><br><b><a href="examples/cable-stayed-bridge.kiln.js">cable-stayed-bridge</a></b><br>7,580 tris &middot; Omen Alpha<br><sub>a stay pattern that has to reach the deck</sub></td>
</tr>
<tr>
- <td width="33%" valign="top"><a href="examples/renders/lunar-lander.png"><img src="examples/renders/lunar-lander.png" alt="a lunar module on four legs, generated by Kiln"></a><br><b><a href="examples/lunar-lander.kiln.js">lunar-lander</a></b><br>13,208 tris &middot; Claude Opus 5<br><sub>crumpled foil, and asymmetry on purpose</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/fire-lookout-tower.png"><img src="examples/renders/fire-lookout-tower.png" alt="a fire lookout tower with a glazed cab on a braced lattice and a switchback stair, generated by Kiln"></a><br><b><a href="examples/fire-lookout-tower.kiln.js">fire-lookout-tower</a></b><br>4,408 tris &middot; LongCat 2.0<br><sub>a whole tower at four thousand triangles</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/tram.png"><img src="examples/renders/tram.png" alt="a 1920s city tram on rails with a trolley pole reaching up to the overhead wire, generated by Kiln"></a><br><b><a href="examples/tram.kiln.js">tram</a></b><br>12,540 tris &middot; Gemini 3.8 Flash<br><sub>a body that is mostly window</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/tugboat.png"><img src="examples/renders/tugboat.png" alt="a harbour tugboat with a rope fender belt, an orange funnel and a raised wheelhouse, generated by Kiln"></a><br><b><a href="examples/tugboat.kiln.js">tugboat</a></b><br>9,856 tris &middot; Gemini 3.8 Flash<br><sub>a hull lofted station by station</sub></td>
+</tr>
+<tr>
+ <td width="33%" valign="top"><a href="examples/renders/deep-sea-diver.png"><img src="examples/renders/deep-sea-diver.png" alt="an atmospheric diving suit with a copper helmet, jointed limbs and weighted boots, generated by Kiln"></a><br><b><a href="examples/deep-sea-diver.kiln.js">deep-sea-diver</a></b><br>10,876 tris &middot; Gemini 3.8 Flash<br><sub>a figure built out of hardware, not anatomy</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/pumpjack.png"><img src="examples/renders/pumpjack.png" alt="an oilfield pumpjack with a walking beam, horsehead and counterweights on a skid, generated by Kiln"></a><br><b><a href="examples/pumpjack.kiln.js">pumpjack</a></b><br>10,236 tris &middot; Gemini 3.8 Flash<br><sub>a linkage that would actually swing</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/drilling-rig.png"><img src="examples/renders/drilling-rig.png" alt="a land drilling rig with a derrick over its substructure, mud tanks and a pipe rack, generated by Kiln"></a><br><b><a href="examples/drilling-rig.kiln.js">drilling-rig</a></b><br>11,048 tris &middot; Gemini 3.8 Flash<br><sub>a site rather than a silhouette</sub></td>
+</tr>
+<tr>
+ <td width="33%" valign="top"><a href="examples/renders/harbour-crane.png"><img src="examples/renders/harbour-crane.png" alt="a rail-mounted harbour crane with a luffing jib and a spreader on the hoist, generated by Kiln"></a><br><b><a href="examples/harbour-crane.kiln.js">harbour-crane</a></b><br>10,568 tris &middot; Gemini 3.8 Flash<br><sub>steelwork that still reads as steelwork</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/crawler-crane.png"><img src="examples/renders/crawler-crane.png" alt="a lattice-boom crawler crane on tracks with the hook block hanging, generated by Kiln"></a><br><b><a href="examples/crawler-crane.kiln.js">crawler-crane</a></b><br>12,660 tris &middot; MiniMax M3<br><sub>a boom that is one bay, repeated</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/excavator.png"><img src="examples/renders/excavator.png" alt="a tracked hydraulic excavator with the boom, stick and bucket curled in, generated by Kiln"></a><br><b><a href="examples/excavator.kiln.js">excavator</a></b><br>12,400 tris &middot; Omen Alpha<br><sub>rams that line up with the joints they drive</sub></td>
+</tr>
+<tr>
+ <td width="33%" valign="top"><a href="examples/renders/printing-press.png"><img src="examples/renders/printing-press.png" alt="a wooden hand printing press with a screw platen, type cases and ink balls, generated by Kiln"></a><br><b><a href="examples/printing-press.kiln.js">printing-press</a></b><br>10,188 tris &middot; Gemini 3.8 Flash<br><sub>a mechanism you could explain from the render</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/pipe-organ.png"><img src="examples/renders/pipe-organ.png" alt="a church pipe organ with ranks of display pipes above a console and pedalboard, generated by Kiln"></a><br><b><a href="examples/pipe-organ.kiln.js">pipe-organ</a></b><br>10,340 tris &middot; Gemini 3.8 Flash<br><sub>ranks arrayed without becoming a comb</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/planetarium-projector.png"><img src="examples/renders/planetarium-projector.png" alt="a dumbbell planetarium projector with two star globes on a trunnion mount, generated by Kiln"></a><br><b><a href="examples/planetarium-projector.kiln.js">planetarium-projector</a></b><br>10,932 tris &middot; Gemini 3.8 Flash<br><sub>black on black, and still legible</sub></td>
+</tr>
+<tr>
+ <td width="33%" valign="top"><a href="examples/renders/astronomical-clock.png"><img src="examples/renders/astronomical-clock.png" alt="an astronomical clock with a gilt astrolabe dial in a carved stone case, generated by Kiln"></a><br><b><a href="examples/astronomical-clock.kiln.js">astronomical-clock</a></b><br>9,324 tris &middot; Gemini 3.8 Flash<br><sub>a dial carrying the whole asset</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/espresso-machine.png"><img src="examples/renders/espresso-machine.png" alt="a three-group commercial espresso machine with portafilters, steam wands and cups warming on top, generated by Kiln"></a><br><b><a href="examples/espresso-machine.kiln.js">espresso-machine</a></b><br>19,080 tris &middot; GLM 5.3 Flash<br><sub>chrome, which is the hardest thing to shade</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/pinball-machine.png"><img src="examples/renders/pinball-machine.png" alt="a pinball machine with a lit backbox, a glassed playfield and a rear cabinet bay, generated by Kiln"></a><br><b><a href="examples/pinball-machine.kiln.js">pinball-machine</a></b><br>8,700 tris &middot; GLM 5.3 Flash<br><sub>a head that has to stand on something</sub></td>
+</tr>
+<tr>
+ <td width="33%" valign="top"><a href="examples/renders/trebuchet.png"><img src="examples/renders/trebuchet.png" alt="a counterweight trebuchet with a slung beam, a ballast box and the sling laid out on the ground, generated by Kiln"></a><br><b><a href="examples/trebuchet.kiln.js">trebuchet</a></b><br>2,652 tris &middot; Gemini 3.8 Flash<br><sub>a siege engine in 2,652 triangles</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/rigid-airship.png"><img src="examples/renders/rigid-airship.png" alt="a 1930s rigid passenger airship moored at its mast, with a promenade window row, engine cars and a cruciform tail, generated by Kiln"></a><br><b><a href="examples/rigid-airship.kiln.js">rigid-airship</a></b><br>11,764 tris &middot; GPT-6 Astra<br><sub>one lofted envelope, with everything hung off it</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/orbital-station.png"><img src="examples/renders/orbital-station.png" alt="a rotating-torus orbital station with lit window bands, four spokes, a docking hub and solar wings, generated by Kiln"></a><br><b><a href="examples/orbital-station.kiln.js">orbital-station</a></b><br>10,212 tris &middot; GPT-6 Astra<br><sub>a ring that has to close on itself</sub></td>
+</tr>
+<tr>
+ <td width="33%" valign="top"><a href="examples/renders/blast-furnace.png"><img src="examples/renders/blast-furnace.png" alt="a blast furnace with three hot-blast stoves, downcomer piping, galleries and a cast house, generated by Kiln"></a><br><b><a href="examples/blast-furnace.kiln.js">blast-furnace</a></b><br>11,964 tris &middot; GPT-6 Astra<br><sub>a plant rather than an object</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/clock-tower.png"><img src="examples/renders/clock-tower.png" alt="a Gothic clock tower with gilt dials, a louvred belfry, crocketed pinnacles and a leaded spire, generated by Kiln"></a><br><b><a href="examples/clock-tower.kiln.js">clock-tower</a></b><br>11,664 tris &middot; GPT-6 Astra<br><sub>four faces that have to agree</sub></td>
</tr>
</table>
-Every shot above is regenerated by `bun scripts/hero-shots.ts`, straight from the checked-in
-programs through the same PBR render port the agent loop uses. Nothing in this README was
-retouched.
+Every shot is regenerated by `bun scripts/hero-shots.ts` straight from those programs, through the
+same PBR render port the agent loop uses. Nothing in this README was retouched.
+
+A still is a weak claim about a mesh, so all fifty are also up at
+**[the specimen gallery](https://matthew-kissinger.github.io/kiln/)**, where you can orbit them,
+flip them to wireframe to see the topology under the shading, and pull the GLB down to open in
+whatever you use. That page holds no assets either: its build runs the same programs through the
+same evaluator, so what you orbit there is what the file beside it produces today rather than an
+export somebody remembered to refresh. It lives in [`site/`](site).
+
+A gallery is thin evidence when it is all one model's work, so it is worth saying who wrote what.
+35 of the 50 programs above were not written by Claude. Gemini 3.8 Flash wrote 21 of them through
+the Antigravity CLI and GPT-6 Astra wrote 4 through Codex; Muse Spark 1.3 wrote 3, GLM 5.3 Flash
+and Omen Alpha 2 each, and there is 1 apiece from DeepSeek V4 Flash, MiniMax M3 and LongCat 2.0.
+The rest came through OpenCode, bar the fire lookout tower, which came out of Hermes -- a Python
+agent with its own config, its own skill store and its own provider routing, and the one harness
+here that is nothing like Claude Code.
+
+Every one of those runs was dispatched into a directory holding nothing but the brief and the Kiln
+skills: no engine source, and no finished example to copy an interface from. Nothing in the tools
+or the skills changed for any of them, which is the claim the gallery is really making. The loop
+belongs to neither the model nor the harness it was built in, and it does not need the model to
+have read this repository first.
+
+## And they move
+
+`animate()` is part of the same program. It returns named clips built from rotation and position
+tracks against the parts the program already created, so a joint that moves is the joint that was
+modelled -- there is no separate rig to keep in sync, and a diff of the motion is a diff of the same
+file. The model reviews a clip the way it reviews a still: `kiln_screenshot_animation` poses the
+scene across the clip and hands back the frames, which is how a walk that slides, a knee that bends
+backwards, or an arm that swings through its own base gets caught before the GLB is written.
+
+<table>
+<tr>
+ <td width="50%" valign="top"><img src="examples/renders/robot-arm.gif" alt="an industrial robot arm running a pick-and-place cycle"><br><b><a href="examples/robot-arm.kiln.js">robot-arm</a></b><br><sub>a six-axis pick-and-place cycle</sub></td>
+ <td width="50%" valign="top"><img src="examples/renders/carousel.gif" alt="a fairground carousel turning, with horses rising and falling"><br><b><a href="examples/carousel.kiln.js">carousel</a></b><br><sub>a turn, with the horses on their own phase</sub></td>
+</tr>
+<tr>
+ <td width="50%" valign="top"><img src="examples/renders/orrery.gif" alt="an orrery with planets orbiting a lit sun"><br><b><a href="examples/orrery.kiln.js">orrery</a></b><br><sub>planets on nested arms off one drive</sub></td>
+ <td width="50%" valign="top"><img src="examples/renders/radio-telescope.gif" alt="a radio telescope dish slewing in azimuth and elevation"><br><b><a href="examples/radio-telescope.kiln.js">radio-telescope</a></b><br><sub>a slew in azimuth and elevation</sub></td>
+</tr>
+</table>
-The arcade cabinet is the one that matters most here. It was authored end to end by a **different
-vendor's model in a different harness** — Gemini 3.8 Flash driving the same plugin through the
-Antigravity CLI — with no changes to the tools or the skills. The loop is not Claude-specific.
+These are rendered by `bun scripts/anim-gifs.ts` from the checked-in programs, through the same PBR
+port as the stills. One detail in that script is worth borrowing if you build something similar: the
+port fits its camera to whatever bounding box it is handed, so a sequence whose posed extent changes
+-- the arm above varies by 63% between folded and reaching -- will appear to breathe as the camera
+refits every frame. Because the projection is orthographic and the fit is exact, each frame can be
+put back onto one shared camera by a scale and a translation that are both computable, which is a
+correction rather than an approximation.
![Six-view contact sheet of a procedurally generated field gun](examples/hero-sheet.png)
-*The contact sheet the model looks at — `examples/field-gun.kiln.js`, 15,544 triangles: a revolved
+*The contact sheet the model looks at. `examples/field-gun.kiln.js`, 15,544 triangles: a revolved
bronze barrel bored with a boolean, a stepped oak carriage carrying strapwork and bolt heads, and
-twelve-spoke wheels with iron tyres:*
-`bun run kiln render examples/field-gun.kiln.js --views sheet.png`
-
-## What this is
-
-A working reference implementation of an agent loop that can **see its own work**:
+twelve-spoke wheels with iron tyres.*
-```
-list primitives -> write program -> validate (AST) -> render -> look at six views -> fix -> finalize
+```bash
+bun run kiln render examples/field-gun.kiln.js --views sheet.png
```
-The interesting parts are architectural, and they generalize past 3D:
-
-- **One tool definition, two transports.** [`src/tools/registry.ts`](src/tools/registry.ts) is the
- single source of truth. The in-process Strands skin and the MCP server both iterate it, so tool
- names and schemas cannot drift apart.
-- **Deterministic gates, kept separate from model judgment.** Self-intersection, part connectivity,
- and AST validation all fail closed with no model call. `QaContext` is deliberately image-free so a
- QA rule *structurally cannot* read a render buffer.
-- **A render port with a fail-closed degrade.** `captureViewsViaPort` owns the deadline, PNG
- validation, grid composition, and a never-throw fallback. Renderers are swappable; correctness
- does not depend on which one ran.
-- **Budgets and compaction** as first-class concerns, because agent loops that render images run
- out of context and money.
-
-## What this is not
-
-- **Not photoreal reconstruction.** Output is stylized to mid-fidelity procedural geometry. If you
- want a scanned-looking mesh, use a diffusion model — Trellis, Hunyuan3D and friends are better at
- that, and it isn't close.
-- **Not a mesh generator.** No diffusion, no photogrammetry, no point cloud. A model writes code;
- the code builds geometry.
-- **Not novel in category.** [img2threejs](https://github.com/img2threejs/img2threejs) is an
- architectural peer running the same essential loop. Kiln differs in being TypeScript/Strands, in
- running its vision loop with no browser required, and in its deterministic gate layer.
-- A single reference view cannot reveal hidden sides. Assets are inferred, not measured.
+## What this does that asking your agent directly does not
+
+Any coding agent will cheerfully write you a Three.js scene of a motorcycle. It writes it in one
+pass, never sees the result, and reports success. The failure mode is not bad code, it is confident
+code about geometry nobody looked at: a front mudguard sunk inside the tyre it is meant to arch over,
+an exhaust routed into the engine instead of out the back, a robot arm whose pick pose reaches
+upward. All three of those are in this repository's example headers, because they happened and the
+loop caught them.
+
+Kiln closes that loop, and then declines to trust it on its own.
+
+The model gets eyes. `kiln_render` builds the program, exports the GLB, and returns the metrics and
+the six-view contact sheet in one tool result, so looking costs a single call rather than a detour
+through a file the agent cannot open. Every render also reports `viewFidelity`, which tells the agent
+in band whether it may judge material from what it is looking at or only geometry. An agent that
+cannot see a texture must not conclude the texture is wrong.
+
+What vision is bad at gets checked by machine instead. Self-intersection, part connectivity, floating
+geometry, degenerate and non-unit normals, triangle budget, and glTF validity all fail closed with no
+model call, and the QA context is deliberately image-free so a rule *structurally cannot* read a
+render buffer. No render will ever show you a normal of length 0.9994. The validator rejects it on
+sight, and that matters because the exporters downstream will too.
+
+The model reads the catalog before it writes anything. `kiln_list_primitives` returns the real
+signatures, so the program is written against the API that exists rather than the one the model
+half-remembers from some other engine. That one step is the difference between a run that compiles
+and a run that burns four turns failing on names.
+
+And what comes out is contracted, not merely valid. Metres, +Y up, sitting on the ground plane at
+y=0, materials drawn from a palette chosen for instancing, a triangle count that lands where the
+gallery lands, and a versioned `integrationManifest` sidecar carrying the artifact hash, bounds,
+grounding offset, semantic role, and structural QA. Drop the file into a scene and it is the right
+size, the right way up, and standing on the floor.
+
+## Where it works and where it does not
+
+Kiln is good at things that were manufactured. A form that comes from a profile turned on a lathe, a
+plate bent to a radius, a frame welded out of tube, or one bay repeated the length of a nave is a
+form you can describe as a program, and a program is what Kiln writes. That covers more of an art
+list than it sounds like: vehicles, aircraft and ships; ordnance and defence hardware; machinery,
+instruments and tooling; furniture, fittings and shop dressing; architecture and the modular kit
+pieces buildings are assembled out of; and the long tail of props that fill a level and never get a
+close-up. The gallery is deliberately all of that.
+
+It is at its best when you want many of them. A program with numbers in it is already a family, so
+the second crate is a parameter rather than another generation, and a street's worth of lamps is one
+casting with different arm lengths. That is also where the loop pays for itself: authoring is minutes
+of unattended wall clock, and the marginal variant is a rerun. Dispatching a batch of them without
+supervision is a documented path further down this page, not an aspiration.
+
+It is bad at things that grew. Faces, hands, cloth, foliage, anything with muscle under the skin all
+want a sculpt, and the honest recommendation there is a diffusion model. Trellis, Hunyuan3D and their
+successors will beat this outright, and it is not close.
+
+It is also not reconstruction. Given one reference image, Kiln infers the sides it cannot see rather
+than measuring them. If you need *that* object rather than something like it, reach for
+photogrammetry or a scanner.
+
+The economics differ too, and it is worth being plain about it. A mesh sampler answers in seconds.
+Kiln spends minutes, because looking is the expensive part and looking is the entire point. What
+those minutes buy is that the cost does not come back. Edit the wheel radius, rerun, and you get the
+same motorcycle with bigger wheels; regenerate a sampled mesh and you get a different motorcycle.
+The second version of a Kiln asset is a diff, and the hundredth variant of it is a loop.
+
+Code-as-geometry with a model in the loop is not a category Kiln invented, and there are other
+projects in it. What is unusual here is the shape of the loop rather than the idea of it: the vision
+pass has no browser anywhere in it, so it runs in a container and in CI; and the model's judgment
+sits on top of a deterministic gate layer that never sees pixels, so a confident wrong answer cannot
+promote a broken asset.
+
+## Where the tokens go
+
+Most of what an agent spends on 3D is not spent on the object. It guesses at an API and reads the
+errors back, renders into a file it has no way to open, narrates the geometry to itself in prose
+because narration is all it has, and re-derives on every asset the same things it worked out on the
+last one. Those turns are expensive and most of them carry an image, and none of them is the model
+thinking about the shape.
+
+Kiln pays that discovery once, up front, and keeps it out of the loop. The primitive catalog is a
+single call that returns real signatures, so the program is written against the API that exists
+rather than the one the model half-remembers from some other engine. Looking is a single call too:
+`kiln_render` builds the program, exports the GLB, rasterizes six views, and returns the contact
+sheet and the metrics in one tool result, so a revision costs one look instead of a render, a file
+write, a read that fails, and a paragraph of speculation. The deterministic gates cost no model
+tokens at all, because self-intersection, floating parts, non-unit normals, triangle budget and glTF
+validity are all decided in process and their context is image-free by construction. And a fix is a
+patch rather than a rewrite: `kiln_edit` replaces exact strings and re-renders, so the tenth revision
+does not re-emit the first nine.
+
+What sits in context permanently is small, and it is measured rather than asserted. The seven tool
+schemas derive to 15,839 characters of JSON Schema, call it four thousand tokens. The five skills
+advertise themselves in 1,698 characters of front matter, four hundred more; their bodies come to
+about eight thousand tokens between them and load only when one of them actually fires. Everything
+else a model would otherwise have to be told about building an asset lives in the engine, where it
+is executed rather than read.
+
+The wall clock is honest about the trade. An unattended dispatch of a mid-sized asset lands between
+two and six minutes on one machine, and thirteen for the carrier at the end of the gallery, which is
+a third of a kilometre long and has the part count to match. Several of the assets above were
+authored exactly that way, in a batch nobody watched.
## Quickstart
-**No API key required.** Render an existing Kiln program and look at the result:
+No API key required. Render one of the checked-in programs and look at the result:
```bash
git clone https://github.com/matthew-kissinger/kiln && cd kiln
@@ -92,8 +278,8 @@ bun run kiln render examples/crate.kiln.js --out crate.glb --views sheet.png
```
That exercises the geometry build, the QA gates, and the rasterizer with no model and no key. The
-default `--render auto` briefly looks for a local GPU render service and falls back to the CPU
-rasterizer when there is none, so this works unchanged on a machine with no GPU.
+default `--render auto` glances for a local GPU render service and falls back to the CPU rasterizer
+when there is none, so it works unchanged on a machine with no GPU.
To generate from a prompt, set one provider key and:
@@ -101,10 +287,211 @@ To generate from a prompt, set one provider key and:
bun run kiln generate "a weathered wooden crate" --out crate.glb
```
-## Rendering: three modes
+## Install it in your agent
+
+Kiln ships as an [Agent Plugin](https://agentplugins.codes/): an MCP server exposing the tool
+surface, alongside five skills that teach an agent to use it well, covering authoring an asset,
+refining one that already exists, composing finished assets into a scene, proving one works inside a
+real project, and wiring another harness up to generate a library at scale. Pick your harness below; [`docs/install.md`](docs/install.md) has the long
+form, including the sharp edges.
+
+Every route starts with a clone and its dependencies, because the engine ships TypeScript source
+rather than a published package:
+
+```bash
+git clone https://github.com/matthew-kissinger/kiln && cd kiln && bun install
+bun run kiln render examples/crate.kiln.js --out crate.glb --views sheet.png
+```
+
+If that writes a GLB and a contact sheet, the engine is fine and anything that goes wrong afterwards
+is transport configuration.
+
+**The server your harness launches runs on Node, not Bun.** `dist/mcp-server.mjs` is a committed
+bundle, because a plugin install is a git clone with no build step, and it is what every config
+below points at. Bun is the development toolchain here; it is not something a user of the plugin
+needs on their `PATH`. That distinction is not cosmetic -- it is the fix for a real bug, and
+[`src/__tests__/mcp-bundle.test.ts`](src/__tests__/mcp-bundle.test.ts) rebuilds the bundle, compares
+it byte for byte, and then speaks MCP to it under `node` so it cannot rot.
+
+<details>
+<summary><b>Claude Code</b></summary>
+
+```bash
+claude plugin marketplace add matthew-kissinger/kiln
+claude plugin install kiln@kiln
+```
+
+Verify with `claude mcp list`, where you want `plugin:kiln:kiln … ✔ Connected`.
+</details>
+
+<details>
+<summary><b>Antigravity CLI (<code>agy</code>)</b></summary>
+
+Two commands, because they do different jobs:
+
+```bash
+agy plugin install .
+agy mcp add --env KILN_RENDER=auto kiln node /absolute/path/to/kiln/dist/mcp-server.mjs
+```
+
+The first brings in the skills. The second is not redundant: as of `agy` 1.1.25, installing a
+plugin does **not** register the MCP servers it declares. `agy plugin validate .` will happily
+report `mcpServers: 1 processed` while `agy mcp list` reports `No MCP servers configured`, and the
+agent sees no tools. `agy mcp add` is the supported registration and writes the entry itself, so
+there is no JSON to hand-edit. Confirm with `agy mcp list`.
+
+For headless (`agy -p`) runs you also need permission grants in
+`~/.gemini/antigravity-cli/settings.json`. Scoped `mcp()` and `write_file()` rules work; `command()`
+targets are soft-denied in print mode whatever the syntax, so only `command(*)` passes. See
+[`docs/install.md`](docs/install.md#headless-permissions) for the evidence and the upstream issue.
+</details>
+
+<details>
+<summary><b>OpenCode</b></summary>
+
+OpenCode has no plugin manifest to install -- its plugins are JavaScript modules, which is a
+different thing entirely -- so Kiln arrives as an MCP server plus skills, and both are one-time
+edits. Put this in `~/.config/opencode/opencode.json`, or in an `opencode.json` at your project
+root:
+
+```json
+{
+ "$schema": "https://opencode.ai/config.json",
+ "mcp": {
+ "kiln": {
+ "type": "local",
+ "command": ["node", "/absolute/path/to/kiln/dist/mcp-server.mjs"],
+ "enabled": true,
+ "environment": { "KILN_RENDER": "auto" },
+ "timeout": 30000
+ }
+ }
+}
+```
+
+Three details differ from every other client on this page and each one fails silently if you carry
+a config over unchanged: the key is `mcp` rather than `mcpServers`, the type is `local` rather than
+`stdio`, and the command and its arguments are a single array rather than a `command` plus `args`.
+The schema rejects unknown keys, so a stray `env` is not ignored, it is an error.
+
+`timeout` bounds the connection handshake, not the tool calls that follow, which is the opposite of
+what the name suggests. Set to 200 ms the server never connects and `opencode mcp list` reports
+`kiln failed`; set to 1500 ms it connects, and a `kiln_render` that takes nine seconds still comes
+back with its picture. The handshake itself measures around 1.2 seconds against a default of five,
+so the default works and an explicit value only buys headroom for a cold start.
+
+Verify with `opencode mcp list`, where you want `kiln connected`.
+
+The skills are the second half, and OpenCode reads Anthropic's `SKILL.md` layout directly. Copy them
+to `~/.config/opencode/skills/` for every project, or to `.claude/skills/` inside one -- OpenCode
+looks in both, along with `.agents/skills/`:
+
+```bash
+cp -r skills/* ~/.config/opencode/skills/
+```
+
+One cosmetic surprise: OpenCode namespaces tools by server, so `kiln_render` is presented to the
+model as `kiln_kiln_render`. Nothing needs changing, and models find the tools anyway, but it is
+what you will see in the transcript.
+</details>
+
+<details>
+<summary><b>Hermes</b></summary>
+
+Hermes is a Python agent with its own YAML config, its own skill store and its own provider routing,
+which makes it the honest test of whether any of this is portable rather than Claude-Code-shaped.
+Two commands attach both halves:
+
+```bash
+hermes mcp add kiln --command node --args /absolute/path/to/kiln/dist/mcp-server.mjs --env KILN_RENDER=auto
+hermes config set skills.external_dirs /absolute/path/to/kiln/skills
+```
+
+The first connects immediately, prints the seven tools it found and asks whether to enable them. The
+second is how Hermes finds skills at all: it reads a list of absolute directories out of its config
+rather than `.claude/skills` out of the working directory, so pointing it at this repository is the
+whole step. `hermes mcp list` and `hermes skills list` confirm both halves landed.
+
+Hermes ships with no model provider, so a fresh install fails on `No inference provider configured`
+before the brief is ever read -- which reads exactly like a broken plugin and is not one.
+[`docs/install.md`](docs/install.md) has the login and the follow-up that catches everybody out.
+</details>
+
+<details>
+<summary><b>Codex CLI</b></summary>
+
+Codex keeps its MCP servers in TOML at `~/.codex/config.toml`, and the path has to be absolute:
+
+```toml
+[mcp_servers.kiln]
+command = "node"
+args = ["/absolute/path/to/kiln/dist/mcp-server.mjs"]
+env = { KILN_RENDER = "auto" }
+```
+
+That is the whole of it for interactive `codex`, which asks before each tool call. `codex exec` is
+the one that needs a flag: it pins the approval policy to `never`, and a `never` policy refuses an
+MCP call rather than queueing it, so a scripted run comes back in under a minute reporting that
+`kiln_list_primitives` was blocked and having written nothing. Add `--approve-for-me`, which routes
+approvals through automatic review and picks the workspace-write sandbox itself -- which is also why
+it is rejected alongside `--sandbox`.
+</details>
+
+<details>
+<summary><b>Cursor, Zed, or any MCP client</b></summary>
+
+Point the client at the bundle with an **absolute** path. The server resolves its own paths from
+`import.meta.url` and never reads `process.cwd()`, so the launch directory does not matter:
+
+```json
+{
+ "mcpServers": {
+ "kiln": {
+ "type": "stdio",
+ "command": "node",
+ "args": ["/absolute/path/to/kiln/dist/mcp-server.mjs"],
+ "env": { "KILN_RENDER": "auto" }
+ }
+ }
+}
+```
+</details>
+
+<details>
+<summary><b>In-process TypeScript, no MCP</b></summary>
-Kiln renders the views the model looks at, and there are three ways to do it. All three are in this
-repository; none requires a cloud account.
+```ts
+import { createKilnToolRegistry } from 'kiln/tools';
+```
+
+`kiln/tools` imports no agent SDK, so porting to a harness that is not Strands does not drag Strands
+along. [`examples/strands-harness.ts`](examples/strands-harness.ts) is the whole integration in about
+sixty lines.
+</details>
+
+Whichever route you took, check it before you judge anything by the assets it produces:
+
+```bash
+bun run smoke:harness
+```
+
+That sends a short brief into a throwaway directory for every CLI it finds -- call one tool, write a
+four-line program, validate it -- and then builds what came back with the engine rather than
+believing the agent's own account of how it went. It matters because every wiring failure here is
+silent. A harness that cannot see the server does not say so, one that can see it but will not grant
+it behaves the same way, and so does a model that simply was not up to the job. Three different
+problems, one symptom, and no way to tell them apart by looking at a bad asset.
+
+The MCP server exposes the **raw tools**, which means *your* agent is the author. It writes the
+program, looks at the render, and iterates using its own model, with no separate provider key and no
+nested agent loop. The trade is that your harness then supplies both the author and the vision judge:
+the deterministic gates still run independently, but the eyes/judge separation the production system
+maintained is collapsed. That is deliberate, and it is what buys the portability.
+
+## Seeing the work: CPU and GPU
+
+There are two renderers in this repository, and the mode picks between them. Neither wants a cloud
+account.
```bash
--render auto # default: local GPU service if one is up, else CPU
@@ -115,29 +502,25 @@ repository; none requires a cloud account.
### What the difference actually looks like
-The same program — the field gun above — rendered both ways:
+The same program, the field gun above, rendered both ways:
| CPU rasterizer | GPU PBR |
|---|---|
| ![Field gun flat-shaded, every material rendering as white plastic](examples/gun-cpu.png) | ![The same gun with oak, iron and bronze all reading distinctly](examples/gun-gpu.png) |
Geometry is equally legible in both. On the CPU sheet you can still count the twelve spokes, see the
-bolt heads on the cheek straps, and read the stepped carriage — silhouette, proportion, orientation
-and part contact all survive intact.
+bolt heads on the cheek straps, and read the stepped carriage; silhouette, proportion, orientation and
+part contact all survive intact.
What does not survive is every material cue in the asset. The oak carriage, the iron tyres, and the
-bronze barrel render as **the same white plastic**. Not dimmer — *absent*. The procedural albedo and
+bronze barrel render as **the same white plastic**. Not dimmer, *absent*. The procedural albedo and
the derived normal maps that separate weathered wood from gun-metal simply do not exist in a
-flat-shaded render, so an agent looking at the left-hand sheet has no way to tell that this asset has
-three materials at all.
-
-**If your assets have textures or metal, use the GPU.** That is most real assets, and it is why
-`auto` reaches for a GPU first. The CPU rasterizer is the floor that guarantees the loop runs
-anywhere — CI, a container, a laptop with no GPU — not the target.
+flat-shaded render, so an agent looking at the left-hand sheet has no way to tell this asset has three
+materials at all.
-This is also why every render reports `viewFidelity`. When `materialFaithful` is false the agent is
-told, in band, that it may judge geometry and **not** material. An agent that cannot see a texture
-must not conclude the texture is wrong.
+**If your assets have textures or metal, use the GPU.** That is most real assets, and it is why `auto`
+reaches for a GPU first. The CPU rasterizer is the floor that guarantees the loop runs anywhere, in
+CI, in a container, on a laptop with no GPU. It is not the target.
| | CPU raster | GPU PBR |
|---|---|---|
@@ -157,7 +540,7 @@ cd render-service && npm install && npm start
```
That is **gpu (local)**. It listens on `:8000`, which is where `--render auto` looks, so nothing else
-needs configuring — the next `kiln render` picks it up and says so:
+needs configuring. The next `kiln render` picks it up and says so:
```
sheet.png (GPU dawn-d3d12:nvidia-geforce-rtx-3070:D3D12 driver version 32.0.16.1074)
@@ -174,128 +557,225 @@ will not start rather than one that silently renders on CPU and lies about it.
With nothing reachable, `auto` falls back to the CPU rasterizer, which is why a machine with no GPU
needs no configuration at all. `captureViewsViaPort` owns the deadline, PNG validation, grid
-composition, and a never-throw fallback: a slow or broken renderer costs fidelity, never correctness.
+composition, and a never-throw fallback, so a slow or broken renderer costs fidelity and never
+correctness.
-**The GPU is a view producer only — it is never gate evidence.** QA rules never see pixels.
+**The GPU is a view producer only. It is never gate evidence,** and QA rules never see pixels.
-## Install it in your agent
+## Materials, and where the pixels come from
-Kiln ships as an [Agent Plugin](https://agentplugins.codes/): an MCP server exposing the tool
-surface, plus three skills that teach an agent how to use it well. Pick your harness below;
-[`docs/install.md`](docs/install.md) has the long form, including the sharp edges.
+Nothing in this pipeline samples an image model, textures included. There are two ways a surface gets
+its detail, and a model authoring an asset reaches for both in the same program.
+
+The first is **procedural**: a declarative stack of layers the model writes out as data, which the
+engine rasterizes into a texture.
-Everything needs [Bun](https://bun.sh) on `PATH` and a clone, because the package ships TypeScript
-source rather than a build artifact:
+```js
+const brick = proceduralTexture({
+ schemaVersion: 2,
+ size: 256,
+ usage: 'albedo',
+ layers: [
+ { op: 'bricks', brick: 0x8c4a32, mortar: 0xbfb6a8, rows: 12, cols: 6, mortarWidth: 0.08 },
+ { op: 'noise', colorA: 0x000000, colorB: 0x604030, scale: 24, octaves: 4, seed: 7,
+ blend: 'multiply', opacity: 0.35 },
+ ],
+});
+
+const wall = pbrMaterial({ albedo: brick, normal: normalMapFromHeight(brick), roughness: 0.9 });
+```
+
+Six operations compose the whole space: `solid`, `checker`, `stripes`, `gradient`, `bricks`, and
+tileable `noise`. Each layer carries a blend mode and an opacity, up to eight layers deep, and
+`normalMapFromHeight` derives relief from any of it, which is where most of the surface read actually
+comes from. That is a small vocabulary on purpose, and it is deliberately *not* the obvious API. The
+obvious API hands the model a per-pixel callback, and a callback is arbitrary code with arbitrary cost
+and no reviewable record of what it drew. A layer stack is bounded before a single pixel is written,
+recorded verbatim in the asset's provenance, and reproducible from the manifest alone. Noise hashes
+the lattice coordinate with a seed rather than calling `Math.random`, and wraps at the cell period, so
+the same program produces the same bytes on every machine and a wall does not show a seam where the
+pattern restarts.
+
+The second is the **scanned library**: sixteen [Poly Haven](https://polyhaven.com) CC0 families, each
+shipping an albedo map, an OpenGL normal map, and a packed ambient-occlusion / roughness / metalness
+map. Bark, planks, finished oak veneer, concrete, brick, cobblestone, clay roof tiles, marble, rock
+face, dry soil, denim, leather, forest leaf litter, rubber, steel plate, and rust. They are embedded
+in the package at 128px, which keeps the whole library under a megabyte, and the model binds one by
+its `kiln.texture.*` ID rather than by a path or a URL. That identifier is checked against a closed
+registry, so an invented ID is a validation error rather than a silent miss, and a generated asset
+never reaches for the network at runtime.
+
+Which one to use is not a toss-up. Procedural wins for anything regular and man-made where the model
+knows the actual dimensions: brickwork, panelling, tiling, painted stripes, plate seams. The library
+wins for organic irregularity, where a layer stack produces something that reads as generated and a
+photograph does not: bark, soil, leaf litter, worn leather. Most convincing surfaces use both, with
+the photograph as the base and procedural layers over it for wear specific to *this* object.
+
+**Neither path is a diffusion model, and that is a boundary rather than a gap.** A texture computed
+from numbers has no third-party provenance to track and no licence to propagate; a scanned family has
+one licence, recorded once, in a file you can read. Both are byte-reproducible, which is what lets the
+repository pin texture fixtures at all. Sampling a texture at authoring time would trade all three of
+those away for surfaces the two existing paths already cover, and it would put a network call and a
+provider key inside a loop whose entire claim is that it needs neither. Expanding the scanned library
+is a networked, opt-in curation script that runs offline and checks its output in; that is the seam
+where new pixels enter, and it is deliberately not the seam where assets are made.
+
+## Dispatching a headless agent
+
+Once Kiln is attached to a CLI harness, that harness can be driven headlessly, which means an agent
+you are already talking to can spawn a second agent whose entire job is to build one asset and hand
+back a GLB. This is the useful shape for batch work: ten assets, ten child agents, a cheaper model
+doing the grunt work while your main session stays on the thing you care about.
+
+The recipe is one line, and it is the same line for every harness:
```bash
-git clone https://github.com/matthew-kissinger/kiln && cd kiln && bun install
-bun run kiln render examples/crate.kiln.js --out crate.glb --views sheet.png
+# Antigravity CLI, verified end to end with Gemini 3.8 Flash and 3.1 Pro
+agy --model gemini-3.8-flash-high --print-timeout 25m --add-dir /abs/path/to/sandbox \
+ --print="Read /abs/path/to/brief.txt and carry out the instructions in it exactly."
+
+# Claude Code
+claude -p "Read /abs/path/to/brief.txt and carry out the instructions in it exactly." \
+ --model sonnet --permission-mode acceptEdits --add-dir /abs/path/to/sandbox
+
+# Codex CLI, where --approve-for-me is what lets it call the tools at all
+codex exec --approve-for-me --skip-git-repo-check --cd /abs/path/to/sandbox "Read /abs/path/to/brief.txt and carry out the instructions in it exactly."
+
+# OpenCode, which reaches a dozen vendors' models behind provider/model ids
+opencode run --auto --dir /abs/path/to/sandbox -m opencode-go/glm-5.3-flash "Read /abs/path/to/brief.txt and carry out the instructions in it exactly."
```
-If that writes a GLB and a contact sheet, the engine is fine and anything that goes wrong later is
-transport configuration.
+That Codex flag is the one non-obvious item in the block. `codex exec` pins its approval policy to
+`never`, and under that policy an MCP call is refused rather than queued, so a run reports that
+`kiln_list_primitives` was blocked and writes nothing at all. `--approve-for-me` moves approval to
+automatic review and selects the workspace-write sandbox itself, which is why it cannot be combined
+with `--sandbox`.
-<details>
-<summary><b>Claude Code</b></summary>
+[`scripts/dispatch-asset.mjs`](scripts/dispatch-asset.mjs) wraps that, composes the brief, and then
+**verifies the result with the engine rather than with the child's own report**:
```bash
-claude plugin marketplace add matthew-kissinger/kiln
-claude plugin install kiln@kiln
+node scripts/dispatch-asset.mjs --name water-tower \
+ "an American small-town steel water tower on a riveted lattice frame"
+
+node scripts/dispatch-asset.mjs --harness claude --model sonnet --name anglerfish \
+ "a deep-sea anglerfish with a glowing lure"
```
-Verify with `claude mcp list` — you want `plugin:kiln:kiln … ✔ Connected`.
-</details>
+It writes `<name>.kiln.js`, `<name>.glb`, the six-view sheet, the exact brief it sent, and the child's
+transcript into `.dogfood/`, then exits non-zero if `kiln render` refuses the result.
-<details>
-<summary><b>Antigravity CLI (<code>agy</code>)</b></summary>
+### Pick a model that can see
+
+Kiln's loop is the model looking at its own render, so the one capability that is not optional is
+image input. A text-only model still produces a file -- it writes blind, from the API documentation
+alone -- and it produces a noticeably worse one for a reason that is easy to misread as the model
+being weak.
-The portable `plugin.json` is accepted unchanged:
+This is worth a preflight rather than a guess. A nine-model batch here turned out to have four
+text-only models in it, chosen by name from a provider list on the assumption that a current
+flagship accepts images; nothing in the run said otherwise, and the resulting assets were quietly
+not evidence of anything. Note also that vision can differ between a vendor's variants, which is the
+sort of thing you find by checking rather than by reasoning: `glm-5.3-flash` sees images and plain
+`glm-5.3` does not.
```bash
-agy plugin install .
+node scripts/check-vision.mjs opencode-go/kimi-k3 opencode-go/glm-5.3
+# opencode-go/kimi-k3 sees images
+# opencode-go/glm-5.3 TEXT ONLY
```
-Then register the server in `~/.gemini/config/mcp_config.json` with an **absolute** path, because
-Antigravity has no plugin-root variable:
+It exits non-zero and names the offenders, so a batch script can refuse to start.
-```json
-{
- "mcpServers": {
- "kiln": {
- "command": "bun",
- "args": ["/absolute/path/to/kiln/src/mcp-server.ts"],
- "env": { "KILN_RENDER": "auto" }
- }
- }
-}
-```
+### The child gets a clean room
-For headless (`agy -p`) runs you also need permission grants in
-`~/.gemini/antigravity-cli/settings.json`. Scoped `mcp()` and `write_file()` rules work; `command()`
-targets are soft-denied in print mode whatever the syntax, so only `command(*)` passes — see
-[`docs/install.md`](docs/install.md#headless-permissions) for the evidence and the upstream issue.
-</details>
+Each dispatch runs in a directory of its own containing exactly two things: the brief, and the five
+Kiln skills. Not the engine source, not `AGENTS.md`, and above all not `examples/`.
-<details>
-<summary><b>Cursor, Codex CLI, Zed, or any MCP client</b></summary>
+That last one is the point. These runs are the evidence behind the claim that the tools teach the
+API, and for a while they were not evidence of much, because the harness was pointed at this
+repository and a child agent could open every finished program in `examples/` and copy an interface
+it never had to learn. An asset built that way demonstrates that the model can read. Scoping the write grant
+to the sandbox and starting the child inside it is what makes the result mean what it claims to.
-Point the client at `src/mcp-server.ts` with an **absolute** path. The server resolves its own paths
-from `import.meta.url` and never reads `process.cwd()`, so the launch directory does not matter:
+The directory sits in the OS temp area rather than under `.dogfood/`, which matters more than it
+looks like it should. Every CLI here finds the project it is working in by walking up from the
+working directory to the nearest `.git`, so a sandbox nested inside the repository resolves straight
+back to the repository and isolates nothing at all.
-```json
-{
- "mcpServers": {
- "kiln": {
- "type": "stdio",
- "command": "bun",
- "args": ["run", "/absolute/path/to/kiln/src/mcp-server.ts"],
- "env": { "KILN_RENDER": "auto" }
- }
- }
-}
-```
-</details>
+What this does not isolate is worth stating plainly: skills and MCP servers installed at *user*
+scope are still in reach, because no harness here exposes a per-run flag that would suppress them.
+What goes away is this repository.
-<details>
-<summary><b>In-process TypeScript, no MCP</b></summary>
+### What the brief has to say
-```ts
-import { createKilnToolRegistry } from 'kiln/tools';
-```
+Four things, and each one is in there because leaving it out produced a bad run.
-`kiln/tools` imports no agent SDK, so porting to a harness that is not Strands does not drag Strands
-along. [`examples/strands-harness.ts`](examples/strands-harness.ts) is the whole integration in about
-sixty lines.
-</details>
+Absolute paths, everywhere. Every CLI resolves relative paths against something and it is rarely your
+working tree; `agy` resolves them against the installed plugin copy under
+`~/.gemini/config/plugins/kiln`. A brief that says `examples/foo.js` writes a file you will not find.
-The MCP server exposes the **raw tools**, which means *your* agent is the author — it writes the
-program, looks at the render, and iterates using its own model. No separate provider key, no nested
-agent loop.
+`kiln_list_primitives` before anything else. Without it the model writes the API it remembers from
+some other engine, and every call fails on a name that does not exist.
-Note that in this mode your harness supplies both the author and the vision judge. The
-deterministic gates still run independently, but the eyes/judge separation the production system
-maintained is collapsed. That is a deliberate trade for portability.
+An instruction to look at the render and fix what it sees. A model that is not told to look will
+write one pass, declare success, and stop. The loop is the entire argument for this tool, and codegen
+without it is not worth a round trip.
+
+A triangle budget. Unbounded, models either build twelve boxes or forty thousand triangles of
+greebling, and neither one is a game asset.
+
+### Pass the brief in a file, not on the command line
+
+`agy` mangles a multi-line `--print=` argument through a shell, npm-installed CLIs on Windows are
+`.cmd` shims that *require* a shell, and a shell cannot carry a multi-line argument. Writing the brief
+to a file and passing a one-line pointer sidesteps all of it, works identically on every harness and
+OS, and leaves the exact brief on disk next to the result.
+
+### What dispatching is actually for
+
+It is how you make a lot of assets. One dispatch is one asset, so a batch is a loop over briefs, and
+because the child verifies its own work against the same gates CI runs, the batch does not need
+watching: what comes back is either a program that passed or a log that says why it did not. Several
+of the assets in the gallery arrived that way while this README was being written.
+
+It is also the cheapest way to find out whether the documentation on this page is true. The first batch run
+against Gemini turned up a real engine bug inside one asset: `THREE.LatheGeometry` emits one ring of
+non-unit normals, which no raster ever shows you because a shader normalises before it lights, and
+which the glTF validator rejects outright. Every lathed cup and saucer in that model blocked the build
+at `final-glb`. Fixed in `src/ops.ts`, with
+[`src/__tests__/lathe-normals.test.ts`](src/__tests__/lathe-normals.test.ts) pinning it. Nothing
+in the hand-written examples had ever hit it, because none of them happened to lathe a profile
+whose last segment was short.
## Tool surface
| Tool | What it does |
|---|---|
| `kiln_list_primitives` | the primitive/helper catalog with signatures |
-| `kiln_validate` | AST validation — syntax, structure, infinite loops, recursion |
+| `kiln_validate` | AST validation: syntax, structure, infinite loops, recursion |
| `kiln_render` | build the scene, return metrics **and** the six-view sheet, in one call |
+| `kiln_edit` | patch an existing program with exact-string edits, and render the result |
| `kiln_screenshot_animation` | frames of an `animate()` program, so motion is visible too |
| `kiln_view_interior` | interior camera, for anything enterable |
| `kiln_inspect` | close-up orbit camera on a named part |
-Every one of these comes from a factory in [`src/tools/registry.ts`](src/tools/registry.ts); no
-transport hand-writes a definition, and `src/mcp-parity.test.ts` is what keeps that true.
-
-`kiln_render` here is the *unified* definition — the one that returns metrics and pixels together,
+`kiln_render` here is the *unified* definition, the one that returns metrics and pixels together,
accepts a custom camera capture, routes to the GPU when the scene needs PBR shading, and reports
-`viewFidelity` so the agent knows whether it may judge material from what it is looking at. The
-engine also carries a frozen four-tool bench baseline whose `kiln_screenshot` is CPU-only by
-construction; the in-process loop still runs that baseline plus a terminal `kiln_submit`. Shipping
-the baseline over MCP would have meant shipping a surface the render port can never reach.
+`viewFidelity` so the agent knows whether it may judge material from what it is looking at. The engine
+also carries a frozen four-tool bench baseline whose `kiln_screenshot` is CPU-only by construction;
+the in-process loop still runs that baseline plus a terminal `kiln_submit`. Shipping the baseline over
+MCP would have meant shipping a surface the render port can never reach.
+
+`kiln_edit` is the refine verb, and it exists because authoring an asset and changing one are not the
+same job. Without it, "make the roof taller" meant re-emitting the whole program through
+`kiln_render` and hoping the other two hundred lines came back the way they went in. It takes exact
+string replacements instead, applies them in order, refuses to guess when one matches twice, and
+applies nothing at all if any of them fails -- so a bad edit costs a retry rather than a program the
+model has to diff against its own intent. It returns the patched source, a unified diff, and the new
+contact sheet together, because the loop is edit-then-look. It holds no state between calls: the
+in-process agent keeps a working buffer across turns, but over MCP the host owns the program text,
+and putting a second copy inside the server would have created a desync the model cannot see.
## Subpath exports
@@ -303,7 +783,7 @@ The engine ships TypeScript source; consume by subpath:
| Import | What |
|---|---|
-| `kiln/tools` | the tool registry — the single source of truth, and free of any agent SDK |
+| `kiln/tools` | the tool registry, the single source of truth, free of any agent SDK |
| `kiln/agent` | the Strands agent loop, model factory, tool surface, edit buffer, unified diff |
| `kiln/render` | GLB build + serialize, grade/optimize/snap, `composeScene` |
| `kiln/views` | the pure-CPU six-view rasterizer + `node:zlib` PNG encoder |
@@ -314,21 +794,39 @@ The engine ships TypeScript source; consume by subpath:
| `kiln/palette` | canonical `OPTIMIZED_PALETTE` + directive (pure data, browser-safe) |
| `kiln/metrics`, `kiln/inspect` | instanceability grade + scene-structure analysis |
| `kiln/contracts` | asset and integration contracts, `IntegrationManifestV1`, semantic roles |
-| `kiln/composer` | THREE-free scene composition — layout, overlap resolution, scene DSL |
+| `kiln/composer` | THREE-free scene composition: layout, overlap resolution, scene DSL |
-Finished renders include `integrationManifest`, a versioned sidecar carrying the artifact hash,
-metres/+Y-up axes, bounds, grounding offset, default scene, role, render metrics, and structural QA.
-Consumers holding only GLB bytes can derive the same sidecar with `inspectGlbIntegration(bytes)`;
-that path parses the artifact and never executes model-authored source.
+Consumers holding only GLB bytes can derive the same integration sidecar with
+`inspectGlbIntegration(bytes)`; that path parses the artifact and never executes model-authored
+source. Visual quality stays explicitly `not_assessed` until something actually looks at the asset in
+its real scene, because structural validation is not a visual pass.
-Visual quality stays explicitly `not_assessed` until something actually looks at the asset in its
-real scene. Structural validation is not a visual pass.
+## How it is put together
+
+The architecture is the part most likely to be useful outside 3D.
+
+[`src/tools/registry.ts`](src/tools/registry.ts) is the single definition of every tool. The
+in-process Strands skin and the MCP server both iterate that registry rather than hand-writing their
+own schemas, so the two transports cannot drift apart, and `src/mcp-parity.test.ts` fails the build if
+they start to.
+
+Model judgment and deterministic judgment sit in separate layers on purpose. The gates run with no
+model call and no pixels; the model's vision is advisory on top of them. That ordering is what stops a
+confident wrong answer from promoting a broken asset, and it is why the gates keep working when the
+render degrades.
+
+`captureViewsViaPort` owns the render deadline, PNG validation, grid composition, and a fallback that
+never throws. Renderers are swappable behind it and correctness does not depend on which one ran.
+
+Budgets and compaction are first-class, because an agent loop that renders images runs out of context
+and money faster than one that does not, and both of those failures look like the model getting stupid
+rather than the loop running out of room.
## Determinism
-Render and rasterizer compute paths use no `Date.now()` or `Math.random()`, so CPU six-view output
-is byte-reproducible — the basis for golden-image tests. Inject seeds and timestamps at the
-boundary.
+Render and rasterizer compute paths use no `Date.now()` or `Math.random()`, so CPU six-view output is
+byte-reproducible, which is what makes golden-image tests possible at all. Inject seeds and timestamps
+at the boundary.
## Tests
@@ -338,45 +836,81 @@ bun run test # offline; live agent tests gated behind KILN_SPIKE_LIVE=
bun run test:coverage # LCOV plus the checked coverage ratchet
```
-Baseline is **95.38% functions / 91.80% lines** across 130 test files. CI enforces non-regression
-ratchets of 92% and 91% and uploads `coverage/lcov.info`.
-Threshold decreases require an explicit measured rationale.
-Tests pin `KILN_RENDER=cpu` so coverage cannot vary by runner GPU.
+1,549 tests across 144 files, at a measured **95.96% functions / 92.54% lines**. CI enforces
+non-regression ratchets of 92% and 91% and uploads `coverage/lcov.info`; threshold decreases require
+an explicit measured rationale. Tests pin `KILN_RENDER=cpu` so coverage cannot vary by runner GPU, and
+the example suite executes every checked-in program on every run, then checks this README's triangle
+counts against what actually came out.
## Dependencies
Runtime: `three`, `@gltf-transform/*`, `manifold-3d` (CSG, WASM), `three-subdivide`,
-`acorn`/`acorn-walk`, `zod`, plus lazy-loaded `sharp` (texture decode) and `xatlasjs` (UV atlas).
-The agent stack — `@strands-agents/sdk` + `@ai-sdk/provider` — is an **optional peer**: install it
-only if you use `kiln/agent`.
+`acorn`/`acorn-walk`, `zod`, plus lazy-loaded `sharp` (texture decode) and `xatlasjs` (UV atlas). The
+agent stack, `@strands-agents/sdk` + `@ai-sdk/provider`, is an **optional peer**: install it only if
+you use `kiln/agent`.
-Textures are eight [Poly Haven](https://polyhaven.com) CC0 families, embedded with source provenance
-retained. Runtime output is self-contained and never calls Poly Haven.
+Textures are sixteen [Poly Haven](https://polyhaven.com) CC0 families, embedded with source
+provenance retained. Runtime output is self-contained and never calls Poly Haven.
### `@ai-sdk/provider` is pinned to v3 by Strands, not by us
Do not bump `@ai-sdk/provider` to v4 or `@openrouter/ai-sdk-provider` to v3. Every
-`@strands-agents/sdk` version through 1.11.1 peers `@ai-sdk/provider@^3.0.0`, and its `VercelModel`
-is typed against `LanguageModelV3`. A cast does not help, because Strands emits V3 shapes at
-*runtime*: `vercel.js` sends `{type: 'file', data: <bare bytes>}` where V4 expects
-`{type: 'data', data}`, plus `{type: 'file-data', ...}`, which does not exist in V4 at all.
+`@strands-agents/sdk` version through 1.11.1 peers `@ai-sdk/provider@^3.0.0`, and its `VercelModel` is
+typed against `LanguageModelV3`. A cast does not help, because Strands emits V3 shapes at *runtime*:
+`vercel.js` sends `{type: 'file', data: <bare bytes>}` where V4 expects `{type: 'data', data}`, plus
+`{type: 'file-data', ...}`, which does not exist in V4 at all.
-v4 is purely additive and the only real change here would be one string in three files — which is
+v4 is purely additive and the only real change here would be one string in three files, which is
exactly why it looks deceptively easy. Stay on `@openrouter/[email protected]` until Strands
ships v4 support.
+## Contributing
+
+The most useful thing you can send is an asset that came out wrong.
+
+Every fix in `src/` worth having started as a render that looked stupid. `THREE.LatheGeometry`
+emitting one ring of non-unit normals, which no raster will show you and which the glTF validator
+rejects outright. Orthographic views framing at 45% fill because the camera fit was a guess against
+the bounding box rather than a projection of its corners. A quarter turn about Y sending an extruded
+profile's u to world -z, which sprang every flying buttress in the cathedral off the pier on the
+opposite side. None of those were found by reading the code.
+
+So point `node scripts/dispatch-asset.mjs` at a subject none of the examples covers. Whatever breaks
+is a bug report with a reproduction already attached, and if nothing breaks, the asset itself is worth
+a pull request.
+
+Places where another pair of hands would obviously help:
+
+- The GPU renderer speaks WebGPU through Dawn and nothing else. A Vulkan or Metal path widens
+ where it runs.
+- Claude Code, the Antigravity CLI, OpenCode, Hermes and Codex are verified end to end. Cursor and
+ Zed are documented from the MCP contract but unproven, and confirming either one is a contained,
+ high-value contribution.
+- Organic form is the weak axis, as the section above admits. A profile and sweep vocabulary that
+ handles soft shapes without a sculpt would move that boundary.
+- `kiln/arena` implements Bradley-Terry pairwise ranking for model bake-offs and has only ever been
+ pointed at a handful of providers. Anyone holding a key for a model not represented here can
+ produce a result nobody has.
+- More skills. The five that ship cover authoring, refining, composition, in-project QA, and batch
+ dispatch. Rigging, LODs, and material authoring are all unwritten.
+
+Before opening a pull request, `bun run lint`, `bun run typecheck` and `bun run test` must pass. CI
+pins `KILN_RENDER=cpu` so a runner that happens to have a GPU cannot change what the golden-image
+tests compare against. [`AGENTS.md`](AGENTS.md) is the operating manual if you want to point an agent
+at this repository, which is a reasonable thing to do here.
+
## History
-Kiln was a commercial text-to-3D product. It is shut down; this is the engine, which is the half
-that stays true regardless of how the product did.
+Kiln was a commercial text-to-3D product. It is shut down; this is the engine, which is the half that
+stays true regardless of how the product did.
-Some of the design here reflects constraints that no longer apply — most visibly the CPU rasterizer,
-which exists because the production agent runtime container had no GPU. Where an original decision
-made sense only for a hosted multi-tenant product, this repo does the thing that makes sense for an
+Some of the design reflects constraints that no longer apply, most visibly the CPU rasterizer, which
+exists because the production agent runtime container had no GPU. Where an original decision made
+sense only for a hosted multi-tenant product, this repository does the thing that makes sense for an
open one, and `docs/history/` records what the production system did and why.
-Initially extracted from the `pixel-forge` monorepo with file history preserved via
-`git subtree split`. See `CHANGELOG.md`.
+Initially extracted from the `pixel-forge` monorepo with file history preserved via `git subtree
+split`. See `CHANGELOG.md`.
## License
diff --git a/docs/history/production-architecture.md b/docs/history/production-architecture.md
index 90c0fbda..a7f49348 100644
--- a/docs/history/production-architecture.md
+++ b/docs/history/production-architecture.md
@@ -2,7 +2,7 @@
Kiln was a commercial text-to-3D product. It is shut down. This document records what the hosted
system looked like, because several decisions still visible in this repo only make sense against
-that background — and because the reasoning is the interesting part.
+that background -- and because the reasoning is the interesting part.
Nothing here is required to use the engine. It is history.
@@ -30,7 +30,7 @@ These are still in the code and still correct.
### The render port owns its own degrade
-`captureViewsViaPort` — in the engine, not the host — owns the deadline, PNG decode and count
+`captureViewsViaPort` -- in the engine, not the host -- owns the deadline, PNG decode and count
validation, grid composition, and a never-throw fallback to the CPU rasterizer. The host adapter
deliberately just builds a request, POSTs it, and maps the response; its thrown errors are
*intentional*, because the shell catches them.
@@ -50,9 +50,9 @@ non-deterministic eye out of the judge path is what makes the gates trustworthy.
### Two injection seams, two deadlines
-The port is injected twice. Once after the loop, for the artifact sheet — nothing waits on it, so a
+The port is injected twice. Once after the loop, for the artifact sheet -- nothing waits on it, so a
long deadline (120s in production) is correct. Once inside `kiln_render`, for the grid the model
-actually looks at — that one blocks the agent mid-thought, so it got 6s.
+actually looks at -- that one blocks the agent mid-thought, so it got 6s.
Collapsing those onto one value breaks one of the two jobs. In production, using the post-loop
deadline in-loop would have stalled every first render of a session, because serverless GPU cold
@@ -64,7 +64,7 @@ Originally the GPU ran only *after* the loop. That meant the model authored mate
see: it wrote `pbrMaterial(...)`, then checked its work against a flat-shaded image that cannot show
whether the result reads as wet stone or as plastic.
-Routing GPU renders into the loop fixed that, conditionally — `sceneNeedsPbrShading` checks bound
+Routing GPU renders into the loop fixed that, conditionally -- `sceneNeedsPbrShading` checks bound
textures and `metalness > 0`, and nothing else. Material *type* is deliberately not consulted,
because `gameMaterial` and `pbrMaterial` both construct a `MeshStandardMaterial` and are
indistinguishable after construction. Roughness is not a signal either, since `gameMaterial` sets it
@@ -95,7 +95,7 @@ browser: it shipped with `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1`, Playwright is uns
on Windows, and `headless-gl` is WebGL1 while three >= r163 requires WebGL2. So: a dependency-free
scanline z-buffer rasterizer, flat lambert, base color only.
-It turned out to be worth keeping for reasons that had nothing to do with the original constraint —
+It turned out to be worth keeping for reasons that had nothing to do with the original constraint --
it is deterministic, it needs no install, and it is sufficient for silhouette, proportion,
orientation, and contact. But it was never chosen as the better renderer, and this repo does not
pretend otherwise.
diff --git a/docs/install.md b/docs/install.md
index 18dc3e7c..ca86a67a 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -2,8 +2,9 @@
Kiln exposes one tool surface over two transports. Pick the one your harness speaks.
-Everything below needs [Bun](https://bun.sh) on `PATH` — the package ships TypeScript source rather
-than a build artifact, which is also why the entry point is a `.ts` file.
+Everything below starts with a clone and its dependencies, because the engine ships TypeScript
+source rather than a published package. [Bun](https://bun.sh) is the development toolchain and
+installs them.
```bash
git clone https://github.com/matthew-kissinger/kiln && cd kiln
@@ -20,29 +21,64 @@ That runs the full geometry build, the QA gates, and the rasterizer with no mode
GPU, and no key. If it produces a GLB and a contact sheet, the engine is fine and any later problem
is transport configuration.
+## The server runs on Node
+
+Every config on this page launches `dist/mcp-server.mjs` with `node`. That is a committed bundle,
+and both halves of that sentence were forced by real failures.
+
+It is **Node** because `"command": "bun"` asks the harness to resolve a name against its own PATH,
+and on Windows that is a coin flip: Bun's installer appends to the *User* PATH, and a process only
+ever sees the environment it was born with, so anything started before the install dies with
+`exec: "bun": executable file not found in %PATH%`. There is not one Bun-specific API on the
+server's runtime path, so bundling for Node takes Bun out of a user's requirements entirely.
+
+It is **committed** because a plugin install is a git clone with no build step, so an artifact that
+is built on demand is an artifact that is not there when the harness looks for it.
+
+Rebuild it with `bun run build:mcp` after changing anything under `src/`.
+[`src/__tests__/mcp-bundle.test.ts`](../src/__tests__/mcp-bundle.test.ts) rebuilds it, compares byte
+for byte against the committed copy, and then speaks real MCP to it under `node`, so a stale or
+broken bundle fails the suite rather than somebody's install.
+
## As an MCP server
-Point your client at `src/mcp-server.ts` with an **absolute** path. The server resolves every
+Point your client at `dist/mcp-server.mjs` with an **absolute** path. The server resolves every
internal path from `import.meta.url` and never reads `process.cwd()`, so the working directory the
-client launches it in does not matter — only that the script path is right.
+client launches it in does not matter -- only that the script path is right.
```json
{
"mcpServers": {
"kiln": {
"type": "stdio",
- "command": "bun",
- "args": ["run", "/absolute/path/to/kiln/src/mcp-server.ts"],
+ "command": "node",
+ "args": ["/absolute/path/to/kiln/dist/mcp-server.mjs"],
"env": { "KILN_RENDER": "auto" }
}
}
}
```
+Codex CLI keeps the same server in TOML at `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.kiln]
+command = "node"
+args = ["/absolute/path/to/kiln/dist/mcp-server.mjs"]
+env = { KILN_RENDER = "auto" }
+```
+
+Interactive `codex` asks before each MCP call and the server works as soon as the block above is in
+place. `codex exec` does not ask: it pins the approval policy to `never`, and under that policy an
+MCP call is refused rather than queued, so a scripted run reports that `kiln_list_primitives` was
+blocked and writes nothing. Pass `--approve-for-me`, which selects the workspace-write sandbox and
+routes approvals through automatic review. It cannot be combined with `--sandbox`, because it sets
+that itself.
+
Set `KILN_RENDER` to `cpu` to pin the deterministic rasterizer, or `gpu` to fail loudly rather than
degrade. `KILN_RENDER_PORT_URL` (plus `KILN_RENDER_TOKEN`) routes views to a GPU render service.
-**For textured or metallic assets, run the GPU renderer** — it ships in this repository:
+**For textured or metallic assets, run the GPU renderer** -- it ships in this repository:
```bash
cd render-service && npm install && npm start
@@ -52,7 +88,7 @@ It listens on `:8000`, which is where `auto` looks, so the MCP server picks it u
configuration. See [`render-service/README.md`](../render-service/README.md) and the render-modes
section of the [README](../README.md).
-Your agent gets six tools and is the author: it writes the program, looks at the render, and
+Your agent gets seven tools and is the author: it writes the program, looks at the render, and
iterates with its own model. There is no nested agent loop and no second provider key.
## As an Agent Plugin
@@ -60,23 +96,35 @@ iterates with its own model. There is no nested agent loop and no second provide
The repository is also a plugin package. Two manifest conventions exist as of late 2026 and Kiln
ships both, because they disagree on filenames and on the path variable:
-| | Portable spec | Claude Code | Antigravity |
+| | Claude Code | Antigravity | OpenCode |
|---|---|---|---|
-| Manifest | `plugin.json` | `.claude-plugin/plugin.json` | `plugin.json` (reuses the portable one) |
-| MCP config | `mcp.json` | inline `mcpServers` in the manifest | `mcp_config.json` |
-| Plugin-root variable | `${PLUGIN_ROOT}` | `${CLAUDE_PLUGIN_ROOT}` | none — absolute paths |
-| Skills | `skills/<name>/SKILL.md` | same | same |
+| Manifest | `.claude-plugin/plugin.json` | `plugin.json` (the portable spec, reused) | none -- no plugin manifest exists |
+| MCP config | inline `mcpServers` in the manifest | `mcp_config.json` | user's `opencode.json`, under `mcp` |
+| Plugin-root variable | `${CLAUDE_PLUGIN_ROOT}` | none -- absolute paths | none -- absolute paths |
+| Consumed today? | yes | no -- see below | yes, via config rather than install |
+| Skills | `skills/<name>/SKILL.md` | same | same files, copied into a skills directory |
+
+A third filename, a bare `mcp.json` at the repository root, is specified by the portable Agent
+Plugin spec and is read by none of the three. It used to ship here and was removed once that was
+measured rather than assumed.
The skills are the same files in both cases. Installing the plugin gives you the MCP tools *and*
-the three skills that teach an agent to use them well:
+the five skills that teach an agent to use them well:
| Skill | When it fires |
|---|---|
-| `kiln-author-asset` | create, model, build, or refine an asset |
+| `kiln-author-asset` | create, model, or build an asset that does not exist yet |
+| `kiln-refine-asset` | change an asset that already has a program, by patching it |
| `kiln-qa-asset` | wire a finished GLB into a real project and prove it works |
| `kiln-compose-scene` | lay out several finished GLBs into one scene |
+| `kiln-batch-dispatch` | wire another harness up, or generate a whole library at once |
+
+Together their front matter is 1,698 characters, about four hundred tokens of always-on context;
+the bodies load only when a skill fires.
-Together they cost about 215 tokens of always-on context; the bodies load only when a skill fires.
+`kiln-batch-dispatch` is the odd one out: the other four are read by the agent building the asset,
+and that one is read by whoever is pointing agents at the problem. It covers the rest of this page
+as a procedure, the smoke test below, and the clean-room dispatcher the gallery was built with.
### Claude Code
@@ -85,7 +133,7 @@ claude plugin marketplace add matthew-kissinger/kiln
claude plugin install kiln@kiln
```
-Verify with `claude mcp list` — you want `plugin:kiln:kiln … ✔ Connected`.
+Verify with `claude mcp list` -- you want `plugin:kiln:kiln … ✔ Connected`.
Claude Code's MCP config is declared **inline in `.claude-plugin/plugin.json`** rather than in a
root `.mcp.json`. That is deliberate: `.mcp.json` at a repository root is also Claude Code's
@@ -93,9 +141,33 @@ root `.mcp.json`. That is deliberate: `.mcp.json` at a repository root is also C
every contributor who opens this repo a broken server entry and a warning. Declaring it in the
manifest works identically for installed users and leaves the repo clean for contributors.
+#### Headless permissions
+
+`claude -p` cannot prompt either, and `--permission-mode acceptEdits` is not enough on its own: it
+grants writes and says nothing about MCP tools, so a run that reaches for `kiln_render` blocks on a
+confirmation with no terminal attached. What comes back is a clean exit, no file, and a polite note
+explaining which permissions the model would have needed.
+
+Grant the server in a settings file the run will read -- the working directory's
+`.claude/settings.json` is enough, and keeps the grant scoped to that directory:
+
+```jsonc
+// <working directory>/.claude/settings.json
+{
+ "permissions": {
+ "allow": ["mcp__kiln", "mcp__plugin_kiln_kiln", "Read", "Write", "Edit", "Glob", "Grep"]
+ }
+}
+```
+
+Naming the server twice is not redundant: the tool prefix depends on how Kiln was installed, and it
+is `plugin_kiln_kiln` for a plugin install and `kiln` for a plain `claude mcp add`. Allowing the
+server allows its tools. `scripts/dispatch-asset.mjs` writes exactly this file into each sandbox,
+which is why an unattended batch does not need `--dangerously-skip-permissions`.
+
### Antigravity (`agy`)
-Antigravity accepts the portable `plugin.json` unchanged — no Google-specific manifest is needed,
+Antigravity accepts the portable `plugin.json` unchanged -- no Google-specific manifest is needed,
which is the whole point of shipping to a spec:
```bash
@@ -103,28 +175,38 @@ agy plugin validate . # ok - 3 skills, 1 mcpServer
agy plugin install .
```
-That installs the skills. **Getting the tools attached takes one more step**, for two reasons worth
-knowing before you start:
+That installs the skills, and only the skills. **Getting the tools attached takes one more command**,
+and the reason is worth knowing because the failure is silent and the diagnostics contradict each
+other. Measured on `agy` 1.1.25: the CLI finds a plugin's `mcp_config.json` and reports it,
-1. Antigravity documents no plugin-root path variable, so a `${PLUGIN_ROOT}` in a plugin's
- `mcp_config.json` does not expand.
-2. As of `agy` 1.1.15 a plugin's `mcp_config.json` is staged but not merged into the session's
- server list.
+```
+agy plugin validate .
+ [ok] .
+ skills : 3 processed
+ mcpServers : 1 processed
+```
-So register the server in Antigravity's central config, `~/.gemini/config/mcp_config.json`, with an
-absolute path — this is the file the CLI, the IDE, and Antigravity 2.0 all share:
+and then never merges it into the session:
-```json
-{
- "mcpServers": {
- "kiln": {
- "command": "bun",
- "args": ["/absolute/path/to/kiln/src/mcp-server.ts"],
- "env": { "KILN_RENDER": "auto" }
- }
- }
-}
```
+agy mcp list
+ No MCP servers configured.
+```
+
+The agent sees no tools, while `plugin validate` insists the server was processed. Uninstalling and
+reinstalling the plugin does not change it, and neither does the path variable, which is why this
+page no longer suggests hand-editing a config file at all. Register the server with the CLI's own
+command:
+
+```bash
+agy mcp add --env KILN_RENDER=auto kiln node /absolute/path/to/kiln/dist/mcp-server.mjs
+agy mcp list # kiln stdio enabled node /absolute/path/to/kiln/dist/mcp-server.mjs
+```
+
+That writes the entry into `~/.gemini/config/mcp_config.json` itself -- the file the CLI, the IDE
+and Antigravity 2.0 share -- so there is no JSON to get wrong. Kiln still ships a correct
+`mcp_config.json` in the plugin root, pointed at the same bundle, so that the day `agy` starts
+merging it the plugin works with one command instead of two.
Remote servers use `serverUrl` rather than `url` or `httpUrl`, which are not supported.
@@ -155,8 +237,8 @@ A second file, `~/.gemini/config/config.json`, contributes *shared* grants under
`--log-file` and those two lines tell you what the CLI actually parsed.
**`command` is the one rule kind that does not accept a target in headless mode.** The documented
-syntax — each whitespace-separated token as an anchored regex, e.g. `command(git)` or
-`command(npm run (build|lint|test))` — parses correctly and still gets denied:
+syntax -- each whitespace-separated token as an anchored regex, e.g. `command(git)` or
+`command(npm run (build|lint|test))` -- parses correctly and still gets denied:
```
tool_confirmation_manager.go:188] Print mode: soft-denying tool confirmation "RunCommand" at step 2
@@ -164,7 +246,7 @@ tool_confirmation_manager.go:188] Print mode: soft-denying tool confirmation "Ru
Only `command(*)` passes. This is upstream
[antigravity-cli#548](https://github.com/google-antigravity/antigravity-cli/issues/548). Scope the
-blast radius with `trustedWorkspaces`, a path-scoped `write_file`, and a `deny` list instead —
+blast radius with `trustedWorkspaces`, a path-scoped `write_file`, and a `deny` list instead --
those are honoured. `mcp(kiln/*)` and `write_file(<abs path>)` were both verified working in
headless mode with the shared wildcard removed, so scope everything you can and treat `command(*)`
as the known exception rather than the default.
@@ -180,7 +262,214 @@ Three more sharp edges:
`README.md` reads the wrong file.
Verified end to end with Gemini 3.8 Flash, which authored
-[`examples/arcade-cabinet.kiln.js`](../examples/arcade-cabinet.kiln.js) through this path.
+[`examples/radio-telescope.kiln.js`](../examples/radio-telescope.kiln.js) through this path -- and
+six more of the gallery besides. Every program it wrote says so on its first line.
+
+### OpenCode
+
+OpenCode is the odd one out in a useful way: it has a skills system that reads Anthropic's
+`SKILL.md` layout unchanged, and a plugin system that has nothing to do with either. OpenCode
+plugins are JavaScript modules that hook into events; there is no manifest, no marketplace and no
+install command that would consume this repository's `plugin.json`. So the MCP server is wired up
+through config, and the skills are copied.
+
+The MCP half goes in `~/.config/opencode/opencode.json` (global) or an `opencode.json` at a project
+root. Both accept JSONC, and `OPENCODE_CONFIG` overrides the path:
+
+```json
+{
+ "$schema": "https://opencode.ai/config.json",
+ "mcp": {
+ "kiln": {
+ "type": "local",
+ "command": ["node", "/absolute/path/to/kiln/dist/mcp-server.mjs"],
+ "enabled": true,
+ "environment": { "KILN_RENDER": "auto" },
+ "timeout": 30000
+ }
+ }
+}
+```
+
+Four differences from the shape every other client on this page uses, all of them silent failures if
+you paste someone else's config:
+
+- the top-level key is `mcp`, not `mcpServers`
+- `type` is `"local"`, not `"stdio"`
+- the interpreter and its arguments are one `command` array, not `command` plus `args`
+- environment variables live under `environment`, not `env`
+
+The schema sets `additionalProperties: false`, so a leftover `args` or `env` key is rejected rather
+than ignored. That is a kindness; it fails loudly at load instead of quietly at use.
+
+`timeout` bounds the connection handshake rather than the tool calls that follow. The name invites
+the other reading, so it is worth stating what was measured: at 200 ms the server does not connect
+and `opencode mcp list` reports `kiln failed`, while at 1500 ms it connects and a `kiln_render` call
+taking nine seconds still returns its picture. The handshake measured about 1.2 seconds against a
+5000 ms default, so the default is already sufficient and an explicit value only covers a slow cold
+start.
+
+Verify:
+
+```bash
+opencode mcp list
+```
+
+You want `kiln connected` and the command line echoed back.
+
+Then the skills. OpenCode searches `~/.config/opencode/skills/`, `~/.claude/skills/` and
+`~/.agents/skills/` globally, and `.opencode/skills/`, `.claude/skills/` and `.agents/skills/` per
+project. The files here need no modification:
+
+```bash
+cp -r skills/* ~/.config/opencode/skills/
+```
+
+**Raise the output cap before you judge a model by its assets.** OpenCode limits a single assistant
+step to 32,000 output tokens by default, whatever the model's own ceiling is. Measured across every
+step in its session store, nothing had ever exceeded that number -- not once, not by a single token
+-- while the models involved publish limits between 80,000 and 943,718. A model that plans at length
+before it writes hits the cap mid-sentence, and the run ends with no file and no error: four separate
+runs, from three vendors, died exactly there. Lift it to the model's own published limit:
+
+```bash
+OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX=128000 opencode run --auto -m opencode-go/<model> "..."
+```
+
+[`scripts/dispatch-asset.mjs`](../scripts/dispatch-asset.mjs) sets this per run, reading each model's
+declared limit out of OpenCode's own model catalog so the ceiling is the provider's rather than one
+picked here.
+
+Two things to expect in a transcript. Tools are namespaced by server, so `kiln_render` is presented
+as `kiln_kiln_render` -- harmless, and models locate the tools regardless, but it makes the skill
+prose and the tool list look inconsistent. And OpenCode reaches many vendors' models behind
+`provider/model` ids, so `opencode models` is worth reading before choosing one; asset quality
+tracks the model far more than it tracks the harness.
+
+### Codex CLI
+
+Codex has a marketplace-shaped plugin system that reads this repository's manifest unchanged, so the
+install itself is two familiar commands:
+
+```bash
+codex plugin marketplace add matthew-kissinger/kiln # or a local path
+codex plugin add kiln@kiln
+```
+
+`codex plugin list` will then show `kiln@kiln installed, enabled`, and the whole tree is copied into
+`~/.codex/plugins/cache/kiln/kiln/<version>`.
+
+**That install does not give the agent the tools.** As of Codex 0.153.3, an installed and enabled
+plugin's MCP servers are not registered: with the plugin enabled and no server entry in config, a run
+asked to name its `kiln_*` tools answers `NONE`. Its skills do not arrive either. Register the server
+yourself, exactly as in the MCP section above:
+
+```toml
+[mcp_servers.kiln]
+command = "node"
+args = ["/absolute/path/to/kiln/dist/mcp-server.mjs"]
+env = { KILN_RENDER = "auto" }
+```
+
+`codex mcp list` should then show `kiln … enabled`. This is the same trap `agy` sets, and it fails
+the same silent way: everything reports success and the agent simply has no tools.
+
+Interactive `codex` asks before each tool call and works from there. `codex exec` does not ask -- it
+pins the approval policy to `never`, and a `never` policy **refuses** an MCP call rather than
+queueing it, so a scripted run comes back in well under a minute saying `kiln_list_primitives` was
+blocked and having written nothing at all. Pass `--approve-for-me`, which routes approvals through
+automatic review and selects the workspace-write sandbox itself. It is rejected alongside
+`--sandbox`, because it sets that:
+
+```bash
+codex exec --approve-for-me --skip-git-repo-check --cd /abs/path/to/sandbox "..."
+```
+
+Because plugin skills do not load, a dispatched run reaches them as files: the sandbox carries a copy
+of `skills/` and the brief names the skill it wants. That is enough -- the child finds and reads it --
+but it is worth knowing that the skill is being read rather than installed.
+
+Codex also rejects a model id newer than the CLI (`The 'gpt-6-astra' model requires a newer version of
+Codex`), which reads like an entitlement problem and is not one. Update the CLI first.
+
+### Hermes
+
+Hermes is the harness that makes the portability claim worth stating. The other four are JavaScript
+CLIs with broadly similar ideas about plugins; 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 any of them. It
+takes the same server and the same skills unchanged.
+
+Two commands, both writing to `~/.hermes/config.yaml` (`%LOCALAPPDATA%\hermes\config.yaml` on
+Windows):
+
+```bash
+hermes mcp add kiln --command node --args /absolute/path/to/kiln/dist/mcp-server.mjs --env KILN_RENDER=auto
+hermes config set skills.external_dirs /absolute/path/to/kiln/skills
+```
+
+The first connects on the spot, prints the seven tools it found, and asks whether to enable them --
+a prompt that wants a terminal, so pipe a `y` into it from a script. The second is the entire skills
+story: Hermes does not read `.claude/skills` out of the working directory the way the other four do,
+it reads a list of absolute directories out of its config, and pointing that list at this
+repository's `skills/` is enough. Verify both:
+
+```bash
+hermes mcp list # kiln node …/dist/mcp-server.mjs all enabled
+hermes skills list # five kiln-* rows, source `local`
+```
+
+`-z` is the headless mode the dispatcher uses: one prompt in, the final response text out, no banner,
+and tool approvals resolved without asking. There is no working-directory flag, so the sandbox is
+simply the directory the process is spawned in -- which is also where Hermes reads `AGENTS.md` from,
+so the clean room holds.
+
+Hermes is a client rather than a model vendor, and it ships with no provider at all. Until it has
+one, every run fails with `No inference provider configured` before the model sees a single token of
+the brief, which looks exactly like the silent wiring failures this page keeps warning about.
+`hermes status` lists the key slots it knows. Its own first-party login is Nous Portal:
+
+```bash
+hermes auth add nous --type oauth
+hermes config set model.provider nous
+hermes config set model.base_url https://inference-api.nousresearch.com/v1
+hermes config set model.default <model id>
+```
+
+The last three lines are not optional after the login, and skipping them produces the most confusing
+state on this page: the credential is stored and `hermes status` reports `Nous Portal logged in`,
+while `model.base_url` still points wherever it pointed before and every run dies on `No LLM provider
+configured`. The catalog is public and OpenAI-shaped, so
+`curl https://inference-api.nousresearch.com/v1/models` will tell you the ids, their pricing and
+which ones accept tools without needing a key.
+
+## Checking that it worked
+
+Every wiring failure on this page is silent. A harness that cannot see the server does not say so,
+and neither does one that can see it but will not grant it -- the agent simply answers as though the
+tools were never mentioned, which is indistinguishable from a model that was not up to the job. So
+do not infer from a bad asset that your model is weak. Check the wiring first:
+
+```bash
+bun run smoke:harness
+```
+
+It runs every CLI it finds on your PATH, and for each one sends a short brief into a throwaway
+directory: call `kiln_list_primitives`, write a four-line program, validate it. Then it builds what
+came back with the engine itself, because the child's own report of success is the one piece of
+evidence that proves nothing.
+
+```
+agy ok 105s gemini-3.8-flash-high built 12 tris
+claude ok 13s sonnet built 12 tris
+codex ok 37s (configured default) built 12 tris
+hermes ok 97s (configured default) built 12 tris
+opencode ok 52s opencode-go/glm-5.3-flash built 12 tris
+```
+
+A harness you have not installed is skipped rather than failed. `--harness <name>` checks one,
+`--model <id>` overrides the model, and a failure prints the last of the agent's output and the path
+to the sandbox, which is left on disk so you can read the brief it was given and whatever it wrote.
+
## In-process, without MCP
@@ -194,5 +483,5 @@ import { createKilnToolRegistry } from 'kiln/tools';
`kiln/tools` is the framework-agnostic core and imports no agent SDK, so porting to a harness that
is not Strands does not drag Strands along. Each def carries `name`, `description`, a zod
-`inputSchema`, and `run`. Mapping those four fields is the entire adapter — `src/mcp-server.ts` is
+`inputSchema`, and `run`. Mapping those four fields is the entire adapter -- `src/mcp-server.ts` is
one such adapter and `src/agent/tools.ts` is another.